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

Auto-review's classifier runs on a small Cursor-managed model. Today that is Claude 4.5 Haiku or GPT-5.4 Mini.

Enterprise model access controls apply. Auto-review is available when at least one of those models is allowed for the team. Blocking all of them disables Auto-review in Settings > Agents > Approvals & Execution, even when team Run Modes includes it. Members then use Allowlist instead.

If Auto-review is grayed out, enable those models 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.

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, as well as configure the sandbox networking rules for terminal commands, 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