agent-sandbox/AGENTS.md

Agent guidelines for agent-sandbox

Build and test

• cargo fmt and cargo clippy must pass before every commit.
• cargo test runs all integration tests. Tests run serially (configured in .cargo/config.toml) because they spawn real bwrap sandboxes that share host paths like /tmp.
• 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.