runlease

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

ProgramRuns onDoes
runleaseYour machine, an agent's sandbox, or CILaunches VMs through the cloud API, holds the keys, and opens every session
runlease-agentEach VMDials out to the relay and hands incoming streams to sshd on localhost
runlease-relayOne small server with a public TLS endpointMatches CLI connections to the right agent and copies bytes between them
YOUR MACHINE runlease CLI holds the keys opens every session relay matches the two sides copies bytes YOUR CLOUD ACCOUNT spot VM runlease-agent → sshd lease timer dials out dials out cloud API: create the VM, attach the boot script, delete it
Both arrows into the relay point inward. Neither your machine nor the VM has to accept a connection.

A launch, step by step

What runlease up does, in order, and who does each part.

  1. 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.

  2. CLI

    Makes a slot token, 256 random bits.

  3. 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.

  4. 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.

  5. CLI

    Saves the keys, encrypted, under ~/.runlease.

  6. 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.

  7. VM → relay

    The agent dials out and claims the slot.

  8. CLI → relay

    The CLI connects for the same slot. The relay joins the two connections.

  9. 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.

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:

  1. Installs runlease-terminate and runlease-snooze, the only two commands the login user may run as root.
  2. Arms a systemd timer that runs runlease-terminate at the end of the lease.
  3. Creates the runlease-agent user and installs your public login key.
  4. Installs the pre-issued host key and removes every other host key.
  5. Hardens sshd: public-key only, one allowed user, no root login.
  6. Grants general sudo only if the manifest says sudo: passwordless.
  7. Downloads the agent, verifies its SHA-256, and starts it under a restricted systemd unit.
  8. Runs your setup steps 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 itWho acts
The lease timer firesThe VM deletes itself
runlease downYou
The cloud reclaims the spot capacityYour cloud provider
runlease daemon sees an expired leaseA watcher on your side

On your machine

Runlease keeps its state under ~/.runlease. Set RUNLEASE_HOME to move it.

FileHolds
config.yamlYour defaults
registry.jsonOne entry per launched VM: cloud, instance ID, relay address, slot token, forwards
credentials/<id>.jsonThat VM's key pairs, encrypted with AES-256-GCM
master.keyThe key that encrypts them, readable only by you
auth.jsonYour 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.

RoleSent byFirst messageThen
registerCLI at up{"role":"register","token":"…"} with your sign-in as a bearer tokenReplies ok, or limit when your tier is full, and closes
instanceAgent at boot{"role":"instance","token":"…"}The agent serves multiplexed streams on this socket
clientCLI, every command{"role":"client","token":"…"}Raw bytes, joined to a new stream on the agent's socket
releaseCLI at down{"role":"release","token":"…"}The slot is freed at once
HTTP endpointPurpose
GET /agentServes the agent binary, which the VM then verifies
GET /readyWhether a slot's agent is connected
GET /.well-known/runlease-relayHow to sign in to this relay, and what its default tier allows
GET /meYour identity, tier and usage
GET /healthLiveness

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.