# 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`: ```bash no-run curl 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 no-run { "mcpServers": { "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] } } } ``` Then check it: ```bash no-run agent mcp list agent 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](/docs/mcp#add-it-to-your-agent)). 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](/docs/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. ```ts check import { 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); ``` ```python check import subprocess from withruntime import Sandbox repo = "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](/docs/javascript#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](/docs/mcp#a-typical-session)). ## 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](/how-to/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](/docs/security#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](/docs/pricing)). Cursor bills its model use on your Cursor plan. New Runtime accounts get 50 sandbox hours free, no card: ```bash no-run npx withruntime sandbox run --trial -- node --version ``` The same MCP setup for other agents is in [Claude Code](/integrations/claude-code), [Codex](/integrations/codex) and [Gemini CLI](/integrations/gemini-cli), and [Model Context Protocol](/glossary/model-context-protocol) explains how the tools reach the agent. ## Sources Checked 25 September 2026. - [Cursor CLI headless](https://cursor.com/docs/cli/headless): the installer, `agent -p`, `--force`, `--output-format`, `CURSOR_API_KEY` - [Cursor CLI MCP](https://cursor.com/docs/cli/mcp): `mcp.json`, `agent mcp list`, `agent mcp list-tools`, `--approve-mcps` - [Cursor installer](https://cursor.com/install): 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.