Agent guidelines for agent-sandbox

Deployed config

The live config on the host is deployed by hephaestus from ansible/roles/agents/templates/agent-sandbox/config.toml.j2; edit it there. config-example.toml in the repo root is only an example for other users.

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

Supported distros

Ubuntu 24.04 LTS and Debian 13 (trixie) are the oldest distros we support. Before you rely on a feature of bwrap, the kernel or glibc, check that both of them ship a version that has it.

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.

2.0 KiB Raw Blame History