dev/docs/sandbox.md

Sandbox & approvals

Approval modes

We've chosen a powerful default for how Hanzo Dev works on your computer: Auto. In this approval mode, Hanzo Dev can read files, make edits, and run commands in the working directory automatically. However, Hanzo Dev will need your approval to work outside the working directory or access network.

When you just want to chat, or if you want to plan before diving in, you can switch to Read Only mode with the /approvals command.

If you need Hanzo Dev to read files, make edits, and run commands with network access, without approval, you can use Full Access. Exercise caution before doing so.

Defaults and recommendations

• Hanzo Dev runs in a sandbox by default with strong guardrails: it prevents editing files outside the workspace and blocks network access unless enabled.
• On launch, Hanzo Dev detects whether the folder is version-controlled and recommends:
  • Version-controlled folders: Auto (workspace write + on-request approvals)
  • Non-version-controlled folders: Read Only
• The workspace includes the current directory and temporary directories like /tmp. Use the /status command to see which directories are in the workspace.
• You can set these explicitly:
  • dev --sandbox workspace-write --ask-for-approval on-request
  • dev --sandbox read-only --ask-for-approval on-request

Can I run without ANY approvals?

Yes, you can disable all approval prompts with --ask-for-approval never. This option works with all --sandbox modes, so you still have full control over Hanzo Dev's level of autonomy. It will make its best attempt with whatever constraints you provide.

Common sandbox + approvals combinations

Intent	Flags	Effect
Safe read-only browsing	--sandbox read-only --ask-for-approval on-request	Hanzo Dev can read files and answer questions. Hanzo Dev requires approval to make edits, run commands, or access network.
Read-only non-interactive (CI)	--sandbox read-only --ask-for-approval never	Reads only; never escalates
Let it edit the repo, ask if risky	--sandbox workspace-write --ask-for-approval on-request	Hanzo Dev can read files, make edits, and run commands in the workspace. Hanzo Dev requires approval for actions outside the workspace or for network access.
Auto (preset)	--full-auto (equivalent to --sandbox workspace-write + --ask-for-approval on-failure)	Hanzo Dev can read files, make edits, and run commands in the workspace. Hanzo Dev requires approval when a sandboxed command fails or needs escalation.
YOLO (not recommended)	--dangerously-bypass-approvals-and-sandbox (alias: --yolo)	No sandbox; no prompts

Note: In workspace-write, network is disabled by default unless enabled in config ([sandbox_workspace_write].network_access = true).

Fine-tuning in config.toml

# approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"

# full-auto mode
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# Optional: allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

You can also save presets as profiles:

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

Experimenting with the Hanzo Dev Sandbox

To test to see what happens when a command is run under the sandbox provided by Hanzo Dev, we provide the following subcommands in the CLI:

# macOS
dev sandbox macos [--full-auto] [COMMAND]...

# Linux
dev sandbox linux [--full-auto] [COMMAND]...

# Legacy aliases
dev debug seatbelt [--full-auto] [COMMAND]...
dev debug landlock [--full-auto] [COMMAND]...

Platform sandboxing details

The mechanism Hanzo Dev uses to implement the sandbox policy depends on your OS:

• macOS 12+ uses Apple Seatbelt and runs commands using sandbox-exec with a profile (-p) that corresponds to the --sandbox that was specified.
• Linux uses a combination of Landlock/seccomp APIs to enforce the sandbox configuration.

Note that when running Linux in a containerized environment such as Docker, sandboxing may not work if the host/container configuration does not support the necessary Landlock/seccomp APIs. In such cases, we recommend configuring your Docker container so that it provides the sandbox guarantees you are looking for and then running dev with --sandbox danger-full-access (or, more simply, the --dangerously-bypass-approvals-and-sandbox flag) within your container.