ducoterra
144e322391
Everything else in the file gates egress, which left an everyday request unanswered: the agent starts a dev server inside the sandbox and a human wants to look at it. This puts a listener on the host that forwards into the container, so a browser, curl or an API tester reaches the server the sandboxed process runs. `--publish [ADDR:]HOST:CONTAINER`, config `publish` and AISB_PUBLISH, repeatable, with the cost named in the flag: it is ingress, so whatever that server serves is reachable from the address it binds. The default address is 127.0.0.1 because a bare podman -p binds every interface (measured) -- a port committed in a repo config must not quietly be a port on the LAN. publish_addr changes the default machine-wide; a spec with a non-loopback address warns on every run. The grammar is smaller than podman's on purpose: one port per entry, no ranges, no /udp, no `*` -- this list is reviewed line by line, and typing 0.0.0.0 is the whole warning. An address means three parts, so `127.0.0.1:8000` is refused rather than guessed. No -p alias: that flag belongs to the harness (claude -p prints). Fail closed, as elsewhere: --net none cannot forward a port and podman discards the mapping while starting the container anyway, so "it ran" would mean "nothing is listening"; a host port already in use is named before the container starts, not after a build; pick_port() will not hand the gate a port this run publishes. The container is labelled with the ports it was given, and doctor reports them. Inside, publish_rules() accepts tcp on the published ports in the input chain and never the output one. Measured (docs/networking.md): pasta delivers the connection over loopback, so that rule counts 0 packets on the reference host; it is there for a host or a bridge network that delivers on the interface, and so that `nft list table inet aisb` answers "what can reach this container". The ports are validated again inside the entrypoint, because a ruleset is not somewhere to splice an unvalidated string. And the measurement that makes a configured preview look broken: a server bound to 127.0.0.1 inside answers inside and refuses the published port outside, so dev servers must bind 0.0.0.0 -- both skills say so in the change that writes the port. Tests. Unit: the grammar and every port list that looks right and is not, config/env/flag precedence and dedup, the canonical spec in --print-policy, the `# ingress:` header, the flags reaching the invocation before the image, egress enforcement byte-identical with a port open, which chain the rule lands in and that a non-numeric port never reaches nft as code. e2e (tests/e2e/13_publish.sh): one real container with enforce=nft where the host gets its 200 and the same run still refuses a domain outside the allowlist at 403, the server runs as uid 1000 with no capabilities so it cannot widen its own port, and the host listener is gone when the container exits. LLM-Generated: true
130 lines
11 KiB
Markdown
130 lines
11 KiB
Markdown
---
|
|
name: doc-sandbox
|
|
description: 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
|
|
|
|
1. **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.
|
|
2. **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).
|
|
3. **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.sh` for "can the agent lift the
|
|
ruleset"). When behaviour is subtle, the test answers better than prose.
|
|
4. **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
|
|
bash scripts/locate.sh # where each of those lives on this machine, and the version
|
|
```
|
|
|
|
## Working a question
|
|
|
|
1. 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.
|
|
2. Read that source. Grep, don't skim: `grep -n 'print-policy' bin/ai-sandbox`.
|
|
3. 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, the `settings.json`
|
|
per-key merge, the `xhigh` thinking policy and the base digest pinning.
|
|
4. If the question is about *this machine's* behaviour, prefer a preview command over an opinion
|
|
(§safe commands) and quote its output.
|
|
5. 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()`), or `docs/networking.md`, or
|
|
`tests/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.md` when 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; `--deep` runs a real container and probes egress.
|
|
* `build`, `update`, `gate up`, `clean`, and any real run — these change the machine.
|
|
* `cat`ing `~/.pi/agent/models.json` to 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, an
|
|
`auth.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/publish` 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 `setpriv`s 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 | `--publish [ADDR:]HOST:CONTAINER` (config `publish`, `AISB_PUBLISH`): forwards a host port into the container. Bound to **127.0.0.1** unless the spec names an address (podman's bare `-p` binds every interface, measured), one port per entry, an address needs three parts, `--net none` refuses instead of starting with nothing listening, a busy host port is named before the build. The server must listen on `0.0.0.0` **inside**: a loopback-only server answers inside and refuses the published port (measured). Ingress only — egress enforcement is untouched in the same run |
|
|
| 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 on my network so my phone can see it" → not as a committed setting.
|
|
`--publish 0.0.0.0:18080:8000` exists and warns on every run, because that is the sandbox becoming
|
|
a server on the LAN; `publish = 8000` (loopback) is the setting a repo file should carry. The old
|
|
answer — `AISB_EXTRA_ARGS=-p …` with `--net full` — buys nothing that `--publish` does not, and it
|
|
costs the 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-autophase` delivers 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-gate` vs `--proxy`, `POL[]`/`P_*`/`OPT_*`).
|
|
* `scripts/locate.sh` — find the installed script, the version, the repo docs, the state dirs.
|