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.

Cursor CLI keeps its editor-grade agent on your laptop while Runtime takes the risky part, running 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. A sandbox starts in 351 ms at the median, from create request to first Python result (20 runs, 24 September 2026), so the agent can use a fresh machine for each experiment. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while idle. agent mcp list-tools reached Runtime's server from this configuration in Runtime's check on 23 September 2026, and the installer on 25 September 2026 fetched Cursor CLI build 2026.09.23-86fc751.

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: ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one repo. Add Runtime:

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

Then check it:

Terminalagent mcp listagent mcp list-tools runtime

The first time, Runtime offers one tool, runtime_connect. Ask the agent to use it, and it shows a link and a code; approve Connect agent in the browser and every Runtime tool appears with nothing to restart (MCP). A machine already signed in with npx withruntime login skips the step. No key is written into mcp.json, which makes the project-level file safe to commit.

To skip the bridge, Cursor also takes remote servers that sign in through the browser; point it 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)

What the flags do, from Cursor's headless page and the CLI's own help:

  • -p, --print runs one prompt without the interactive UI.
  • --approve-mcps approves the configured MCP servers, so the Runtime tools load with nobody 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, and RUNTIME_API_KEY from your secret manager does the same for Runtime's server.

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

The tools Cursor's agent uses

Tool What it is for
runtime_sandbox_create A new microVM, running when the call returns
runtime_sandbox_list Find a sandbox by name or label
runtime_sandbox_exec Run a command; returns exit code, stdout and stderr
runtime_sandbox_files_write Copy a file from the local repo into the sandbox
runtime_sandbox_previews_create Share a dev server at a private HTTPS address
runtime_sandbox_network_set Narrow or cut the sandbox's internet
runtime_secrets_set 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 ones, with stdoutTruncated set when output was dropped; for bigger logs the agent writes them to a file and reads that (MCP).

Why run the code remotely

  • Your laptop stays clean. Package installs, post-install scripts and test servers run in a machine with its own kernel, and it can be thrown away.
  • Network rules hold. The allow list above applies to root inside the sandbox, so a test that tries to phone home fails (turn off sandbox internet).
  • Keys stay out. A token stored with runtime_secrets_set reaches the sandbox as a placeholder; the proxy adds the value only for its hosts (secrets sandboxes never see).
  • State survives. Pause keeps files, memory and running processes for 1 to 365 days, and forks give 1 to 10 running copies to try alternatives.

Cost

Runtime bills CPU on use at $0.025 per vCPU-hour, with a floor of a twentieth of a vCPU, and reserved memory at $0.0075 per GiB-hour. A 2 vCPU, 4 GiB sandbox is $0.03125 an hour waiting and $0.08 an hour at full CPU (pricing). Cursor bills its model use on your Cursor plan. New Runtime accounts get 50 sandbox hours free, no card:

Terminalnpx withruntime sandbox run --trial -- node --version

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

Sources

Checked 25 September 2026.

  • Cursor CLI headless: the installer, agent -p, --force, --output-format, CURSOR_API_KEY
  • Cursor CLI MCP: mcp.json, agent mcp list, agent mcp list-tools, --approve-mcps
  • Cursor installer: build 2026.09.23-86fc751, agent and cursor-agent in ~/.local/bin; that build's help lists --trust, --approve-mcps and --force

Facts on this page were checked on 25 September 2026.

Claim 50 hours free