Skip to content
Runtime

How to give Cursor CLI a cloud sandbox

Add Runtime's MCP server to ~/.cursor/mcp.json. Cursor's agent then runs code in Linux microVMs instead of on your machine.

Start free, no cardRead as Markdown

Cursor CLI runs its agent on your laptop. Runtime runs the risky part, the code. Through Runtime's MCP server, the agent gets tools to start a Firecracker microVM with its own kernel, run commands, and read files back. The agent can therefore use a fresh machine for each experiment. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while idle. In Runtime's check on 23 September 2026, agent mcp list-tools reached Runtime's server from this configuration. The installer on 25 October 2026 fetched Cursor CLI build 2026.10.22-27dcf5f.

Where the work happens What runs there
Your machine Cursor's agent, your editor files, Cursor's model calls
A Runtime sandbox The commands, installs, tests and servers the agent starts
Runtime's servers Your keys for sandboxes, as secrets the sandbox never sees

Install and connect

Cursor's installer puts the CLI in ~/.local/bin as both agent and cursor-agent:

Terminalcurl https://cursor.com/install -fsS | bash

Cursor CLI reads the same MCP files as the editor. Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one repo. Add Runtime:

JSON{  "mcpServers": {    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }  }}

Then check the setup:

Terminalagent mcp listagent mcp list-tools runtime

The first time, Runtime offers one tool, runtime_connect. Ask the agent to use it. The tool shows a link and a code. Approve Connect agent in the browser. Every Runtime tool then appears, with no restart needed (MCP). A machine already signed in with npx withruntime login skips this step. No key is written to mcp.json, so the project-level file is safe to commit.

Cursor also accepts remote servers that sign in through the browser. To use one, point Cursor at https://api.withruntime.com/mcp (remote connection).

Script it: prepare a sandbox, then let the agent work

In a script or CI job, prepare a named sandbox with the SDK. Then run Cursor's agent in print mode, and tell it which sandbox to use. The sandbox is ready, cloned, and narrowed to the hosts you choose before the agent touches it.

TypeScriptimport { execFileSync } from "node:child_process";import { Sandbox } from "withruntime";const repo = "https://github.com/your-org/your-repo";const sbx = await Sandbox.getOrCreate("cursor-tests", {  diskMiB: 8192,  idlePauseSeconds: 900,});if (!sbx.info.reused) {  await sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"], {    check: true,    timeoutMs: 600_000,  });}await sbx.network.set({ internet: true, allow: ["registry.npmjs.org", "github.com"] });const prompt =  `Use the Runtime sandbox ${sbx.id}. In /workspace/app run npm ci and npm test, ` +  "fix the first failing test in this local repo, and rerun the tests in the sandbox.";const out = execFileSync(  "agent",  ["-p", "--approve-mcps", "--trust", "--force", "--output-format", "json", prompt],  { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },);console.log(out);
Pythonimport subprocessfrom withruntime import Sandboxrepo = "https://github.com/your-org/your-repo"sbx = Sandbox.get_or_create("cursor-tests", disk_mib=8192, idle_pause_seconds=900)if not sbx.info.get("reused"):    sbx.exec(["git", "clone", "--depth", "1", repo, "/workspace/app"],             check=True, timeout_ms=600_000)sbx.network.set(internet=True, allow=["registry.npmjs.org", "github.com"])prompt = (f"Use the Runtime sandbox {sbx.id}. In /workspace/app run npm ci and npm test, "          "fix the first failing test in this local repo, and rerun the tests in the sandbox.")out = subprocess.run(    ["agent", "-p", "--approve-mcps", "--trust", "--force", "--output-format", "json", prompt],    capture_output=True, text=True, check=True,)print(out.stdout)

These flags are described in Cursor's headless page and its CLI parameters reference:

  • -p, --print runs one prompt without the interactive UI.
  • --approve-mcps approves the configured MCP servers, so the Runtime tools load with no one at the keyboard.
  • --trust trusts the current workspace without a prompt.
  • --force (alias --yolo) allows commands unless a rule denies them. The agent's own edits land in your local checkout. The builds and tests it runs through Runtime happen in the sandbox.
  • --output-format json prints a structured result. stream-json streams events as they happen.
  • CURSOR_API_KEY authenticates the CLI in CI in place of a browser login. RUNTIME_API_KEY, from your secret manager, does the same for Runtime's server.

getOrCreate returns the same sandbox on the next run. If the sandbox paused after 15 idle minutes, it wakes. A second job skips the clone and reuses the installed dependencies (sandboxes by name).

The tools Cursor's agent uses

Tool What it is for
runtime_sandboxes_create A new microVM, running when the call returns
runtime_sandboxes_list Find a sandbox by name or label
runtime_sandboxes_exec Run a command. Returns exit code, stdout and stderr
runtime_sandboxes_files_write Copy a file from the local repo into the sandbox
runtime_sandboxes_previews Share a dev server at a private HTTPS address
runtime_sandboxes_network Narrow or cut the sandbox's internet
runtime_secrets Store a token the sandbox can use but never read

A command's result carries at most 64 KiB of each stream for runs up to 60 seconds, and 1 MiB for longer runs. When output is dropped, stdoutTruncated is set. For larger logs, the agent writes the output to a file and reads that file (MCP).

Why run the code remotely

  • Your laptop stays clean. Package installs, post-install scripts and test servers run on a machine with its own kernel. You can discard that machine.
  • Network rules hold. The allow list above applies to root inside the sandbox. A test that tries to send data to an outside host fails (turn off sandbox internet).
  • Keys stay out. A token stored with runtime_secrets reaches the sandbox as a placeholder. The proxy adds the real value only for its hosts (secrets sandboxes never see).
  • State survives. Pause keeps files, memory and running processes for 1 to 365 days. Forks give 1 to 100 running copies, so you can try alternatives.

Cost

Runtime bills CPU on use at $0.025 per vCPU-hour, with a floor of a twentieth of a vCPU. Reserved memory costs $0.0075 per GiB-hour. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while waiting and $0.08 an hour at full CPU (pricing). Cursor bills its model use on your Cursor plan. Every Runtime account gets 100 free hours of a 1 GB machine in the first 30 days, with no card needed:

Terminalnpx withruntime sandboxes run -- node --version

The same MCP setup for other agents is covered in Claude Code, Codex and Gemini CLI. Model Context Protocol explains how the tools reach the agent.

Sources

Checked 25 October 2026.

Facts on this page were checked on 25 October 2026.

Related.

100 free hoursin your first 30 days.

of a 1 GB machine

  • No credit card
  • Four sandboxes at once, 2 vCPU and 4 GiB each
  • Then prepaid credit from $10, no plan fee
Start free, no card
Start free, no card