Cursor sandbox: sandbox.json, network allowlist and run modes
How does Cursor's agent terminal sandbox work and how do I configure it?
On macOS and Linux, Cursor can run agent terminal commands in a sandbox that limits writes to the workspace and blocks network access you have not allowed. Whether a command enters the sandbox depends on your run mode in Settings > Agents > Approvals & Execution. You tune the sandbox with sandbox.json in ~/.cursor/ or <project>/.cursor/, including a networkPolicy allow and deny list.
Compare: sandbox modes in every AI coding agent →
What the sandbox restricts
- Commands can read and write inside the workspace.
- /tmp and platform temp directories are writable unless you set disableTmpWrite.
- Network access is limited by the network mode and your sandbox.json allowlist.
- Some paths are always write protected, including .cursor/*.json, .vscode/**, .git/hooks/**, .git/config and .cursorignore.
- Private IPv4 and IPv6 ranges, loopback and the cloud metadata endpoint are blocked by default.
Reads: with readBoundary "system" (the default) the agent can read outside the workspace. With "workspace" (Cursor 3.23 or later) Cursor asks first, except for paths in the Read Allowlist.
Supported platforms
- macOS: Seatbelt through sandbox-exec. Cursor 2.0 or later, no extra setup.
- Linux: creates a user namespace and remaps the process to UID 0. Uses Landlock, with a Bubblewrap fallback.
Inside the sandbox Cursor sets CURSOR_SANDBOX ("seatbelt" on macOS, "native" on Linux), plus CURSOR_ORIG_UID and CURSOR_ORIG_GID. On Linux, id -u returns 0, so scripts that need your real ID should read CURSOR_ORIG_UID.
How it fits with run modes
Set the run mode in Settings > Agents > Approvals & Execution. Sandboxing is a layer on top of run modes for shell commands.
- Auto-review: allowlisted calls run immediately. Other shell commands go to the sandbox when possible. Calls outside the sandbox go to the classifier.
- Allowlist: allowlisted actions run without approval. With sandboxing enabled, supported shell commands can run in the sandbox.
- Run Everything: every tool call runs automatically, with no sandbox and no classifier.
If a sandboxed command fails on a sandbox restriction, the agent can rerun it outside the sandbox, and the classifier reviews that rerun.
Network modes and the allowlist
- sandbox.json + Defaults (default): your allowlist plus Cursor's built-in defaults for package managers and language tools.
- sandbox.json Only: only domains in your sandbox.json allowlist.
- Allow All: all network access is allowed, regardless of sandbox.json.
.cursor/sandbox.json
{
"networkPolicy": {
"default": "deny",
"allow": [
"registry.npmjs.org",
"pypi.org",
"*.githubusercontent.com"
],
"deny": ["*.internal.corp.example.com"]
}
}Patterns can be exact domains, wildcards like *.example.com (which also match the bare domain) or CIDR ranges. Deny always beats allow. URL paths are ignored.
sandbox.json keys
- type: "workspace_readwrite" (default), "workspace_readonly" or "insecure_none" (sandbox disabled).
- additionalReadwritePaths: extra read and write paths (only with workspace_readwrite).
- additionalReadonlyPaths: extra read-only paths.
- readBoundary: "system" (default) or "workspace".
- additionalReadPaths: Read Allowlist paths and globs, used when readBoundary is "workspace".
- disableTmpWrite: true removes write access to /tmp and temp directories.
- enableSharedBuildCache: true shares npm, cargo and pip caches between sandboxed and unsandboxed commands.
- networkPolicy: default ("allow" or "deny", default "deny"), allow, deny.
~/.cursor/sandbox.json applies to all projects. <project>/.cursor/sandbox.json applies to one project and wins when both exist. Path lists and deny lists are combined. Team admin policies and Cursor's hardcoded rules apply on top and cannot be weakened by local files.
Sources
More Cursor guides
- How to allow Cursor to run all commands: Run Everything, allowlist and sandbox
- Cursor Privacy Mode: telemetry, training and data retention
- Add MCP servers to Cursor with mcp.json
- Keep files out of Cursor with .cursorignore
- Cursor CLI: install, headless mode, permissions and CI
- Cursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codes
- Cursor settings: settings.json, Cursor Settings and the ~/.cursor config files
- Cursor browser agent: @browser, browser automation and approval modes
- Cursor subagents: .cursor/agents, frontmatter, built-in Explore and Browser
- Cursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API)
- Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.md
- Cursor skills and custom slash commands: .cursor/skills SKILL.md, .cursor/commands and /migrate-to-skills
Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →