ducoterra
a08a69f143
Two changes, one bug found through the other.
Thinking is policy now: defaultThinkingLevel is xhigh unless you say otherwise
(thinking / --thinking / AISB_THINKING, with pi's levels plus 'host' to decline
and 'off' meaning pi's own no-reasoning level). It is written into the bridged
settings and re-applied by the entrypoint on every run, so a run cannot set its
own reasoning down for the runs after it. Unknown levels are refused with the
list to pick from. Nothing is written for codex, claude or a command after --,
and --no-pi-config declines it along with the bridge, because pi's own defaults
are what that flag asks for.
The reason xhigh had never reached a sandbox is worse than a missing default:
settings.json was managed as one whole file, and pi rewrites its own settings
(a theme change, "seen the changelog"), so the first such write matched nothing
and froze every host preference out permanently -- provider, model, thinking
budgets and level included, a real session left holding just
{"lastChangelogVersion": "1.4.0"}. It is merged per key instead, against a copy
of what we last wrote: a key edited in the sandbox stays edited, a key never
touched follows the host again, an untouched key the host dropped is dropped, a
key pi invented survives, and a file with no base copy takes the host values --
which repairs the volumes already frozen. Unparseable JSON is re-seeded with a
warning since pi cannot use it either; a file the container cannot read is
reported with the fix, because nothing inside the sandbox can repair one.
One trap worth remembering: the seeding script is passed to bash -c in single
quotes, so a single quote inside it closes the argument early and the rest runs
in the outer shell -- valid bash, wrong program, clean bash -n and clean
shellcheck. tests/unit/06_entrypoint.sh extracts the seeding script and asserts
it is quote-free, and extracts the merge program to test its semantics without
a container; tests/e2e/12_sandbox.sh does the same in a real run, including
forcing the level back after the sandbox sets it to off.
LLM-Generated: true
7.7 KiB
Recipes
Concrete invocations. pi below is whatever you aliased to ai-sandbox.
A first session
cd ~/Projects/myapp
ai-sandbox doctor # is this machine ready?
pi --allow aipi.reeseapps.com --env AI_API_TOKEN
With your pi config bridged, the token is found on its own, so the allowlist is the only thing you have to say:
pi --allow aipi.reeseapps.com
Same thing, but remembered by the repo (so teammates review the policy, not just your shell history):
mkdir -p .ai-sandbox
printf 'aipi.reeseapps.com\n' > .ai-sandbox/allow
pi
Pi's own configuration
The bridge rewrites your host ~/.pi/agent/{models,settings}.json instead of copying
it: providers, models, thinking budgets and preferences come along, the credential
becomes "$AI_API_TOKEN", and anything that only works on the host (a !command
header, a path into ~) is dropped with a warning. auth.json is never bridged.
# the everyday case: same provider as the host, token from the environment
pi --allow aipi.reeseapps.com
# a model your gateway serves, chosen per run
pi --allow aipi.reeseapps.com --model juggernaut
# keep the model's endpoint pinned by IP as well, on a LAN inference host
pi --allow aipi.reeseapps.com --allow 10.20.0.7:11434
# a different variable name for the credential
pi --allow aipi.reeseapps.com --pi-token-env GW_TOKEN
# do not hand the token over automatically: the run then fails closed unless you
# pass it yourself, which is what you want in shared scripts
pi --allow aipi.reeseapps.com --env AI_API_TOKEN --no-pi-token-env
# no bridge: pi starts with its own defaults inside the volume (and no thinking policy)
pi --no-pi-config --allow aipi.reeseapps.com
models.json is kept in step with the host unless you edit it in the sandbox, where your
edit then wins; deleting it inside the sandbox re-seeds it. settings.json is merged per
key, so a preference you changed in the sandbox stays changed and every one you did not
touch follows the host again.
How hard it thinks
defaultThinkingLevel is policy, not preference: xhigh unless you say otherwise, and
re-applied every run rather than remembered from whatever the last sandbox set.
# the everyday case: xhigh
pi --allow aipi.reeseapps.com
# one-off: the top of pi's range, or no reasoning at all for a mechanical job
pi --thinking max --allow aipi.reeseapps.com
pi --thinking off --net allow --allow registry.npmjs.org -- npm ci
# let settings.json decide, the way it did before this was policy
pi --thinking host --allow aipi.reeseapps.com
# per repo, chosen by .ai-sandbox/config
# thinking = high
Nothing is written for codex, claude or a command after --: those read their own
configuration and ai-sandbox does not touch it.
Your skills and standing instructions
~/.agents is shared read-only at /home/sandbox/.agents by default, so the sandboxed
harness finds the same skills, prompt templates and AGENTS.md you use on the host.
A project's own .agents/ needs nothing: it arrives with the project mount, and harnesses
that read both see the project's alongside yours.
# the everyday case: your skills are simply there
pi --allow aipi.reeseapps.com
# a run where the harness should not have them: reviewing untrusted code, or a
# skills set that mentions internal hosts you would rather it not repeat back
pi --net none --no-agents -- bash -lc 'make lint'
# a curated set for sandboxes -- e.g. host skills stay yours, this dir is what you share
pi --agents-dir ~/.config/ai-sandbox/agents --allow aipi.reeseapps.com
# two sets, per trust level, chosen by config file in a repo
# .ai-sandbox/config: agents_dir = ./.agents-shared
It is read-only and there is no flag to change that: a skill is an instruction you
follow on the host later, so letting a sandbox write one would let it persist past the
run. If a workflow really needs to author skills, do it in the project directory and
move the result into ~/.agents yourself, where you can read it first.
Per harness
# pi (baked into the image, config bridged)
pi --allow aipi.reeseapps.com
# pi with a model chosen on the command line
pi --harness 'pi --model turbo' --allow aipi.reeseapps.com
# a gateway that speaks a different protocol still needs only its host
pi --allow gateway.internal:8443 --env AI_API_TOKEN
# OpenAI Codex CLI / Claude Code: they read their own config files, so mount or
# generate what they need and allow their endpoints; the pi bridge does not apply
pi --allow chatgpt.com --env CODEX_API_KEY
pi --allow api.anthropic.com --env ANTHROPIC_API_KEY
# just a shell in the sandbox
pi --shell
# any other build/test command, no network needed
pi --net none -- make test
Per ecosystem
Only the endpoints the tool actually needs. Everything else stays blocked, so a typosquatted package from an unexpected host fails loudly instead of quietly working.
# npm / node
pi --allow registry.npmjs.org --allow nodejs.org --allow github.com
# python: pypi needs both of these (the CDN that serves the files is separate)
pi --allow pypi.org --allow files.pythonhosted.org
# rust
pi --allow crates.io --allow static.crates.io --allow index.crates.io
# go
pi --allow proxy.golang.org --allow sum.golang.org
# docker/podman images from within a build
pi --allow registry-1.docker.io --allow auth.docker.io --allow production.cloudflare.docker.com
# a project that also needs its dev database (non-HTTP: pinned IP + port)
pi --allow aipi.reeseapps.com --allow 10.20.0.5:5432
Git
# fetch/push over https with a token in the environment
pi --allow github.com --env GH_TOKEN -- git push origin main
# ssh: the key has to be mounted deliberately (an explicit, reviewable grant)
pi --allow github.com --mount ~/.ssh:ro -- git push origin main
# read-only view of a sibling repo for context
pi --allow aipi.reeseapps.com --mount ../docs:/docs:ro
Tightening a run
# nothing persistent, nothing readable, nothing writable outside the repo
pi --net none --ephemeral-home --read-only -- make build
# an entirely blank sandbox for untrusted code: no project, no home, no skills
pi --net none --no-cwd --ephemeral-home --read-only --no-agents -- bash
# CI-ish: refuse to start if the policy or environment is not exactly right
pi --strict-args --net allow --allow-file .ai-sandbox/allow --env-file .ci/env -- npm ci
Long-lived gate shared by several sandboxes
ai-sandbox gate up --allow aipi.reeseapps.com --allow registry.npmjs.org
# name=aisb-gate
# port=18081
# proxy_env=export HTTPS_PROXY=http://100.64.0.1:18081
ai-sandbox --proxy 100.64.0.1:18081 --allow aipi.reeseapps.com --shell
ai-sandbox gate logs # what did it allow/deny?
ai-sandbox gate down
Debugging
ai-sandbox --dry-run --allow example.com --env KEY # the exact podman invocation
ai-sandbox --print-policy # effective policy, no secrets
ai-sandbox --print-entrypoint | less # the enforcement script
ai-sandbox --keep --net none -- false # leave the container for forensics
ai-sandbox ps
AISB_GATE_KEEP=1 pi --allow example.com --shell # keep the gate after exit
ai-sandbox clean --all
# "the ruleset would not install" (exit 77): check the host
podman info | grep -i rootless
grep "$(id -un)" /etc/subuid
Making it the default for a project
.ai-sandbox/config:
net = allow
harness = pi
cpus = 8
memory = 8g
mount = ../specs:/specs:ro
env = AI_API_TOKEN
.ai-sandbox/allow:
aipi.reeseapps.com
registry.npmjs.org
Then pi alone in that directory is the whole invocation — and because both files
are in the repository, the sandbox policy gets reviewed with the code.