Skip to content
Back to search

runlease

MarketplaceWorks with Claude CodeGitHub

Cheap spot VMs for coding agents, in your own cloud. Every machine deletes itself when its lease ends.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marshal-org--runlease/badge.svg)](/listings/marshal-org--runlease)

HTML

<a href="/listings/marshal-org--runlease"><img src="/api/listings/marshal-org--runlease/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

The [script](site/install.sh) downloads the release for your machine, checks its SHA-256 against `checksums.txt`, and puts `runlease` in `~/.local/bin`. It uses no sudo. To do the same by hand:

VERSION=v0.7.1   # pick the latest
OS=linux ARCH=amd64   # or darwin / arm64
curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/runlease-${OS}-${ARCH}"
curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
install -m 0755 "runlease-${OS}-${ARCH}" ~/.local/bin/runlease

Releases are signed. See [verifying a release](docs/security.md#verifying-a-release).

Or build from source (Go 1.26 or newer):

go install github.com/marshal-org/runlease/cmd/runlease@latest

A source build does not carry the agent checksum that release builds do. Read [agent verification](docs/security.md#the-agent-binary-is-verified-before-it-runs) before using one against a relay you do not run yourself.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "runlease",
  3. "owner": {
  4. "name": "The Marshal team",
  5. "url": "https://marshal.codes"
  6. },
  7. "metadata": {
  8. "description": "Runlease, built by the Marshal team: disposable cloud machines for coding agents, in your own Google Cloud or AWS account, at spot prices."
  9. },
  10. "plugins": [
  11. {
  12. "name": "runlease",
  13. "source": "./plugin",
  14. "category": "development",
  15. "homepage": "https://runlease.online/claude-code-sandbox.html",
  16. "description": "Give Claude Code a real cloud machine when the task outgrows your laptop: long builds, code you would not run locally, test runs split across machines. Spot VMs in your own Google Cloud or AWS account, with a live view of each lease and its cost. Every machine deletes itself when its lease ends. Built by the Marshal team."
  17. }
  18. ]
  19. }
README.md · README · 315 lines · 1 finding marked
  1. <p align="center"><img src="site/logo.svg" alt="" width="72" height="72"></p>
  2. <h1 align="center">runlease</h1>
  3. <p align="center">
  4. <strong>Spot machines for coding agents. Cheap, safe, and in your own cloud.</strong><br>
  5. Your keys never leave your machine, the relay cannot read your traffic, and every machine deletes itself.
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/marshal-org/runlease/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/marshal-org/runlease/actions/workflows/ci.yml/badge.svg"></a>
  9. <a href="https://github.com/marshal-org/runlease/releases"><img alt="Release" src="https://img.shields.io/github/v/release/marshal-org/runlease"></a>
  10. <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
  11. <a href="https://pkg.go.dev/github.com/marshal-org/runlease"><img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/marshal-org/runlease.svg"></a>
  12. </p>
  13. <p align="center">
  14. Built by <a href="https://marshal.codes/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=runlease&amp;utm_content=top"><strong>Marshal</strong></a>: AI coding agents at full speed, with full receipts.<br>
  15. Marshal runs coding agents in isolated pods inside your own VPC. Runlease is the tool we built to give them, and our tests, a real machine for an hour.
  16. </p>
  17. <p align="center">
  18. <img src="site/demo.svg" width="100%" alt="A terminal runs runlease up, exec, snooze and list. Beside it a diagram builds step by step: keys are made on your computer, a slot is reserved at the relay, a spot machine starts in your cloud account and dials out, SSH runs end to end through the relay, the lease is extended, and the machine deletes itself.">
  19. </p>
  20. ```bash
  21. runlease up --provider gcp --size compute.large --ttl 2h # a spot VM in your account
  22. runlease exec <name> -- make test # run something on it
  23. runlease down <name> --yes # or let the lease delete it
  24. ```
  25. One command gives an agent, a CI job or you a real Linux machine. It runs in **your** cloud
  26. account at spot prices, has **no public address**, and **deletes itself** when its lease runs out.
  27. ---
  28. ## Why
  29. Coding agents need somewhere to run things: build the project, start the stack, run the tests,
  30. break something and try again. A laptop is the wrong place and a long-lived dev box is worse.
  31. | | |
  32. |---|---|
  33. | **Yours** | The VM runs in your own GCP or AWS account, on your network, under your IAM. Nothing is hosted for you and nothing leaves your account. |
  34. | **Cheap** | Spot capacity. `runlease up` shows the hourly price and the projected cost of the lease before it launches. |
  35. | **Closed** | By default the VM has no public address and its SSH server listens on localhost only. The VM dials out to a relay; you reach it through that tunnel. |
  36. | **Private** | The relay carries SSH. It holds no keys and cannot read, alter or impersonate a session. [How that works](docs/security.md). |
  37. | **Managed** | Every machine has a lease. It deletes itself at the end of it, whether or not your laptop is still online. |
  38. | **Scriptable** | `--output json` on every command, non-interactive `exec`, `push`, `pull` and `forward`. Built to be driven by an agent. |
  39. ## Install
  40. ```bash
  41. curl -fsSL https://runlease.online/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 54 on GitHub
  42. ```
  43. The [script](site/install.sh) downloads the release for your machine, checks its SHA-256 against
  44. `checksums.txt`, and puts `runlease` in `~/.local/bin`. It uses no sudo. To do the same by hand:
  45. ```bash
  46. VERSION=v0.7.1 # pick the latest
  47. OS=linux ARCH=amd64 # or darwin / arm64
  48. curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/runlease-${OS}-${ARCH}"
  49. curl -fsSLO "https://github.com/marshal-org/runlease/releases/download/${VERSION}/checksums.txt"
  50. sha256sum --check --ignore-missing checksums.txt
  51. install -m 0755 "runlease-${OS}-${ARCH}" ~/.local/bin/runlease
  52. ```
  53. Releases are signed. See [verifying a release](docs/security.md#verifying-a-release).
  54. Or build from source (Go 1.26 or newer):
  55. ```bash
  56. go install github.com/marshal-org/runlease/cmd/runlease@latest
  57. ```
  58. A source build does not carry the agent checksum that release builds do. Read
  59. [agent verification](docs/security.md#the-agent-binary-is-verified-before-it-runs) before using
  60. one against a relay you do not run yourself.
  61. ## Quick start
  62. You need credentials for one cloud: `gcloud auth application-default login` (and
  63. `gcloud config set project MY_PROJECT`) for GCP, or the usual AWS credential chain.
  64. ```bash
  65. runlease login # the free public relay: approve a short code in a browser
  66. runlease doctor # optional: checks sign-ins, project and network, prints the fix
  67. runlease up -p gcp -n box -d # or -p aws: a small spot machine, gone in two hours
  68. # no NAT gateway on the subnet? it stops and says so: add --public-ip
  69. runlease exec box -- uname -a # run something
  70. runlease connect box # or open a shell
  71. runlease forward box -L 8080:localhost:8080 # reach a port on the VM
  72. runlease push box ./build.tar /tmp/build.tar
  73. runlease snooze box 1h # extend the lease
  74. runlease down box --yes # delete it now
  75. ```
  76. Run `runlease configure` once to save a default cloud, region and size; after that a bare
  77. `runlease up` is enough.
  78. For anything repeatable, describe the machine in a manifest:
  79. ```yaml
  80. # agent-box.yaml
  81. name: agent-box
  82. provider: gcp
  83. region: us-central1-a
  84. instanceClass: compute.large
  85. reclaim:
  86. ttl: 3h
  87. selfTermination: true
  88. relay:
  89. addr: wss://relay.example.com
  90. setup:
  91. - name: toolchain
  92. run: |
  93. apt-get update && apt-get install -y build-essential git
  94. forwards:
  95. - local: 3000
  96. remote: 3000
  97. ```
  98. ```bash
  99. runlease up -m agent-box.yaml --attach
  100. ```
  101. `runlease manifest new` writes one interactively. Every field is in the
  102. [manifest reference](docs/manifest.md).
  103. ### For coding agents: the MCP server
  104. `runlease mcp` serves the same commands as typed tools over the
  105. [Model Context Protocol](https://modelcontextprotocol.io), so an agent launches, uses and deletes
  106. machines without composing shell commands:
  107. ```bash
  108. claude mcp add runlease -- runlease mcp # Claude Code
  109. ```
  110. Any other MCP client takes `{"command": "runlease", "args": ["mcp"]}`. The tools and the safety
  111. notes are in [docs/mcp.md](docs/mcp.md).
  112. ### Finding machines this computer has forgotten
  113. `runlease list` shows what this computer launched and still remembers. It also asks your cloud
  114. for every machine carrying the `runlease-managed` label, and lists the ones it does not track:
  115. launched from another computer, or left behind stopped with a disk that still bills.
  116. ```bash
  117. runlease list # tracked machines, then anything found in the cloud
  118. runlease down --leaked # delete the stopped ones whose lease is over
  119. runlease list --local # skip the cloud lookup
  120. runlease down --leaked --provider aws --region eu-north-1 # say where to look: an AWS region
  121. runlease down --leaked --provider gcp --project my-project # or a Google Cloud project, all zones
  122. ```
  123. `down --leaked` never deletes a running machine. It only removes machines that are stopped and
  124. past their lease.
  125. Both look where this computer has launched before and in its saved default. With neither,
  126. `down --leaked` and `list --untracked` look in each cloud signed in on this computer, in its
  127. default place. `down --leaked` always prints where it is looking first, by name: the project ID,
  128. or the region and account.
  129. It deletes without asking (`--yes`, or `--output json`) only in a place that was named: by the
  130. flags above, by a machine this computer tracks, or by the saved default. In a place it had to
  131. fill in, it lists what it found, deletes nothing, and prints the command that names the place.
  132. ### When something is not working
  133. ```bash
  134. runlease doctor # every cloud signed in on this computer
  135. runlease doctor --provider aws --region eu-north-1 # one cloud, one region
  136. runlease doctor --output json # {"ok": bool, "checks": [{id, title, status, detail, fix}]}
  137. ```
  138. `runlease doctor` creates nothing. It checks this CLI, the relay (set, reachable, signed in,
  139. serving the agent this CLI expects) and each cloud (credentials, project or account, region,
  140. network, NAT gateway), runs every check whatever the one before it found, and prints the
  141. command that fixes each problem. It exits 1 if a check failed; a warning, such as a subnet
  142. with no NAT gateway, does not fail it.
  143. ## How it works
  144. ```mermaid
  145. flowchart LR
  146. subgraph You["You, an agent, or CI"]
  147. CLI["runlease CLI<br/>holds the SSH keys"]
  148. end
  149. R[("Relay<br/>holds no keys")]
  150. subgraph Cloud["Your cloud account"]
  151. subgraph VM["Spot VM, dials out"]
  152. A["runlease-agent"] --> S["sshd"]
  153. end
  154. end
  155. CLI -- "SSH inside a WebSocket" --> R
  156. A -- "dials out" --> R
  157. ```
  158. 1. `runlease up` generates two key pairs on your machine: one to log in with, and the VM's SSH
  159. **host key**. It also picks a random 256-bit slot token and registers it with the relay.
  160. 2. The VM boots. Its agent dials **out** to the relay and claims the slot.
  161. 3. Every command you run opens an SSH session through the relay to the VM's `sshd`. The CLI
  162. accepts only the host key it generated in step 1, so the relay cannot stand in for the VM.
  163. 4. A timer inside the VM deletes the instance when the lease ends.
  164. The full walk-through, with the protocol and the boot sequence, is in
  165. [docs/how-it-works.md](docs/how-it-works.md).
  166. ## Security
  167. Runlease is built so that the one shared, internet-facing piece, the relay, is not something you
  168. have to trust with your sessions.
  169. - The relay never holds an SSH key, a cloud credential or plaintext.
  170. - Host keys are issued before boot. Nothing is trusted on first use.
  171. - The agent binary is checked against a SHA-256 compiled into the CLI before it runs.
  172. - The agent runs unprivileged in a locked-down systemd unit. `sudo` on the VM is off unless the manifest turns it on.
  173. - On AWS, instances require IMDSv2.
  174. The [threat model](docs/security.md) says exactly what each party can and cannot do, and lists
  175. the limits we know about. To report a vulnerability, see [SECURITY.md](SECURITY.md).
  176. ## For Claude Code
  177. A plugin gives Claude Code the skills to use Runlease on its own, slash commands, typed tools, and
  178. a live view of what is running:
  179. ```
  180. /plugin install runlease --marketplace marshal-org/runlease
  181. ```
  182. What it adds and what it holds Claude to: [the Claude Code plugin](docs/claude-plugin.md).
  183. ## For Antigravity and the Gemini CLI
  184. The same skills, commands and typed tools install in Google's coding agents, without the live
  185. view:
  186. ```bash
  187. agy plugin install https://github.com/marshal-org/runlease # Antigravity
  188. gemini extensions install https://github.com/marshal-org/runlease # Gemini CLI
  189. ```
  190. What is included and what is not: [Antigravity and Gemini CLI](docs/google-agents.md).
  191. ## The relay
  192. A relay is one small Go binary. You have three choices:
  193. - **Use the public one.** Free, with a Google sign-in and a limit of two machines at once:
  194. ```bash
  195. runlease login # with no relay set, this picks the public one and saves it
  196. ```
  197. What it allows and what it sees: [the public relay](docs/relay-service.md).
  198. - **Run your own.** It takes one VM or container and a TLS endpoint. See
  199. [self-hosting the relay](docs/self-hosting-relay.md). This is what we recommend for real work.
  200. - **No relay at all.** Leave `relay.addr` empty and Runlease gives the VM a public IP and connects
  201. directly, or use `runlease iap` (GCP) or `runlease ssm` (AWS).
  202. ## Clouds
  203. | Cloud | Status |
  204. |---|---|
  205. | Google Cloud | Supported |
  206. | AWS | Supported |
  207. | Azure, others | Not implemented. The [provider interface](pkg/provider/interface.go) is four methods, and a new provider is a good first contribution. |
  208. Machine sizes are portable: `compute.small` to `compute.2xlarge` and `compute.gpu` map to a
  209. concrete type per cloud. Run `runlease catalog` to see the mapping.
  210. ## Documentation
  211. | | |
  212. |---|---|
  213. | [How it works](docs/how-it-works.md) | Architecture, protocol, boot sequence, lease lifecycle |
  214. | [Security and threat model](docs/security.md) | What each party can do, known limits, release verification |
  215. | [Manifest reference](docs/manifest.md) | Every field |
  216. | [MCP server](docs/mcp.md) | `runlease mcp`: typed tools for coding agents, how to register it, safety notes |
  217. | [The public relay](docs/relay-service.md) | Sign in, free tier limits, what it logs |
  218. | [Self-hosting the relay](docs/self-hosting-relay.md) | Deploy, authenticate, set tiers, operate |
  219. | [CI and release pipeline](docs/ci.md) | How changes are tested and how releases are built and signed |
  220. ## Contributing
  221. Issues and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Changes to
  222. the relay, the boot script or credential handling get an extra-careful review; the pull request
  223. template says what we look for.
  224. This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
  225. ## Status
  226. Pre-1.0. The CLI and the manifest format can still change between minor versions; the
  227. [changelog](CHANGELOG.md) calls out every breaking change.
  228. ## License
  229. [Apache License 2.0](LICENSE).
  230. ## Built by Marshal
  231. Runlease is built and maintained by [Marshal](https://marshal.codes/?utm_source=github&utm_medium=readme&utm_campaign=runlease&utm_content=section). Marshal runs AI coding
  232. agents in isolated pods inside your own VPC, with credential isolation, audited egress and live
  233. tool policies.
  234. **Running agents for a whole team?** Runlease gives one agent one machine. When you need policy,
  235. audit and isolation across many agents and many people, [see Marshal](https://marshal.codes/?utm_source=github&utm_medium=readme&utm_campaign=runlease&utm_content=team)
  236. or [book a demo](https://marshal.codes/?utm_source=github&utm_medium=readme&utm_campaign=runlease&utm_content=demo#demo).
  237. Runlease stands alone: you do not need Marshal to use it. We built it to give agents and tests a
  238. real machine for an hour, and we use it ourselves.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.