Limit what commands can touch

Check what your platform provides

macOS

Seatbelt, automatically, when its startup check succeeds. Commands get broad read access, writes limited by the sandbox mode, and network only when the mode allows it.

Linux

Bubblewrap, but only if you turn it on (below). Without it, commands run with no OS sandbox.

Windows

No OS sandbox today. Your approval setting and Windows permissions still apply.

External service

With sandbox_backend = "opensandbox", shell commands run on an OpenSandbox-compatible service you configure; its isolation is that service's to guarantee.

Ask Codewhale which one it found:

codewhale doctor
codewhale setup --status

Both report the sandbox that is actually available after your settings are applied. Codewhale never counts source code that is not wired in as a sandbox.

Turn on the Linux sandbox

Install bubblewrap, then opt in with one line in ~/.codewhale/config.toml:

sudo apt install bubblewrap      # Fedora: dnf install bubblewrap · Arch: pacman -S bubblewrap

# ~/.codewhale/config.toml
prefer_bwrap = true

Codewhale uses /usr/bin/bwrap only when that file exists and is executable. Commands then see a read-only view of the system, write only where the sandbox mode allows, and have no network unless the mode enables it.

Choose how much a command may write

sandbox_mode = "workspace-write"

read-only

Commands can read but not write.

workspace-write

Commands can write inside the workspace and temporary folders, and nowhere else.

danger-full-access

No OS sandbox. Use only on a machine or container you are prepared to lose.

external-sandbox

You are already running inside isolation, so Codewhale adds none of its own.

The first two are enforced only where a sandbox is available — on Linux without bubblewrap, and on Windows, they are settings without an OS wrapper behind them. A repository's own config can make the mode stricter, never looser. For one headless run, pass --sandbox <mode> to codewhale exec; --auto approves tools but never widens the sandbox.

Know the limits

• Availability is checked before a command starts, but the sandbox can still fail at launch because of host policy or container restrictions.
• A “Permission denied” from a command is not proof that the sandbox blocked it. Codewhale labels a denial as the sandbox's only when the sandbox itself reported it.
• No sandbox protects against kernel vulnerabilities or every kind of resource exhaustion.

Next