agent-sandbox/AGENTS.md

Agent guidelines for agent-sandbox

Deployed config

config-example.toml in the repo root is the canonical config file. It is symlinked into $XDG_CONFIG_HOME/agent-sandbox/config.toml on the host. When editing it, remember that changes take effect immediately for all sandbox invocations.

The config file may set extra-config = "<absolute path>" to layer a second file on top using the same merge rules (scalars replace, vecs append, profiles merge by name). A missing extra file is silently skipped; nesting is not supported (the extra file cannot itself set extra-config).

Build and test

• cargo fmt and cargo clippy must pass before every commit.
• cargo test runs all test cases.
• Never add Co-Authored-By lines to commits.

Things that will bite you

bwrap argument ordering matters

Later bwrap arguments override earlier ones for the same path. This has caused multiple bugs:

• Blacklist overlays (tmpfs, ro-bind /dev/null) must come after the base --ro-bind / / and --bind /tmp /tmp.
• The /run tmpfs and its selective whitelisted binds must come after the overlay section, or the overlays clobber the whitelisted paths.
• User --rw/--ro escape hatches must come after mode setup so they can override sandbox restrictions.

Take extreme care when reordering any arguments in sandbox.rs or refactor things and test thoroughly.

Env values must never become bwrap arguments

/proc/<pid>/cmdline is world-readable, and the same string is exposed inside every sandbox at /run/agent-sandbox/bwrap-args. --setenv KEY VALUE therefore publishes every secret the user puts in env = [...]. set_sandbox_env in sandbox.rs sets the whole child environment on the bwrap process instead, and bwrap passes its own environment on. Do not "simplify" it back to --setenv; tests/e2e/env.rs guards this.