runlease

Install

One verified binary, in your home directory.

The installer downloads the release for your machine, checks its SHA-256, and puts runlease in ~/.local/bin. No sudo, no package manager, no background service.

Install

$ curl -fsSL https://runlease.online/install.sh | sh

Works on Linux and macOS, on Intel and Arm. If you would rather read a script before running it, which is a good habit for a tool that holds SSH keys:

$ curl -fsSL https://runlease.online/install.sh -o install.sh
$ less install.sh
$ sh install.sh

What the script does

  1. 01

    Works out your operating system and CPU.

  2. 02

    Downloads that binary and checksums.txt from the GitHub release.

  3. 03

    Checks the binary's SHA-256 against checksums.txt, and stops without installing on a mismatch.

  4. 04

    If cosign is installed, also checks the signature on checksums.txt.

  5. 05

    Copies the binary to ~/.local/bin/runlease. Nothing else on your system changes.

SettingDefaultMeaning
RUNLEASE_VERSIONlatestA specific release, for example v0.7.1
RUNLEASE_INSTALL_DIR~/.local/binWhere the binary goes

Install by hand

The script is a convenience. These are the same steps, and they are the way to install on Windows.

# pick the latest release, and your platform
$ VERSION=v0.7.1
$ OS=linux ARCH=amd64      # or darwin / arm64
$ BASE=https://github.com/marshal-org/runlease/releases/download/$VERSION

$ curl -fsSLO $BASE/runlease-$OS-$ARCH
$ curl -fsSLO $BASE/checksums.txt
$ sha256sum --check --ignore-missing checksums.txt
$ install -m 0755 runlease-$OS-$ARCH ~/.local/bin/runlease

To also check the signature and the build provenance, see verify a release.

Why not go install?

You can build from source, and it works. It is not the recommended way to install, for a security reason.

A release build of the CLI has the SHA-256 of its matching agent compiled in. Every VM you launch checks the agent it downloads from the relay against that value before running it. A binary from go install has no such value, so that check is off, and the CLI warns you at every up.

# Go 1.26 or newer. Fine for development, and against a relay you run yourself.
$ go install github.com/marshal-org/runlease/cmd/runlease@latest

If you do use a source build against a relay you do not run, pin the agent's digest in each manifest with relay.agentSha256. How agent verification works.

First launch

You need credentials for one cloud. Runlease uses the ones your cloud's own tools use, and stores none of its own.

Google Cloud

$ gcloud auth application-default login
$ gcloud config set project MY_PROJECT

AWS

The usual credential chain: environment variables, a profile, or SSO.

$ aws sso login

Then sign in to the free public relay and launch:

$ runlease login                 # the free public relay: approve a short code in any browser
$ runlease up -p gcp -n box -d    # or -p aws: a small 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 on it
$ runlease connect box           # or open a shell
$ runlease down box --yes        # or let the lease delete it

Those lines are copy-paste complete. To stop typing the cloud, region and size each time, run runlease configure once; after that a bare runlease up is enough. If a command fails because a cloud sign-in has expired, the error says which command renews it.

Something not working? runlease doctor checks your sign-ins, project and network and prints the fix.

Your subnet needs a way out. A machine launched through a relay gets no public address, so it reaches the relay through your subnet's NAT gateway. runlease up checks for one before it creates anything. If there is none it stops and tells you the two ways forward: add a NAT gateway, or re-run with --public-ip, which gives an address for outbound traffic only while SSH still listens on localhost.

The machine is yours. It runs in your cloud account, on your bill. The relay only connects you to it. What the public relay allows, and how to run your own.

Start from a manifest

A manifest is a short YAML file that describes one machine. Keep it next to your code and every launch is the same. Pick the one closest to what you need, save it, and run runlease up -m FILE.

Smallest, Google Cloud

One small machine, the public relay, a two-hour lease. Start here. File: examples/manifests/quick-gcp.yaml

# The smallest useful manifest: one small spot machine on Google Cloud,
# reached through the free public relay, gone after two hours.
#
#   runlease up -m quick-gcp.yaml
name: scratch
provider: gcp
region: us-central1-a          # a zone
instanceClass: compute.small   # about 2 vCPU / 2 GB
reclaim:
  ttl: 2h                      # the lease: the machine deletes itself after this
relay:
  addr: wss://connect.runlease.online

Smallest, AWS

The same on AWS. The image defaults to the latest Amazon Linux 2023. File: examples/manifests/quick-aws.yaml

# The same on AWS. The image defaults to the latest Amazon Linux 2023.
#
#   runlease up -m quick-aws.yaml
name: scratch
provider: aws
region: eu-north-1             # a region
instanceClass: compute.small   # about 2 vCPU / 2 GB
reclaim:
  ttl: 2h                      # the lease: the machine deletes itself after this
relay:
  addr: wss://connect.runlease.online

Coding agent

More room, tools installed at boot, and a dev server port forwarded to your computer. File: examples/manifests/agent-workbench.yaml

# A machine for a coding agent: more room, tools installed at boot, and a dev
# server port forwarded to your computer.
#
#   runlease up -m agent-workbench.yaml --attach
#
# --attach streams the setup log, then holds the port forward open.
name: workbench
provider: gcp
region: us-central1-a
instanceClass: compute.large   # about 4 vCPU / 8 GB
diskSizeGb: 50
reclaim:
  ttl: 4h
relay:
  addr: wss://connect.runlease.online
sudo: passwordless             # the agent may install packages; default is locked
setup:                         # runs once, as root, after the machine is ready
  - name: tools
    run: |
      apt-get update -qq
      apt-get install -y -qq git build-essential nodejs npm
forwards:                      # localhost:3000 here -> port 3000 on the machine
  - name: dev-server
    local: 3000
    remote: 3000

No NAT gateway

For a subnet with no NAT gateway: a public address for outbound traffic only. File: examples/manifests/no-nat.yaml

# For a subnet with no NAT gateway. By default a machine launched through a
# relay gets no public address and dials out through NAT. Without NAT it needs
# a public address to reach the relay. SSH still listens on localhost only.
#
#   runlease up -m no-nat.yaml
name: scratch
provider: gcp
region: us-central1-a
instanceClass: compute.small
publicIp: true                 # outbound only: nothing of Runlease's listens on it
reclaim:
  ttl: 2h
relay:
  addr: wss://connect.runlease.online

GPU job

One spot GPU for a short job, on AWS. File: examples/manifests/gpu.yaml

# One spot GPU for a short job, on AWS. Spot GPUs are reclaimed more often than
# CPUs, so keep the work resumable. Check your GPU spot quota in the region first.
# The default image has no NVIDIA driver: install one in setup, or set baseImage
# to an AMI that has it.
#
#   runlease up -m gpu.yaml
name: gpu-job
provider: aws
region: us-east-1              # a region
instanceClass: compute.gpu     # g4dn.xlarge: 4 vCPU / 16 GB and one NVIDIA T4
diskSizeGb: 100
reclaim:
  ttl: 3h
relay:
  addr: wss://connect.runlease.online

Every field, with its default: the manifest reference. These files are loaded by the project's tests, so they stay valid.

Uninstall

$ rm ~/.local/bin/runlease
$ rm -r ~/.runlease              # saved keys, settings and sign-in

Run runlease list first and take down anything still running, because the second command deletes the keys you would need to reach it. The machines still delete themselves when their leases end.