agent sandbox run <cmd> [args...]

Runs a single command in a sandbox with read/write access to the workspace.

agent sandbox run <cmd> [args...] runs exactly one command in isolation, by default with read/write access to the workspace (--sandbox, default true) and no network access (--network, default false). Extra paths can be exposed via --allow-paths or --readonly-paths, and unwanted files blocked via --blocked-patterns (gitignore syntax); --sb-debug writes debug logs to a temp folder.

🎬 AS A SHORT VIDEO

Runs a single command in a sandbox with read/write access to the workspace.

✅ WHEN TO USE IT?

Test an unfamiliar install/build script in isolation before it touches the real workspace

agent sandbox run npm install

Run a command with network access even though the sandbox otherwise blocks it

agent sandbox run --network curl https://example.com/healthz

⛔ WHEN NOT TO?

Several commands need to run isolated persistently, not just one

agent sandbox run is meant for exactly one single command.

Better: Use agent sandbox enable so the sandbox policy applies to all future commands the CLI runs

The command needs access outside the workspace directory

Without extra flags, access is limited to the workspace.

Better: Specify --allow-paths or --readonly-paths with the additionally needed paths

SOURCES

Cursor Docs — CLI Reference: Parameters ↗ cursor.com