# 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 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`:

```bash no-run
curl 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 no-run
{
  "mcpServers": {
    "runtime": { "command": "npx", "args": ["-y", "withruntime", "mcp"] }
  }
}
```

Then check the setup:

```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. The tool shows a link and a code. Approve **Connect agent** in the
browser. Every Runtime tool then appears, with no restart needed
([MCP](/docs/mcp#add-it-to-your-agent)). 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](/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)
```

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](/docs/javascript#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](/docs/mcp#a-typical-session)).

## 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](/how-to/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](/docs/security#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](/docs/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:

```bash no-run
npx withruntime sandboxes run -- node --version
```

The same MCP setup for other agents is covered in [Claude Code](/integrations/claude-code),
[Codex](/integrations/codex) and [Gemini CLI](/integrations/gemini-cli).
[Model Context Protocol](/glossary/model-context-protocol) explains how the
tools reach the agent.

## Sources

Checked 25 October 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.10.22-27dcf5f`,
  `agent` and `cursor-agent` in `~/.local/bin`
- [Cursor CLI parameters](https://cursor.com/docs/cli/reference/parameters):
  `--trust`, `--approve-mcps`, `--force` and its alias `--yolo`

Facts on this page were checked on 25 October 2026.