
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.
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
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.
- The VM boots. Its agent dials out to the relay and claims the slot.
- 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.
- 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.