Limit what commands can touch

Inspect execution policy rules

/permissions

Typed permissions select User, Agent and BuiltinDefault rules in that order. Within one source layer, deny wins over ask and allow; specificity breaks ties.

Hard denied command prefixes cannot be overridden by a typed allow. An allow never removes later safety checks, repository restrictions or sandbox limits.

Read the authorization order and matching rules

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, automatically, once it is installed and verified working (opt out 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.

Enable (or turn off) the Linux sandbox

Install bubblewrap — Codewhale uses it by default. To run Linux commands unwrapped instead, opt out with one line in ~/.codewhale/config.toml:

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

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

Codewhale uses /usr/bin/bwrap only when that file exists, is executable, and a probe shows it can create its sandbox namespaces — an installed-but-blocked bwrap is treated as absent, not used. 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> before the prompt to codewhale exec. By default, --auto enables Full Access: tools run without asking, shell commands have no Codewhale sandbox, and trust mode lets file tools write outside the workspace. Any --sandbox other than danger-full-access (or the equivalent sandbox_mode in config) keeps trust mode off. Use --sandbox workspace-write for the shell sandbox, where available, and file-tool workspace restrictions; external-sandbox relies on your own isolation.

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