Files

T

mrtoth 6933deb441 Document config-example.toml as the canonical deployed config

Makes it clear that the example config is meant to be symlinked into
$XDG_CONFIG_HOME/agent-sandbox/ so it stays in sync with the repo.

2026-04-22 22:43:46 +02:00

1.2 KiB

Raw Blame History

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.

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.