runlease

module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0

README

runlease

Spot machines for coding agents. Cheap, safe, and in your own cloud.
Your keys never leave your machine, the relay cannot read your traffic, and every machine deletes itself.

CI Release Go Reference

Built by Marshal: AI coding agents at full speed, with full receipts.
Marshal runs coding agents in isolated pods inside your own VPC. Runlease is the tool we built to give them, and our tests, a real machine for an hour.

runlease up --provider gcp --size compute.large --ttl 2h   # a spot VM in your account
runlease exec <name> -- make test                          # run something on it
runlease down <name> --yes                                 # or let the lease delete it

One command gives an agent, a CI job or you a real Linux machine. It runs in your cloud account at spot prices, has no public address, and deletes itself when its lease runs out.


Why

Coding agents need somewhere to run things: build the project, start the stack, run the tests, break something and try again. A laptop is the wrong place and a long-lived dev box is worse.

Yours The VM runs in your own GCP or AWS account, on your network, under your IAM. Nothing is hosted for you and nothing leaves your account.
Cheap Spot capacity. runlease up shows the hourly price and the projected cost of the lease before it launches.
Closed By default the VM has no public address and its SSH server listens on localhost only. The VM dials out to a relay; you reach it through that tunnel.
Private The relay carries SSH. It holds no keys and cannot read, alter or impersonate a session. How that works.
Managed Every machine has a lease. It deletes itself at the end of it, whether or not your laptop is still online.
Scriptable --output json on every command, non-interactive exec, push, pull and forward. Built to be driven by an agent.

Install

curl -fsSL https://runlease.online/install.sh | sh

The script downloads the release for your machine, checks its SHA-256 against checksums.txt, and puts runlease in ~/.local/bin. It uses no sudo. To do the same by hand:

VERSION=v0.5.0   # pick the latest
OS=linux ARCH=amd64   # or darwin / arm64
curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/runlease-${OS}-${ARCH}"
curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
install -m 0755 "runlease-${OS}-${ARCH}" ~/.local/bin/runlease

Releases are signed. See verifying a release.

Or build from source (Go 1.26 or newer):

go install github.com/marshal-org/runlease/cmd/runlease@latest

A source build does not carry the agent checksum that release builds do. Read agent verification before using one against a relay you do not run yourself.

Quick start

You need credentials for one cloud: gcloud auth application-default login for GCP, or the usual AWS credential chain.

runlease configure                      # provider, region, relay, default size and lease
runlease up                             # launch with your defaults
runlease exec <name> -- make test       # run something
runlease forward <name> -L 8080:localhost:8080   # reach a port on the VM
runlease push <name> ./build.tar /tmp/build.tar
runlease snooze <name> 1h               # extend the lease
runlease down <name>                    # delete it now

For anything repeatable, describe the machine in a manifest:

# agent-box.yaml
name: agent-box
provider: gcp
region: us-central1-a
instanceClass: compute.large
reclaim:
  ttl: 3h
  selfTermination: true
relay:
  addr: wss://relay.example.com
setup:
  - name: toolchain
    run: |
      apt-get update && apt-get install -y build-essential git
forwards:
  - local: 3000
    remote: 3000
runlease up -m agent-box.yaml --attach

runlease manifest new writes one interactively. Every field is in the manifest reference.

Finding machines this computer has forgotten

runlease list shows what this computer launched and still remembers. It also asks your cloud for every machine carrying the runlease-managed label, and lists the ones it does not track: launched from another computer, or left behind stopped with a disk that still bills.

runlease list             # tracked machines, then anything found in the cloud
runlease down --leaked    # delete the stopped ones whose lease is over
runlease list --local     # skip the cloud lookup

down --leaked never deletes a running machine. It only removes machines that are stopped and past their lease.

How it works

