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.

How Auto-review works

Auto-review applies to shell, MCP, and Fetch tool calls. Cursor checks each call in this order:

A shell command "can run in the sandbox" when it works under the sandbox's file and network limits. Commands that need more access, like full network access, writes outside the workspace, or privileged operations, can't use the sandbox, so they go to the classifier instead.

If a sandboxed command fails on a sandbox restriction, such as a permission error, the agent can rerun it outside the sandbox. The classifier reviews that rerun.

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.

The classifier runs on the Cursor backend. To judge a call, it can make read-only ReadFile, Grep, Glob, and ListDir calls on your machine, for example to read a script the command runs.

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 classifier requirements

Auto-review's classifier runs on small Cursor-managed models. Today it uses Gemini 3.5 Flash Lite, with Claude 4.5 Haiku as the fallback.

Enterprise model access controls apply to both. Keep Claude 4.5 Haiku allowed for the team. Allowing it keeps Auto-review available in Settings > Agents > Approvals & Execution, and Auto-review uses it for every review when Gemini 3.5 Flash Lite is blocked. Blocking Claude 4.5 Haiku can disable Auto-review there, even when team Run Modes includes it. Members then use Allowlist instead.

If Auto-review is grayed out, enable Claude 4.5 Haiku in Team Settings → Models, fully quit and reopen Cursor, then check Approvals & Execution again.

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:

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.

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:

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.

Read access

Read access controls whether the agent can read files outside your workspace without asking you first. It covers the agent's file reads and searches, plus terminal commands that run in the sandbox.

Set it in Settings > Agents > Approvals & Execution > Read Access:

With Workspace selected:

• File reads outside the workspace ask first. The approval card shows the full path and why Cursor is asking. Click Allow to let the read through.
• Searches stay inside the boundary. Grep results skip files outside the workspace and your Read Allowlist.
• Sandboxed commands see less of your machine. On macOS and Linux, a sandboxed command can read the workspace, your Read Allowlist, and the system paths common tools need to run, like system libraries, toolchains, and certificate stores. Commands get a private temp directory for the project instead of the host temp directory.

The workspace boundary also includes this project's folder under ~/.cursor/projects, plus the skills, rules, and plugins folders in ~/.cursor.

Read access doesn't apply in Run Everything mode, which runs every call without checks, so the setting is hidden there.

Read Allowlist

Add paths the agent can read outside the workspace to the Read Allowlist in the same settings section. In Auto-review, expand Allowlist Options to find it. The list only applies when Read Access is Workspace.

• Folders. An absolute folder path like /opt/shared/design-tokens allows everything under it.
• Globs. A pattern with *, like ~/notes/*.md, allows the files it matches. Sandboxed commands can't match globs, so they get read access to the pattern's parent folder.
• Home directory. ~ expands to your home directory.

Configure read access in sandbox.json

Set readBoundary and additionalReadPaths in sandbox.json to configure read access per machine or per project:

{  "readBoundary": "workspace",  "additionalReadPaths": ["/opt/shared/design-tokens", "~/notes/*.md"]}

A value in sandbox.json replaces the one in Cursor settings, and the project file wins over ~/.cursor/sandbox.json. Settings show which file controls the value.

In the CLI, set sandbox.readBoundary in cli-config.json and add Read(...) entries to permissions.allow for the allowlist. sandbox.json overrides both.

Team read policy

Admins on Enterprise plans can set a read policy for the team in Team Settings > Security & automation, or for an organization group. Turn on Read Controls, then pick a mode:

• System leaves the choice to each member.
• Workspace turns on Workspace for every member. Their setting shows as controlled by the admin, and approval cards explain that the read needs approval under the team's read policy.

With Workspace, the team's Read Allowlist adds to each member's own list. Turn off Read Control User Extensions to apply only the team list and ignore paths from member settings and sandbox.json.

How sandboxing works on your platform

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.

Docker and container automation

A common pattern in automation rules and scripts is running Docker containers that need to match the host user's identity. Because the sandbox remaps the UID on Linux, relying on $(id -u) produces the wrong value. Use the CURSOR_ORIG_* variables instead:

docker run --rm \  --user "${CURSOR_ORIG_UID:-$(id -u)}:${CURSOR_ORIG_GID:-$(id -g)}" \  -v "$PWD:/work" -w /work \  my-image build

The ${CURSOR_ORIG_UID:-$(id -u)} fallback ensures the command also works outside the sandbox, where the variables are not set.

Network access

Choose how sandboxed terminal commands access the network:

*.cloudflarestorage.com*.docker.com*.docker.io*.googleapis.com*.githubusercontent.com*.gvt1.com*.public.blob.vercel-storage.com*.yarnpkg.comalpinelinux.organaconda.comapache.orgapt.llvm.orgarchive.ubuntu.comarchlinux.orgawscli.amazonaws.comazure.combinaries.prisma.shbitbucket.orgcentos.orgcloudflarestorage.comcocoapods.orgcodeload.github.comcpan.orgcrates.iodebian.orgdl.google.comdocker.comdocker.iodot.netdotnet.microsoft.comeclipse.orgfedoraproject.orgfiles.pythonhosted.orgfonts.gstatic.comgcr.ioghcr.iogithub.comgitlab.comgolang.orggoogle.comgoproxy.iogradle.orghaskell.orghashicorp.comhex.pmindex.crates.iojava.comjava.netjson-schema.orgjson.schemastore.orgk8s.iolaunchpad.netmaven.orgmcr.microsoft.commetacpan.orgmicrosoft.commise.runnodejs.orgnpm.duckdb.orgnpmjs.comnpmjs.orgnuget.orgoracle.compackagecloud.iopackages.microsoft.compackagist.orgpkg.go.devplaywright.azureedge.netppa.launchpad.netproxy.golang.orgpub.devpublic.blob.vercel-storage.compublic.ecr.awspypa.iopypi.orgpypi.python.orgpythonhosted.orgquay.ioregistry.npmjs.orgregistry.yarnpkg.comrepo.maven.apache.orgruby-lang.orgrubygems.orgrubyonrails.orgrustup.rsrvm.iosecurity.ubuntu.comsh.rustup.rssourceforge.netspring.iostatic.crates.iostatic.rust-lang.orgsum.golang.orgswift.orgubuntu.comvisualstudio.comyarnpkg.comziglang.org

Other protections

Run Modes and sandboxing are not the only safety controls. These protections can require approval even when a mode would otherwise run automatically:

Team controls

Admins can override which modes are available for their users, configure the sandbox networking rules for terminal commands, set a team read policy, and more. All of these settings are available in the web dashboard.

Team settings take precedence over individual and project configuration. Use them when you want a consistent baseline for everyone. If you enable Auto-review for the team, keep one of the models the classifier needs allowed under model access control.

Changelog