
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.7.1 # 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 (and
gcloud config set project MY_PROJECT) for GCP, or the usual AWS credential chain.
runlease login # the free public relay: approve a short code in a browser
runlease doctor # optional: checks sign-ins, project and network, prints the fix
runlease up -p gcp -n box -d # or -p aws: a small spot machine, gone in two hours
# no NAT gateway on the subnet? it stops and says so: add --public-ip
runlease exec box -- uname -a # run something
runlease connect box # or open a shell
runlease forward box -L 8080:localhost:8080 # reach a port on the VM
runlease push box ./build.tar /tmp/build.tar
runlease snooze box 1h # extend the lease
runlease down box --yes # delete it now
Run runlease configure once to save a default cloud, region and size; after that a bare
runlease up is enough.
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.
For coding agents: the MCP server
runlease mcp serves the same commands as typed tools over the
Model Context Protocol, so an agent launches, uses and deletes
machines without composing shell commands:
claude mcp add runlease -- runlease mcp # Claude Code
Any other MCP client takes {"command": "runlease", "args": ["mcp"]}. The tools and the safety
notes are in docs/mcp.md.
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
runlease down --leaked --provider aws --region eu-north-1 # say where to look: an AWS region
runlease down --leaked --provider gcp --project my-project # or a Google Cloud project, all zones
down --leaked never deletes a running machine. It only removes machines that are stopped and
past their lease.
Both look where this computer has launched before and in its saved default. With neither,
down --leaked and list --untracked look in each cloud signed in on this computer, in its
default place. down --leaked always prints where it is looking first, by name: the project ID,
or the region and account.
It deletes without asking (--yes, or --output json) only in a place that was named: by the
flags above, by a machine this computer tracks, or by the saved default. In a place it had to
fill in, it lists what it found, deletes nothing, and prints the command that names the place.
When something is not working
runlease doctor # every cloud signed in on this computer
runlease doctor --provider aws --region eu-north-1 # one cloud, one region
runlease doctor --output json # {"ok": bool, "checks": [{id, title, status, detail, fix}]}
runlease doctor creates nothing. It checks this CLI, the relay (set, reachable, signed in,
serving the agent this CLI expects) and each cloud (credentials, project or account, region,
network, NAT gateway), runs every check whatever the one before it found, and prints the
command that fixes each problem. It exits 1 if a check failed; a warning, such as a subnet
with no NAT gateway, does not fail it.
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.
For Claude Code
A plugin gives Claude Code the skills to use Runlease on its own, slash commands, typed tools, and
a live view of what is running:
/plugin install runlease --marketplace marshal-org/runlease
What it adds and what it holds Claude to: the Claude Code plugin.
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 login # with no relay set, this picks the public one and saves it
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 |
| MCP server |
runlease mcp: typed tools for coding agents, how to register it, safety notes |
| 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.
Running agents for a whole team? Runlease gives one agent one machine. When you need policy,
audit and isolation across many agents and many people, see Marshal
or book a demo.
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.