Sandbox

​

How OS-level isolation works

• macOS — Seatbelt (the built-in macOS sandbox) profiles restrict filesystem and process access.
• Linux and WSL2 — bubblewrap with a seccomp filter provides the same confinement.
• Network (all platforms) — outbound traffic is routed through an HTTP/SOCKS filtering proxy that permits only the allowed domains (Factory’s own domains are always allowed).

​

Isolation modes

• per-command runs each Droid-initiated action through the sandbox individually. Shell commands (and their child processes) are confined at the OS level; other tools are mediated by policy checks before each call. The main Droid process itself is not isolated.
• whole-process launches the entire Droid process inside the OS sandbox, so the main process and everything it spawns (MCP transports, subagents) is isolated too. Its own network requests — not just those from the Execute tool — are filtered against allowedDomains, with interactive domain prompts in TUI mode. If the sandbox cannot be established at startup (unsupported platform or a failed isolation check), Droid refuses to start rather than running unsandboxed.

​

Enable and configure the sandbox

{
  "sandbox": {
    "enabled": true
  }
}

​

Default access policies

​

Full settings reference

{
  "sandbox": {
    "enabled": true,
    // Isolation scope: "per-command" (default) or "whole-process"
    "mode": "per-command",
    "filesystem": {
      // Additional writable paths beyond CWD (which is always writable)
      "allowWrite": ["/tmp/build-output", "~/.config"],
      // Deny writes to specific subpaths even if parent is in allowWrite
      "denyWrite": ["/tmp/build-output/cache/locks", "~/.config/secrets"],
      // Block reads to specific paths (everything else is readable)
      "denyRead": ["~/.aws/credentials", "~/.ssh/id_rsa"]
    },
    "network": {
      // Only these domains are reachable (Factory's own domains always included)
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

​

Organization controls

• Org-level denyWrite/denyRead settings cannot be overridden by user “Allow always”
• Violation prompt shows “(organization policy)” when the deny comes from org settings
• Admins can set the sandbox isolation mode (per-command or whole-process) org-wide from Enterprise Controls

​

Coverage and enforcement

• File tools (Read, Edit, Create, LS, Grep, Glob, ApplyPatch) — checked before every operation, enforcing denyRead for reads and allowWrite/denyWrite for writes
• Execute tool — shell commands run inside the OS sandbox, with network routed through a filtering proxy for domain-level control
• FetchUrl — network requests are checked against allowedDomains
• WebSearch — network requests are checked against allowedDomains
• MCP tools — filesystem and network requests are checked; locally launched servers receive a minimal environment (ambient host environment variables are dropped, keeping only a safe operational allowlist plus keys set in mcp.json)
• Subagents (Task tool) — delegated subagents inherit the parent sandbox policy
• Hooks — hook commands (PreToolUse, PostToolUse, etc.) are wrapped by the sandbox and run with the same proxy/runtime env as the Execute tool; if the sandbox cannot be established the hook is blocked instead of running on the host

​

When something is blocked

• Sandbox violations interrupt the agent loop with a TUI prompt, even at Auto (High) autonomy
• Options: Allow once, Allow always (persists to settings), Deny — for denyRead/denyWrite violations, “Remove from deny list” replaces “Allow always”
• Execute network violations show a real-time domain prompt with a 60s auto-deny timeout

• Sandbox violations are auto-denied without prompting — no hang, no user interaction required
• The agent receives a denial message and reports it in the output

• Choosing Allow always saves the exception to your user settings (for example, adding a domain to allowedDomains or a path to allowWrite) so it won’t prompt again
• Changes take effect immediately in the current session

• SANDBOX status indicator in footer when sandbox is enabled
• “Sandbox Violation” prompt with violation details (path, domain, reason)

​

Security limitations

• Allowed network egress can still leak data. Every domain in allowedDomains is a channel through which data the agent can read might leave. Keep the allowlist as narrow as your workflow permits.
• A writable path can still be modified. The sandbox limits where writes land, not what is written within the allowed paths — including your own project code under the working directory.
• Your settings files are protected. Sandboxed tool processes cannot write to Droid’s own configuration files (e.g. settings.json), so they cannot silently change sandbox policy.

​

Related

• Autonomy Level — approval policy for tool risk.
• Settings — where sandbox.* lives.
• Hierarchical Settings & Org Control — how org policy merges with user settings.
• Security — broader security model for the Droid CLI.