runlease

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
Google
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 once2
Longest a machine can stay connected8 hours, then runlease connect reconnects it
A machine that has been gone for 15 minutesIts place is given back
PriceNothing
Uptime promiseNone

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

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

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.

SettingWho it admitsHow they sign in
--audience with --allowed-domains or --allowed-emailsYour organisation's accounts and service accountsgcloud or a service account. Nothing to set up per person
--google-client-id and --google-client-secretAnyone with a Google account, or only your allow-list if you set onerunlease 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

Operating it

FlagMeaning
--addrListen address. Default :7777
--agent-binaryPath of the agent served to booting VMs
--audienceThe relay's public URL, which identity tokens must be issued for
--allowed-emails, --allowed-domainsWho may open slots
--google-client-id, --google-client-secretThe OAuth client for runlease login
--tiers-fileThe tiers file
--max-slotsRefuse new slots beyond this many, across everyone. Default 5000