mrtoth
6933deb441
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.
24 lines
1.2 KiB
Markdown
24 lines
1.2 KiB
Markdown
# 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.
|