flowchart LR
    subgraph You["You, an agent, or CI"]
        CLI["runlease CLI<br/>holds the SSH keys"]
    end
    R[("Relay<br/>holds no keys")]
    subgraph Cloud["Your cloud account"]
        subgraph VM["Spot VM, dials out"]
            A["runlease-agent"] --> S["sshd"]
        end
    end
    CLI -- "SSH inside a WebSocket" --> R
    A -- "dials out" --> R
  1. runlease up generates two key pairs on your machine: one to log in with, and the VM's SSH host key. It also picks a random 256-bit slot token and registers it with the relay.
  2. The VM boots. Its agent dials out to the relay and claims the slot.
  3. Every command you run opens an SSH session through the relay to the VM's sshd. The CLI accepts only the host key it generated in step 1, so the relay cannot stand in for the VM.
  4. A timer inside the VM deletes the instance when the lease ends.

The full walk-through, with the protocol and the boot sequence, is in docs/how-it-works.md.

Security

Runlease is built so that the one shared, internet-facing piece, the relay, is not something you have to trust with your sessions.

  • The relay never holds an SSH key, a cloud credential or plaintext.
  • Host keys are issued before boot. Nothing is trusted on first use.
  • The agent binary is checked against a SHA-256 compiled into the CLI before it runs.
  • The agent runs unprivileged in a locked-down systemd unit. sudo on the VM is off unless the manifest turns it on.
  • On AWS, instances require IMDSv2.

The threat model says exactly what each party can and cannot do, and lists the limits we know about. To report a vulnerability, see SECURITY.md.

The relay

A relay is one small Go binary. You have three choices:

  • Use the public one. Free, with a Google sign-in and a limit of two machines at once:

    runlease config set relay.addr wss://connect.runlease.online
    runlease login
    

    What it allows and what it sees: the public relay.

  • Run your own. It takes one VM or container and a TLS endpoint. See self-hosting the relay. This is what we recommend for real work.

  • No relay at all. Leave relay.addr empty and Runlease gives the VM a public IP and connects directly, or use runlease iap (GCP) or runlease ssm (AWS).

Clouds

Cloud Status
Google Cloud Supported
AWS Supported
Azure, others Not implemented. The provider interface is four methods, and a new provider is a good first contribution.

Machine sizes are portable: compute.small to compute.2xlarge and compute.gpu map to a concrete type per cloud. Run runlease catalog to see the mapping.

Documentation

How it works Architecture, protocol, boot sequence, lease lifecycle
Security and threat model What each party can do, known limits, release verification
Manifest reference Every field
The public relay Sign in, free tier limits, what it logs
Self-hosting the relay Deploy, authenticate, set tiers, operate
CI and release pipeline How changes are tested and how releases are built and signed

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md. Changes to the relay, the boot script or credential handling get an extra-careful review; the pull request template says what we look for.

This project follows the Contributor Covenant.

Status

Pre-1.0. The CLI and the manifest format can still change between minor versions; the changelog calls out every breaking change.

License

Apache License 2.0.

Built by Marshal

Runlease is built and maintained by Marshal. Marshal runs AI coding agents in isolated pods inside your own VPC, with credential isolation, audited egress and live tool policies.

Runlease stands alone: you do not need Marshal to use it. We built it to give agents and tests a real machine for an hour, and we use it ourselves.

Directories

Path Synopsis
cmd
runlease command
runlease-agent command
runlease-agent runs on each launched instance.
runlease-agent runs on each launched instance.
runlease-relay command
pkg
agent
Package agent holds the runlease-agent core loop, factored out of the main binary so it can be exercised by integration tests.
Package agent holds the runlease-agent core loop, factored out of the main binary so it can be exercised by integration tests.
pricing
Package pricing resolves spot/preemptible hourly rates for launched instances using the caller's own cloud credentials (the same ADC / AWS default chain the provider packages use).
Package pricing resolves spot/preemptible hourly rates for launched instances using the caller's own cloud credentials (the same ADC / AWS default chain the provider packages use).
signin
Package signin signs a person in to a relay with their Google account and keeps the resulting session on disk.
Package signin signs a person in to a relay with their Google account and keeps the resulting session on disk.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL