Sandbox

Documentation Index

Fetch the complete documentation index at: https://docs.factory.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Default access policies (when sandbox is enabled)

​

What’s included

• File tools (Read, Edit, Create, LS, Grep, Glob, ApplyPatch) — checkFileAccess() before every operation, enforcing denyRead for reads and allowWrite/denyWrite for writes
• Execute tool — shell commands wrapped in OS sandbox (Seatbelt/bubblewrap) with network routed through SRT’s filtering proxy for domain-level control
• FetchUrl — checkNetworkAccess() against allowedDomains
• Note — main Droid process, MCPs and subagent are not isolated yet.

• Sandbox violations interrupt the agent loop with a TUI prompt, even at Auto (High) autonomy
• Three options: Allow once, Allow always (persists to settings), Deny
• For denyWrite violations: “Remove from deny list” option instead of “Allow always” (removes the entry from denyWrite in settings)
• For denyRead violations: “Remove from deny list” option instead of “Allow always”
• For Execute network violations: real-time domain prompts via SRT’s proxy callback with 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

• File write violations (outside CWD): adds parent directory to sandbox.filesystem.allowWrite in user settings
• denyWrite violations: removes the entry from sandbox.filesystem.denyWrite
• denyRead violations: removes the entry from sandbox.filesystem.denyRead
• Domain violations: adds domain (with wildcard for 3+ part domains, e.g. registry.npmjs.org -> *.npmjs.org) to sandbox.network.allowedDomains
• Changes take effect immediately in the current session

• Org-level denyWrite/denyRead settings cannot be overridden by user “Allow always”
• Violation prompt shows “(organization policy)” when the deny comes from org settings

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

​

Settings config

{
  "sandbox": {
    "enabled": true,
    "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.ai always included)
      "allowedDomains": ["github.com", "*.npmjs.org"],
    },
  },
}

​

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.