Permissions and Sandboxing
An agent that can run shell commands and edit files needs limits. Permissions decide which tool calls run and which need approval; sandboxing decides how isolated a command is when it does run. The two answer different questions: permissions are about whether, sandboxing is about where.
Gating tool calls
Section titled “Gating tool calls”Each tool call passes through a permission gate before it runs. Two settings shape the gate: an allow list of patterns that are always permitted, and auto-approve, which lets matching calls run without asking. A call that matches neither prompts you for approval inline. This is what lets a trusted command, like a read or a known-safe build step, run unattended while a risky one still stops for a decision.
For unattended runs where you have accepted the risk, --force (also spelled yolo and dangerously-skip-permissions) skips the prompts entirely. The name is deliberately blunt: it removes the gate, so it is for sandboxed or disposable environments rather than your main machine.
Multi-actor access
Section titled “Multi-actor access”The engine has a permission layer that goes beyond a single user. It holds an access policy over actor, resource, and action tuples, and it issues signed bearer tokens with a time limit so a caller’s access can be scoped and expired. A single system actor is the internal bypass for engine-level callers. This is the machinery behind safely letting more than one actor, including sub-agents, share an engine.
Sandboxing
Section titled “Sandboxing”Sandboxing isolates a command from the host. The engine has a multi-backend sandbox layer: bubblewrap on Linux, sandbox-exec on macOS, AppContainer on Windows, and Docker as a cross-platform option. Each backend runs a command under a manifest that constrains its network and system access.
The default posture is to fail closed. If no real sandbox backend is available, the sandbox layer refuses to run rather than quietly dropping to host-level execution. Running without isolation requires an explicit opt-in through an environment variable, and the engine logs a warning while it stays in that state. The point is that unsandboxed execution is a deliberate choice, never an accident.
Team sandboxes and swarm worktree isolation build on this so that parallel work stays separated rather than stepping on each other.