ducoterra
209f167e43
The explainer for questions about a flag, a config key, a refusal, a mechanism or a security boundary. ai-sandbox generates its own Containerfile, entrypoint, squid config and netfilter rules from one script, so the text of the program is the documentation of the version the user will run: the skill sets a strict ground-truth order -- the installed script and --help, then the repo docs, then the tests as the executable spec -- and its own fact sheet last, overridden by all of them. scripts/locate.sh resolves that order on an arbitrary machine: the installed script and its version, the source tree behind it (via $AISB_REPO, the script's own parent, $PWD, the git root), the docs with their line counts, and the config/state/cache locations. references/source-map.md maps a question topic to the function, doc and test that hold the answer, plus the vocabulary (split_target, classify_allows, gate vs --no-gate vs --proxy, POL[]/P_*/OPT_*) and the FAQ. The skill names which safe surface answers what: the --dry-run, --print-entrypoint, --print-containerfile and --print-policy previews build nothing and reach no registry, while inspect, doctor --deep, build, update and gate up do change the machine and are not for an explanation. It records the two honest exceptions rather than overclaiming -- --print-policy ensures the home volume, and --no-gate hits DNS. Read-only by construction: no build, no container, no network call, and it reads pi_config_bridge() rather than a models.json holding a live key. Its worst failure mode is an invented flag, so the answer format requires the real spelling, the source it came from, what the thing does not do, and a plain "no" plus the closest real thing when the answer is no. LLM-Generated: true
10 KiB
10 KiB
name, description
| name | description |
|---|---|
| doc-sandbox | Answers questions about ai-sandbox and ai-sandbox-autophase — what a flag or config key does, why a run refused to start (exit 77/78), how the egress allowlist, the squid gate and the in-container nftables ruleset work together, how the ~/.agents share or the pi config bridge or the base-image digest pinning behaves, what the image contains, how to run a given harness or language, what the sandbox does and does not protect against, and how the phase driver splits sandbox work from host git. Use when the user asks what something in ai-sandbox means, is about to, or just did, run ai-sandbox and wants an explanation, hits a sandbox error, or asks about the tool's design, security model or limitations. Answers from the installed program's own text plus the repo docs and tests, never from memory; runs only side-effect-free preview commands and never a build, container, or network call. |
doc-sandbox
ai-sandbox is one bash script that generates its own Containerfile, container entrypoint, squid config and netfilter rules. That is what makes it answerable: the text of the program is the documentation of the installed version, and three of its flags print the artifacts it generates. Read those; do not recall.
Ground truth, in this order
- The installed program —
ai-sandbox --help, and its source:readlink -f "$(command -v ai-sandbox)". If they disagree, the installed program is what the user will run. - The repository, if present:
README.md(what and why),docs/networking.md(the measurements behind the enforcement model),docs/threat-model.md(what is not protected),docs/recipes.md(invocations per harness/ecosystem/pipeline),AGENTS.md(design rules). - The tests — the executable spec.
tests/unit/*needs no containers and states exact shapes;tests/e2e/*proves behaviour in a real container (e.g.11_net.shfor "can the agent lift the ruleset"). When behaviour is subtle, the test answers better than prose. - This skill's fact sheet — fast, but if it conflicts with the above, the above wins and this file is a bug to fix.
bash scripts/locate.sh # where each of those lives on this machine, and the version
Working a question
- Classify it: a flag/key, a failure, a mechanism ("how is egress enforced"), a
security boundary ("can it read my ssh keys"), or a pipeline question. Then read
references/source-map.md— it maps each to the function, doc and test that hold the answer. - Read that source. Grep, don't skim:
grep -n 'print-policy' bin/ai-sandbox. - Check the version you read (
ai-sandbox version) and say which one you read when it matters — behaviour that changed recently includes the working-directory mirroring, thesettings.jsonper-key merge, thexhighthinking policy and the base digest pinning. - If the question is about this machine's behaviour, prefer a preview command over an opinion (§safe commands) and quote its output.
- Answer in the format below. If the source does not contain it, say it does not exist and name the closest real thing — a plausible invented flag is the worst failure mode available here.
Answer format
- The answer, one or two sentences, in the user's terms.
- The command to run, copy-pasteable, with real flag spellings.
- Where it comes from:
bin/ai-sandbox(build_argv()), ordocs/networking.md, ortests/e2e/11_net.sh. So they can check you. - What it does not do, whenever the question touched security — e.g. "the allowlist limits where, not what: an allowlisted remote plus a token can ship your code."
- A pointer to
docs/threat-model.mdwhen the honest answer is "this is out of scope" (kernel escapes, anything allowlisted, anything you mounted).
Safe to run while answering
ai-sandbox --help ai-sandbox version
ai-sandbox --dry-run the effective invocation, env values redacted
ai-sandbox --print-entrypoint the enforcement script baked into the image
ai-sandbox --print-containerfile the generated Containerfile
ai-sandbox --print-policy effective policy as key=value -- with one caveat, below
These build nothing, start no container, write no session state and reach no registry — that is a
deliberate property of the tool (preview modes are what make it scriptable), so use them freely.
They read config files, so they show the effective policy where you are. Two honest exceptions:
--print-policy also ensures the home-cache volume exists, so it fails without podman (a deviation
from the repo's own "preview must not write state" rule, worth reporting rather than repeating);
and with --no-gate, resolving domain entries does hit DNS.
Not for an explanation, unless the user asked about the machine and agrees:
inspect— prints the same policy but resolves the base digest now, so it may contact the registry.doctor [--deep]— host checks;--deepruns a real container and probes egress.build,update,gate up,clean, and any real run — these change the machine.cating~/.pi/agent/models.jsonto answer a question about the bridge: read the code (pi_config_bridge()), not the file with a live key in it. Never echo a credential, anauth.json, or anything from a--env-file.
Facts you may state without reading (still: state the version)
| topic | fact |
|---|---|
| precedence | built-in default < ~/.config/ai-sandbox/{config,allow} < ./.ai-sandbox/{config,allow} < AISB_* < CLI. allow/env/mount/install/label accumulate; other keys replace |
| arg parsing | stops at the first positional or unknown flag; the rest goes to the harness. -- replaces the command. --strict-args makes an unknown flag an error |
| default net | allow, and an empty allowlist in allow mode is a hard error, never a silent free-for-all |
| enforcement | two stacked controls: an in-container inet aisb nft table with policy drop on output, installed by the entrypoint as root before it setprivs to uid 1000 with no capabilities, plus a squid gate on the host loopback that filters by domain at CONNECT |
| refusals | exit 77 ruleset could not be installed; 78 policy file missing in the container. Both are the sandbox working; --allow-unenforced is the named escape hatch |
| gate ports | squid relays only 80, 443, 8443; --allow domain:8080 is not what it looks like. IP/CIDR entries are direct netfilter rules instead (default ports 80,443) |
| host services | 100.64.0.1 (config: gate_addr) inside the container is the host's loopback; only the gate's port is reachable through it unless you --allow 100.64.0.1:<port> |
| inbound | there is no publish flag, and in --net allow the generated ruleset's input chain is policy drop too, so a -p pushed through extra_args is dropped inside. That last half is a reading of gen_rules(), not a measurement — probe it (right-sandbox's references/port-and-loopback.md) before promising a preview URL |
| filesystem | cwd mounted rw at its host path (falls back to /project with a message when the host path would bury /tmp, /usr, /etc, /var, /opt, /run, the container home, or /); nothing else is mounted except the .agents share and the read-only policy mount at /run/aisb |
| the container user | uid/gid 1000, the image's own sandbox account, $HOME = its home (--userns=keep-id, so files the agent writes are owned by you on the host). Skills land at ~/.agents on both sides and they are different directories |
| skills | host ~/.agents → the container's ~/.agents (agents_dest) read-only, no flag makes it writable; --no-agents to withhold it, --agents-dir for another directory. Its contents are readable by whatever runs in there |
| env | nothing inherited but TERM LANG LC_ALL LC_CTYPE TZ (plus HOME, AISB, AISB_SESSION); values travel in a 0600 file, never argv; --env NAME where NAME is unset fails the run |
| pi bridge | host ~/.pi/agent/{models,settings}.json rewritten, not copied: apiKey → "$AI_API_TOKEN", !command values dropped, auth.json never touched; settings.json merged per key; defaultThinkingLevel is policy (xhigh) re-applied every run unless --thinking host |
| image | one base (ubuntu:24.04) pinned to a registry digest that is part of the image tag; Node pinned + sha256-verified; pi version-pinned; --install PKG → a different tag; a build with no digest is labelled UNPINNED and doctor warns |
| limits | cpus 4, memory 4g, pids 512, tmpfs 1g; the container home is a named volume (aisb-home) that outlives the image, --ephemeral-home swaps it for a tmpfs |
| state | logs/config/cache under ~/.local/state/ai-sandbox, ~/.config/ai-sandbox, ~/.cache/ai-sandbox; ~/.local/state/ai-sandbox/log records every run without secret values |
| autophase | the agent and .agents/validate.sh run in the sandbox; the commits and every push happen on the host, and the git remote is deliberately unreachable from inside. Host git runs with an empty hooks path and refuses to deliver if a sandboxed unit changed .git/config or .git/hooks/ |
When the answer is "no"
Say it plainly, then give the closest real thing:
- "publish a port" → no; run the server on the host (the mount is your disk), or one named
--net fullpreview run withAISB_EXTRA_ARGS=-p …and an explicit warning that that run has no egress policy. - "make the sandbox able to write my skills" → no, by design: a skill is an instruction you follow later on the host. Author it in the project and move it yourself.
- "let the pipeline push from inside the sandbox" → no: an agent that can push can ship what you are
about to review.
ai-sandbox-autophasedelivers on the host. - "inherit my environment, it's annoying" → no; that ambient environment is exactly the exfil target.
Name what you need with
--env. - "silently fall back to no network policy when the ruleset fails" → no: exit 77.
If the user wants the missing thing, that is a change to bin/ai-sandbox — say which function
would carry it (gen_rules(), build_argv(), parse_args()), that it needs an entry in
tests/e2e/, and that per the repo's own rules it must fail closed and print no values.
References
references/source-map.md— question topic → function / doc / test, plus the FAQ and the vocabulary (split_target,classify_allows, gate vs--no-gatevs--proxy,POL[]/P_*/OPT_*).scripts/locate.sh— find the installed script, the version, the repo docs, the state dirs.