The relay
Start on ours for free. Move to your own whenever you like.
The relay is the one part that must be reachable from the internet. It introduces your machine to your VM and then copies encrypted bytes. It never holds a key.
Free
Public relay
Sign in with Google and launch. No card, no setup.
- machines at once
- 2
- connected for up to
- 8 h
- sign-in
- uptime promise
- none
Your own
Self-hosted relay
One small binary on one small VM, admitting only who you say.
- machines at once
- yours to set
- who can sign in
- your domain
- connection metadata
- stays with you
- cost
- one small VM
The public relay
$ runlease config set relay.addr wss://connect.runlease.online $ runlease login
runlease login prints a short code and a link. Open the link in any browser, on any device, enter the code and approve. Nothing has to open on the machine you are working on.
$ runlease whoami # who you are, your tier, how much of it is in use $ runlease up # launch as usual $ runlease logout # forget the saved sign-in
What the free tier allows
| Free | |
|---|---|
| Machines connected at once | 2 |
| Longest a machine can stay connected | 8 hours, then runlease connect reconnects it |
| A machine that has been gone for 15 minutes | Its place is given back |
| Price | Nothing |
| Uptime promise | None |
runlease down gives a place back at once. If you reach the limit, runlease up tells you so before any machine is created, and tells you which command frees a place.
The limits are on the relay only. The machines are yours, in your cloud account, on your bill. Runlease does not limit or meter them.
Larger tiers may be offered later. The limits can change; runlease whoami always shows the current ones.
What it sees
The relay is built so that it does not have to be trusted with your sessions. The threat model has the full account.
It sees and logs
- The email address of the Google account you signed in with
- When you open and close a slot, and the first characters of its token
- The network addresses that connect to it, and how much data passes
It never sees
- Your SSH keys
- Your cloud credentials
- Your commands, files, or the contents of forwarded connections
- Anything from your Google account other than the email address
Details are in the privacy notice. The relay exists to reach machines you launched with Runlease; the terms say what it may not be used for.
When to run your own
- You need more than the free limits, or an uptime you can rely on.
- You do not want a third party to see who connects to what, and when.
- Your machines must only talk to hosts inside your own network.
- You want to admit your organisation's identities and nobody else.
The security of a session is the same either way. What changes is who holds the connection metadata and who sets the limits.
Self-hosting
The relay is one static binary. It needs a public TLS endpoint and almost nothing else: it keeps no data on disk and holds no keys.
What you need
- A small Linux VM or container. One vCPU and 1 GB of memory is enough to start.
- A DNS name and TLS. Put the relay behind a load balancer, Caddy, nginx or Cloudflare; the relay itself speaks plain HTTP and WebSocket on one port.
- The
runlease-relayandrunlease-agentbinaries from the same release as the CLI your team uses.
With Terraform, on Google Cloud
The repository ships a module that stands up everything on this page on one VM: its own network, inbound 80 and 443 only, a static address, a service account with no cloud access, checksum-verified binaries and automatic TLS. It is the module the public relay runs on.
module "relay" { source = "github.com/marshal-org/runlease//deploy/relay/gcp?ref=v0.7.1" project_id = "my-relay-project" hostname = "relay.example.com" acme_email = "ops@example.com" relay_binary_url = "https://github.com/marshal-org/runlease/releases/download/v0.7.1/runlease-relay-linux-amd64" relay_sha256 = "<from checksums.txt>" agent_binary_url = "https://github.com/marshal-org/runlease/releases/download/v0.7.1/runlease-agent-linux-amd64" agent_sha256 = "<from checksums.txt>" # a private relay for one organisation audience = "https://relay.example.com" allowed_domains = ["example.com"] }
Point the hostname's A record at the module's address output. Create the DNS record before the VM, or restart the VM once the record resolves: it asks for its certificate at boot.
By hand
$ VERSION=v0.7.1 $ BASE=https://github.com/marshal-org/runlease/releases/download/$VERSION $ curl -fsSLO $BASE/runlease-relay-linux-amd64 $ curl -fsSLO $BASE/runlease-agent-linux-amd64 $ curl -fsSLO $BASE/checksums.txt $ sha256sum --check --ignore-missing checksums.txt $ sudo install -m 0755 runlease-relay-linux-amd64 /usr/local/bin/runlease-relay $ sudo install -m 0755 runlease-agent-linux-amd64 /usr/local/bin/runlease-agent
Use the release binaries, not a local build. The CLI checks the agent the relay serves against a SHA-256 compiled into the CLI at release time. A locally built agent has a different digest and VMs will refuse it, unless each manifest pins it with relay.agentSha256.
# /etc/systemd/system/runlease-relay.service
[Unit]
Description=Runlease relay
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/runlease-relay \
--addr 127.0.0.1:7777 \
--agent-binary /usr/local/bin/runlease-agent \
--audience https://relay.example.com \
--allowed-domains example.com \
--max-slots 5000
Restart=always
DynamicUser=yes
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
CapabilityBoundingSet=
[Install]
WantedBy=multi-user.target
$ sudo systemctl daemon-reload $ sudo systemctl enable --now runlease-relay $ curl -fsS http://127.0.0.1:7777/health && echo ok
Then terminate TLS in front of it and forward to 127.0.0.1:7777. WebSocket upgrades must pass through, and idle timeouts on the proxy should be long, because sessions are held open.
Point the CLI at it
$ runlease config set relay.addr wss://relay.example.com
Who may open a slot
Opening a slot needs a Google ID token. There are two ways to accept one, and a relay can use both.
| Setting | Who it admits | How they sign in |
|---|---|---|
--audience with --allowed-domains or --allowed-emails | Your organisation's accounts and service accounts | gcloud or a service account. Nothing to set up per person |
--google-client-id and --google-client-secret | Anyone with a Google account, or only your allow-list if you set one | runlease login |
For runlease login, create an OAuth client of type TVs and Limited Input devices in the Google Cloud console, with the openid and email scopes. The relay hands the client ID and secret to each CLI that signs in. For this client type the secret is not confidential; what protects sign-in is Google's signature on the token, which the relay verifies.
The relay will not start with no authentication at all unless you pass --insecure-no-auth.
Tiers and limits
A tiers file gives each identity a set of limits. Adding a tier is a file edit.
default: free tiers: free: maxSlots: 2 # machines one person may have connected at once slotTTL: 8h # a slot lives this long at most idleTTL: 15m # a slot whose machine has been gone this long is given back team: maxSlots: 20 assign: emails: someone@example.com: team domains: example.com: team
- Everyone lands in
defaultunless an assignment names another tier. An exact email wins over a domain. - A slot is given back when its owner runs
runlease down, when its machine has been absent foridleTTL, or whenslotTTLruns out. - An unknown field in the file is an error, so a misspelt limit cannot silently mean "unlimited".
- The file is read at start. Restart the relay to change limits.
Operating it
| Flag | Meaning |
|---|---|
--addr | Listen address. Default :7777 |
--agent-binary | Path of the agent served to booting VMs |
--audience | The relay's public URL, which identity tokens must be issued for |
--allowed-emails, --allowed-domains | Who may open slots |
--google-client-id, --google-client-secret | The OAuth client for runlease login |
--tiers-file | The tiers file |
--max-slots | Refuse new slots beyond this many, across everyone. Default 5000 |
- State is all in memory. There is nothing to back up.
- Logs go to stderr. Slot tokens are logged as a short prefix only.
- Health:
GET /healthreturns 200. - Network: inbound HTTPS, and nothing outbound.
- Upgrades: the relay serves the agent, so relay and agent are always upgraded together, before the CLI release that goes with them. Restarting the relay drops live sessions and forgets its slots. VMs already running keep their old agent.
- Hardening: keep it on its own small machine with no cloud credentials attached. A relay with no credentials is worth little to whoever breaks into it, which is the point of the design.