# 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.