pages/agent/security/run-modes.txt

route: /docs/agent/security/run-modes
title: Run Modes
description: Choose how Cursor Agent runs shell, MCP, and Fetch calls with Auto-review, allowlists, sandboxing, and enterprise controls.

Run Modes
Run Modes control how the Cursor agent runs tool calls, and when Cursor interrupts you for approval.
Use them to decide how much autonomy the agent gets for shell commands, MCP tools, and Fetch calls. The safest useful setup for most people is Auto-review. It runs known-safe calls, sandboxes shell commands when it can, and asks a classifier to review anything else.
Pick a mode
In the desktop application, go to Settings > Agents > Approvals & Execution.
Mode
What runs without asking
Sandbox
Classifier
Use it when
Auto-review
Allowlisted calls run immediately. Other shell commands run in the sandbox when possible. Calls that do not use the sandbox go to the Auto-review classifier.
Yes, for shell commands
Yes
You want fewer prompts with a safety review before higher-risk calls run.
Allowlist
Actions in your allowlist run without approval. With sandboxing enabled, supported shell commands can run in the sandbox.
Optional, for shell commands
No
You want deterministic behavior with a small set of trusted repeat actions.
Run Everything
Every tool call runs automatically.
No
You accept the risk and want zero prompts.
How Auto-review works
Auto-review applies to shell, MCP, and Fetch tool calls. Cursor checks each call in this order:
The execution lifecycle of agent actions on Auto-review mode. Allowlisted calls run immediately, other shell commands run in the sandbox when possible, and anything else goes to the classifier, which can allow the call, ask the agent to take a different approach, or ask you to approve.
A shell command "can run in the sandbox" when it works under the sandbox's file and network limits. Commands that need full system access, like writes outside the workspace or privileged operations, can't be sandboxed, so they go to the classifier instead.
Sandboxing is a layer on top of Run Modes for shell commands. It controls where a supported terminal command runs, not whether the mode uses the Auto-review classifier.
When the classifier blocks a call, Cursor can try another approach. If the agent decides that the action makes sense despite what the classifier said, Cursor will show you an approval prompt.
Auto-review is not a security boundary
The classifier can make mistakes. It can allow a call you would have blocked, or block a call you would have allowed.
Configuring Auto-review
Configuration is not required for Auto-review to work well. If there are specific actions you always want to review manually, describe them in plain English.
The easiest way to set this up is to ask the Cursor agent to do it. Tell it something like "I want every AWS CLI command to go through approval first," and it edits your permissions.json for you.
You can also edit the file yourself. Auto-review reads permissions.json from two locations:
Location
Scope
~/.cursor/permissions.json
Applies to all project directories on your machine.
<project-dir>/.cursor/permissions.json
Applies to one project directory. Commit it when the project should share the same guidance.
If both files exist, Cursor merges them. Your personal instructions and the project instructions both apply.
Teams can also define a global Auto-review configuration in the dashboard. When a team configuration is defined, it takes priority and Cursor ignores the user-level and project-level files.
Both local files use the same schema. Each instruction is a plain-English sentence, so a request like "I want every AWS CLI command to go through approval first" maps straight onto block_instructions:
{
"autoRun": {
"allow_instructions": [],
"block_instructions": [
"Every AWS CLI command should go through approval first.",
"Every command that modifies Kubernetes resources should go through approval first."
]
}
allow_instructions describe actions Auto-review should lean toward allowing.
block_instructions describe actions Auto-review should lean toward blocking so the agent can choose another path or ask you to approve.
For more on policy design, read Governing agent autonomy with Auto-review.
Sandboxing
Sandboxing lets Cursor run terminal commands without giving them full machine access. A sandboxed command can work in your project, but it cannot freely read protected files, write outside approved paths, or contact arbitrary network destinations.
For the engineering deep dive, read Implementing a secure sandbox for local agents.
permissions.json and sandbox.json do different jobs
permissions.json steers which calls Auto-review runs automatically and which it reviews. sandbox.json controls what a sandboxed command can reach, like network domains and extra readable or writable paths. You don't need either file to get started.
Access
Default sandbox behavior for terminal commands
Workspace files
Read and write access inside the workspace. .cursorignore can hide files from the agent.
Protected paths
Cursor protects paths like .git/config, .git/hooks, .vscode, .cursorignore, and sensitive Cursor config files.
Network
Blocked by default, then opened by your network mode and sandbox.json.
Temporary files
/tmp and platform temp directories are writable unless disabled in sandbox.json.
Some commands need full system access and bypass the sandbox. Cursor will indicate when a command runs outside the sandbox and ask for your approval.
Sandbox configuration
Customize sandbox behavior with a sandbox.json file:
Location
Scope
~/.cursor/sandbox.json
Applies to all project directories on your machine.
<project-dir>/.cursor/sandbox.json
Applies to one project directory. Commit it when the project should share the same sandbox rules.
If both files exist, Cursor merges them with the project-level file taking priority. Team-admin policies and Cursor's hardcoded security rules layer on top, so local files cannot weaken those protections.
Use sandbox.json to control network policy, extra readable or writable paths, temporary directory writes, and shared build caches. See the sandbox.json reference for the full schema.
How sandboxing works on your platform
macOSLinux
Cursor uses Seatbelt through sandbox-exec. A generated sandbox profile limits file access, network access, and other process behavior for the full subprocess tree.
Requirements
Cursor v2.0 or later
No extra setup needed
Cursor uses Landlock and seccomp. Landlock applies filesystem restrictions. Seccomp blocks unsafe syscalls.
Requirements
Kernel 6.2 or later with Landlock v3 support (CONFIG_SECURITY_LANDLOCK=y)
Unprivileged user namespaces enabled
If your kernel does not meet these requirements, Cursor falls back to asking for approval before running commands.
AppArmor setup (remote environments and CLI only)
Local desktop installations need no setup. The Cursor desktop package ships with the required AppArmor profile.
Some distributions restrict user namespaces through AppArmor, and remote environments and the standalone CLI do not ship the profile. If sandbox creation fails there with a user-namespace permissions error, install the AppArmor package for your distribution.
Debian / Ubuntu:
curl -fsSL https://downloads.cursor.com/lab/enterprise/cursor-sandbox-apparmor_0.6.0_all.deb -o cursor-sandbox-apparmor.deb
sudo dpkg -i cursor-sandbox-apparmor.deb
RHEL / Fedora:
curl -fsSL https://downloads.cursor.com/lab/enterprise/cursor-sandbox-apparmor-0.6.0-1.noarch.rpm -o cursor-sandbox-apparmor.rpm
sudo rpm -i cursor-sandbox-apparmor.rpm
After installing, restart Cursor or your CLI session for the sandbox to work.
Environment variables
Cursor injects environment variables into every sandboxed child process. These are available to your scripts, build tools, and automation running inside the sandbox.
Variable
Platforms
Description
CURSOR_SANDBOX
macOS, Linux
Set to "seatbelt" (macOS) or "native" (Linux) when the process is running inside the sandbox.
CURSOR_ORIG_UID
macOS, Linux
…