Overview

Sandbox is one of DuckAgent’s core safety features. It controls local tool execution with a JSON policy: filesystem mounts, path rules, ordinary network allow/ask/deny behavior, environment inheritance, secret handling, MCP tool policy, and shell command policy.

The goal is simple: DuckAgent should be useful on your real machine without acting like it owns your whole machine.

Sandbox config lives in root config:

~/.duckagent/config.json

It is not profile-scoped. Switching profiles should not silently weaken the local execution boundary.

Default

If no sandbox is configured, DuckAgent uses:

{
  "sandbox": {
    "preset": "workspace"
  }
}

The default active preset is workspace: read broadly, write only to the workspace and temp directory, keep common secrets hidden, keep .git read-only, route ordinary network through the managed proxy, and ask before risky shell command classes.

Preset	When to use	Main behavior
workspace	Daily development and agent work	Broad read access, workspace/temp writes, guarded network proxy, and approval for risky shell commands.
readonly	Review and inspection	Read-only filesystem, denied network, and the same risky shell approval table.
danger	Fully trusted local execution	Direct process execution, broad filesystem access, direct network, and no default shell approval table.

Use --sandbox <preset> to override one process:

duck --sandbox readonly
duck --sandbox danger

Use duck sandbox get <preset> to inspect the resolved preset JSON that DuckAgent will use. The Presets page includes the full default workspace JSON.

Network and env secrets

In proxy network mode, DuckAgent starts a managed local proxy and sets proxy-related environment variables for sandboxed child processes. Sandbox env can also define secret-backed network requests: the child receives a placeholder value and a local reverse-proxy URL, while the proxy injects the real secret as a request header.

See Environment & Secrets for the exact config shape.

Windows behavior

On Windows, users should not normally run setup commands by memory. First run checks the active sandbox after model/provider setup. If a non-danger preset needs elevated setup, DuckAgent prompts the user to set up the default sandbox, switch to danger, or quit.

The Windows commands are for preflight, repair, and troubleshooting:

duck sandbox windows-setup-status
duck sandbox setup-windows

Read next

• Presets includes the shipped JSON for workspace, readonly, and danger.
• Filesystem Rules explains read/write boundaries.
• Network Rules explains proxy, deny, allow, and approval behavior.
• Environment & Secrets explains inherited variables and secret placeholders.
• Tool & Shell Permissions explains allow, ask, and deny policy.
• Windows Setup explains elevated setup.