Sandboxing

Watchfire runs coding agents inside a macOS sandbox using sandbox-exec. This limits what the agent process can access, reducing the blast radius of any unintended actions.

How It Works

Every agent process is wrapped in a sandbox:

sandbox-exec -f <profile> claude --dangerously-skip-permissions --append-system-prompt "..." [--prompt "..."]

The sandbox profile is embedded in the Watchfire binary and is not user-visible or editable. This ensures consistent security boundaries across all agent sessions.

Security Model

Aspect	Behavior
Sandbox	Agent process runs inside macOS sandbox-exec
Profile	Custom profile restricting filesystem/network access
Profile storage	Embedded in binary, not user-visible
Agent permissions	Agent runs in "yolo mode" — full permissions within sandbox
Claude Code flag	--dangerously-skip-permissions

The key insight: the agent has free reign inside the sandbox. The sandbox limits what "free reign" actually means.

What's Allowed

Inside the sandbox, agents can:

• Read most of the filesystem (project files, system libraries, tools)
• Write to the project directory and temporary directories
• Execute installed tools (git, npm, make, etc.)
• Network — Full network access for package installation, API calls, etc.

Write-Allowed Paths

Beyond the project directory and temp dirs, agents can write to:

• Package manager caches — ~/.npm, ~/.yarn, ~/.pnpm-store, ~/.cache, ~/Library/Caches/*
• Dev tool caches — ~/.cargo, ~/go, ~/.rustup
• Claude config — ~/.claude
• CLI tool config — ~/Library/Application Support

What's Blocked

The sandbox restricts read and write access to sensitive locations:

• ~/.ssh — SSH keys and configuration
• ~/.aws — AWS credentials
• ~/.gnupg — GPG keys
• ~/.netrc — Network credentials
• ~/.npmrc — npm credentials
• ~/Desktop, ~/Documents, ~/Downloads — Personal directories
• ~/Music, ~/Movies, ~/Pictures — Media directories
• .env files — Environment secrets
• .git/hooks — Git hooks (prevents hook injection)

Why sandbox-exec?

macOS sandbox-exec provides kernel-level enforcement through the App Sandbox framework. Unlike userspace restrictions:

• The agent process cannot bypass the sandbox
• Even if the agent writes malicious code, it runs within the same sandbox
• Child processes inherit the sandbox profile

Platform Support

Sandboxing is currently macOS-only, as it relies on sandbox-exec. On other platforms, agents run without sandbox restrictions. Linux sandboxing support (via seccomp/AppArmor) is planned for a future release.

Agent Permissions Flow

The --dangerously-skip-permissions flag tells Claude Code to skip its own permission prompts. This is safe because the macOS sandbox enforces stricter boundaries at the OS level.