skip to content

In Cursor, what can an Agent terminal command reach inside the sandbox by default, and when does it run outside it?

level: middleimportance: nice to knowfreq 5%

answer

  1. a layer under Run Modes
  2. shell commands only
  3. workspace read-write, protected paths
  4. network: sandbox.json + Defaults
  5. fails, then reruns outside under review

basics

~20 s

A sandboxed Cursor terminal command can read and write the workspace and temp directories, cannot write protected paths, and reaches only allowlisted domains. Commands needing more access run outside the sandbox, after the Auto-review classifier allows them or you approve.

solid answer

~50 s

Sandboxing is a layer on top of Run Modes for **shell commands only**; it controls where a supported command runs, not whether the Auto-review classifier is used. By default a sandboxed command can read and write inside the workspace and write to `/tmp`, while protected paths such as `.git/config`, `.git/hooks`, `.vscode` and `.cursorignore` stay write-protected. Network access is blocked except for what the network mode opens; the default, **sandbox.json + Defaults**, allows your `sandbox.json` allowlist plus Cursor's domains for common package managers, and private and loopback addresses stay blocked. A command runs outside the sandbox when it needs more access (full network, writes outside the workspace, privileged operations) or when it fails on a sandbox restriction and the agent reruns it; under Auto-review the classifier reviews that call, otherwise Cursor asks you. On Linux without Landlock support, Cursor falls back to asking before running commands.

go deeper

for a junior

Recall that Cursor can run Agent's terminal commands in a sandbox, and that a command outside it is flagged and may need your approval.

for a middle

Explain the default reach: workspace read-write, protected paths, temp writes, and the sandbox.json + Defaults network mode, plus the two ways a command leaves.

for a senior

Diagnose sandbox failures such as loopback databases, Linux UID remapping or missing Landlock, and choose what belongs in sandbox.json versus permissions.json.

for a principal

Decide which sandbox network policy a team enforces from the dashboard, knowing local files cannot weaken admin policy.

## Where the sandbox sits Cursor's Agent runs terminal commands on your machine. Two separate mechanisms decide what happens to each one: - **Run Modes** (Auto-review, Allowlist, Run Everything) decide *whether* a call runs without asking. - **Sandboxing** decides *where* a supported shell command runs: inside a restricted environment, or with your normal access. Cursor's docs describe sandboxing as **a layer on top of Run Modes for shell commands**. It does not apply to MCP tools or Fetch calls, and it does not switch the Auto-review classifier on or off. | Run Mode | Sandbox | |---|---| | **Auto-review** | Yes, for shell commands; other shell commands run in it when possible | | **Allowlist** | Optional; with sandboxing enabled, supported commands can run in it | | **Run Everything** | No | The old **Run in Sandbox** mode no longer exists: in Cursor 3.5 it was folded into Allowlist with sandboxing enabled. ## What a sandboxed command can reach by default | Access | Default | |---|---| | **Workspace files** | Read and write inside the workspace | | **Protected paths** | Write-protected, for example `.git/config`, `.git/hooks`, `.vscode`, `.cursorignore` and Cursor's own JSON config under `.cursor/` | | **Network** | Blocked, then opened by the network mode and `sandbox.json` | | **Temporary files** | `/tmp` and platform temp directories are writable unless `sandbox.json` disables it | The **network mode** has three settings: - **sandbox.json Only**: only the domains in your `sandbox.json` allowlist. - **sandbox.json + Defaults**: your allowlist plus Cursor's built-in defaults for package managers and language tools. **This is the default.** - **Allow All**: any destination, regardless of `sandbox.json`. Independently of the mode's domain list, the `sandbox.json` reference says private and loopback addresses (`10.x`, `172.16.x`, `192.168.x`, `127.x`) and the cloud metadata endpoint are blocked by default, to prevent server-side request forgery. ## When a command leaves the sandbox A command "can run in the sandbox" when it works within those file and network limits. It leaves the sandbox in these cases: 1. It needs more than the sandbox gives, such as full network access, writes outside the workspace or privileged operations. Under Auto-review it goes to the **classifier**; under Allowlist, Cursor shows that it will run outside the sandbox and asks for your approval. 2. It ran in the sandbox and **failed on a sandbox restriction**, such as a permission error. The agent can rerun it outside the sandbox, and under Auto-review the classifier reviews that rerun. 3. It matched the **allowlist** under Auto-review: allowlisted calls run immediately, outside the sandbox. 4. The Run Mode is **Run Everything**, which uses no sandbox at all. ## Configuring it Two files in `.cursor/` do different jobs: - **`permissions.json`** steers which calls run automatically and which the Auto-review classifier reviews. - **`sandbox.json`** controls what a sandboxed command can reach: network domains, extra readable or writable paths, temp-directory writes and shared build caches. Each can live in `~/.cursor/` (all projects) or in the project's `.cursor/` (commit it to share). For `sandbox.json`, the two are merged with the project file taking priority, and team-admin policies and Cursor's hardcoded rules layer on top, so local files cannot weaken them. Write protection on the protected paths applies whatever `sandbox.json` says. The main `sandbox.json` fields: - `type`: `"workspace_readwrite"` by default; `"workspace_readonly"` restricts commands to reading, and `"insecure_none"` disables the sandbox entirely. - `additionalReadwritePaths` and `additionalReadonlyPaths`: extra paths a command may use. - `networkPolicy`: `default` is `"deny"`, with `allow` and `deny` lists of domains, wildcards or CIDR ranges; a deny entry always beats an allow entry. - `disableTmpWrite` and `enableSharedBuildCache`: temp-directory writes and caches shared between sandboxed and unsandboxed commands. ## Platform notes - **macOS**: Seatbelt through `sandbox-exec`, applied to the whole subprocess tree. - **Linux**: Landlock for the filesystem and seccomp for syscalls. It needs kernel 6.2 or later with Landlock v3 and unprivileged user namespaces; **without them, Cursor falls back to asking for approval** before running commands. - **Linux identity**: inside the sandbox the process runs as UID 0 in a user namespace, so `id -u` returns 0. Cursor injects `CURSOR_ORIG_UID` and `CURSOR_ORIG_GID` with the real IDs, and `CURSOR_SANDBOX` tells a script it is sandboxed. - **Remote environments and the standalone CLI** may need an AppArmor profile package before the sandbox can start.

  • A sandboxed test command in Cursor can't reach a local database on 127.0.0.1. Why, and what happens next under Auto-review?
    The sandbox blocks loopback and private addresses by default, besides limiting domains, so the connection fails on a sandbox restriction. The agent can rerun the command outside the sandbox, and under Auto-review the classifier reviews that rerun before it runs; if the classifier blocks it, the agent tries another approach or asks you.
  • On Linux, a sandboxed script in Cursor runs a container with --user set from id -u and creates root-owned files. Why?
    Cursor's Linux sandbox creates a user namespace and maps the process to UID 0 inside it, so `id -u` returns 0. Cursor injects `CURSOR_ORIG_UID` and `CURSOR_ORIG_GID` with the real IDs; use them, falling back to `id -u` when the variables are unset outside the sandbox.

  • The sandbox is a fourth Run Mode you choose instead of Auto-review
  • Cursor's sandbox also wraps MCP tool calls and Fetch requests
  • A sandboxed command has no network access of any kind
  • Inside the workspace the sandbox lets the agent rewrite .git/hooks
  • If Linux can't start the sandbox, commands silently run unsandboxed