[sandbox.os]

Sub-pages

Sub-section	Page
[sandbox.os.command_tools]	sandbox.os.command_tools — Curated per-tool config bundles (git, gh, cargo, bun, node, …).

command_fs

Typeenum (string)Default”system”

How much of the host filesystem is visible inside the command_run sandbox before manifest-declared fs_read / fs_write / additional_directories entries layer on top.

Four modes, least-permissive first:

• None — nothing bound by default. Only paths the manifest explicitly names are visible. The strictest posture; tools that depend on /usr/bin etc. will fail to start unless those paths are added explicitly.
• System (default) — system paths bound read-only: /usr, /bin, /sbin, /lib, /lib64, /etc, /nix if present. $HOME is not bound; the manifest names what’s needed (~/.cargo/registry, etc.). Carve-outs for /etc/ssh/, /etc/shadow, etc. are masked when command_mask_secrets = true.
• Permissive — System baseline plus $HOME bound read-only. Carve-outs extend to ~/.ssh/, ~/.aws/, etc. when command_mask_secrets = true. The “I want config files but not secrets” posture.
• All — --ro-bind / / at the bwrap level: the entire host filesystem is visible read-only. Even in this mode, command_mask_secrets = true (the default) masks the standard sensitive-file paths. Opt-in for tools that need broad host visibility.

Value	Meaning
"none"	Nothing bound by default.
"system"	System paths only; $HOME not bound. Default.
"permissive"	System paths + $HOME read-only.
"all"	Entire filesystem read-only.

command_mask_secrets

TypebooleanDefaulttrue

Apply the standard sensitive-file masklist (see SYSTEM_DENY_PATHS + HOME_DENY_PATHS constants) on top of whichever baseline is selected. Default true; the masks always apply unless explicitly disabled.

network

Typeobject

Sub-section of [sandbox.os] that authorizes (a) which ports the agent may expose from inside the sandbox to the host’s loopback via command_run’s dev_server_ports parameter (inbound), and (b) which host loopback ports the agent may reach via host_localhost_ports (outbound). Bare-u16 entries silently allow; { port = N, prompt = true } forces a runtime prompt. Each side’s deny list takes precedence over its allow list.

dev_server_ports

Typearray<integer | object>

Array items

Bare-u16 or table entry for one allow-list port. Shared by dev_server_ports and host_localhost_ports since both use the same TOML shape; the resolved-config types are distinct so the direction is type-checked at use sites.

Variant 1

Typeinteger

Shorthand: 3000.

Table form

Typeobject

Explicit: { port = 3000, prompt = true }.

port

Typeintegerrequired

prompt

TypebooleanDefaultfalse

dev_server_ports_deny

Typearray<integer>Default[]

host_localhost_ports

Typearray<integer | object>

Array items

Bare-u16 or table entry for one allow-list port. Shared by dev_server_ports and host_localhost_ports since both use the same TOML shape; the resolved-config types are distinct so the direction is type-checked at use sites.

Variant 1

Typeinteger

Shorthand: 3000.

Table form

Typeobject

Explicit: { port = 3000, prompt = true }.

port

Typeintegerrequired

prompt

TypebooleanDefaultfalse

host_localhost_ports_deny

Typearray<integer>Default[]

wrappers

Typearray<string>

Section-wide list of wrapper-command prefixes that every enabled bundle in command_tools also applies to. Useful when a build orchestrator (just, make, mise, etc.) spawns the real tool as a child inside the same bwrap namespace — without this, the child inherits the parent’s NetworkParams::None because the orchestrator’s matched_pattern doesn’t match any bundle’s command_prefixes. The section default unions with each entry’s wrappers = [...] override; both add to (never replace) the bundle’s command_prefixes. Empty (the default) preserves the original bundle-applies-by- command-prefix behaviour.