How it works
Three small programs. One of them is deliberately kept in the dark.
The CLI holds the keys and opens every session. The agent sits on the VM and dials out. The relay introduces them and then only copies bytes.
The parts
| Program | Runs on | Does |
|---|---|---|
runlease | Your machine, an agent's sandbox, or CI | Launches VMs through the cloud API, holds the keys, and opens every session |
runlease-agent | Each VM | Dials out to the relay and hands incoming streams to sshd on localhost |
runlease-relay | One small server with a public TLS endpoint | Matches CLI connections to the right agent and copies bytes between them |
A launch, step by step
What runlease up does, in order, and who does each part.
- CLI
Makes the keys. Two ed25519 key pairs for this VM. One logs you in. The other is the VM's SSH host key, chosen by you before the VM exists.
- CLI
Makes a slot token, 256 random bits.
- CLI → relay
Registers the slot, proving who you are with your sign-in. The relay only ever accepts connections for tokens registered this way. If your tier is full, it says so here, before any VM is created.
- CLI → cloud
Requests a spot VM with a boot script attached. The script holds your public login key, the host key pair, the relay address and the slot token.
- CLI
Saves the keys, encrypted, under
~/.runlease. - VM
Boots. Arms the lease timer first. Installs the host key, hardens
sshd, downloads the agent, checks its SHA-256, and starts it as an unprivileged service. - VM → relay
The agent dials out and claims the slot.
- CLI → relay
The CLI connects for the same slot. The relay joins the two connections.
- CLI ↔ VM
SSH runs across the joined connection. The CLI accepts exactly one host key: the one from the first step.
Sessions
The agent keeps one connection to the relay and multiplexes any number of sessions over it. Each command you run opens its own connection to the relay, which becomes a new stream to the agent, which becomes a new TCP connection to sshd on the VM.
That is why you can hold a port forward open in one terminal and run exec, push and pull from others at the same time.
$ runlease forward agent-box -L 8080:localhost:8080 # terminal one, stays open $ runlease exec agent-box -- make test # terminal two $ runlease pull agent-box /var/log/app.log ./app.log # terminal three
A slot lives for at most 24 hours, or less if the relay's tier says so. If the agent's connection drops, it reconnects and reclaims the same slot. Only one agent can hold a slot at a time.
Signing in
A relay decides who may open a slot from a Google ID token.
runlease loginshows a short code. You approve it in a browser on any device, and the CLI saves the session in~/.runlease/auth.json. Nothing has to open on the machine you are working on, so it works over SSH, in a container, and for an agent whose human is at another screen.- Without a saved session the CLI falls back to an identity token from a service account or from
gcloud, which is what a private relay usually expects.
The relay verifies Google's signature on the token and that the email is verified, then looks up the limits for that identity. Agents and later connections do not sign in. They present the slot token, which only works for a slot that a signed-in identity opened.
Inside the VM
The boot script does this, in order:
- Installs
runlease-terminateandrunlease-snooze, the only two commands the login user may run as root. - Arms a systemd timer that runs
runlease-terminateat the end of the lease. - Creates the
runlease-agentuser and installs your public login key. - Installs the pre-issued host key and removes every other host key.
- Hardens
sshd: public-key only, one allowed user, no root login. - Grants general
sudoonly if the manifest sayssudo: passwordless. - Downloads the agent, verifies its SHA-256, and starts it under a restricted systemd unit.
- Runs your
setupsteps as root, logging to/var/log/runlease-setup.log.
The lease timer is armed in step 2, before anything that can fail. A VM whose setup breaks still deletes itself.
Leases
Every machine has an expiry. There are four ways a machine ends, and only one of them needs you.
| What ends it | Who acts |
|---|---|
| The lease timer fires | The VM deletes itself |
runlease down | You |
| The cloud reclaims the spot capacity | Your cloud provider |
runlease daemon sees an expired lease | A watcher on your side |
reclaim.ttlin the manifest sets the lease, and the timer inside the VM is armed by default. The deadline is kept on the VM's disk and re-armed at every boot, so a reboot does not lose it.runlease snooze NAME 1hmoves the timer, over the same secure channel.- On GCP the VM deletes itself through the Compute API. On AWS it powers off, and the instance is configured to terminate on shutdown.
- Every VM is tagged
runlease-managed,runlease-created-byandrunlease-expires-at.
On your machine
Runlease keeps its state under ~/.runlease. Set RUNLEASE_HOME to move it.
| File | Holds |
|---|---|
config.yaml | Your defaults |
registry.json | One entry per launched VM: cloud, instance ID, relay address, slot token, forwards |
credentials/<id>.json | That VM's key pairs, encrypted with AES-256-GCM |
master.key | The key that encrypts them, readable only by you |
auth.json | Your relay sign-in, readable only by you |
Without a relay
Leave relay.addr empty and the CLI connects straight to the VM's public address, still with the pre-issued host key. runlease iap on GCP and runlease ssm on AWS use the cloud's own tunnel instead.
The relay protocol
Everything is a WebSocket to /relay. The first message is one line of JSON. After it, the connection is a plain byte stream.
| Role | Sent by | First message | Then |
|---|---|---|---|
register | CLI at up | {"role":"register","token":"…"} with your sign-in as a bearer token | Replies ok, or limit when your tier is full, and closes |
instance | Agent at boot | {"role":"instance","token":"…"} | The agent serves multiplexed streams on this socket |
client | CLI, every command | {"role":"client","token":"…"} | Raw bytes, joined to a new stream on the agent's socket |
release | CLI at down | {"role":"release","token":"…"} | The slot is freed at once |
| HTTP endpoint | Purpose |
|---|---|
GET /agent | Serves the agent binary, which the VM then verifies |
GET /ready | Whether a slot's agent is connected |
GET /.well-known/runlease-relay | How to sign in to this relay, and what its default tier allows |
GET /me | Your identity, tier and usage |
GET /health | Liveness |
The relay sees the token, the source addresses, and an opaque byte stream that happens to be SSH. It has no key that would let it decrypt that stream, pose as the VM, or log in. The threat model goes through each case.