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
239 lines
7.7 KiB
Markdown
239 lines
7.7 KiB
Markdown
# Recipes
|
|
|
|
Concrete invocations. `pi` below is whatever you aliased to `ai-sandbox`.
|
|
|
|
## A first session
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pi --allow aipi.reeseapps.com
|
|
```
|
|
|
|
Same thing, but remembered by the repo (so teammates review the policy, not just
|
|
your shell history):
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```ini
|
|
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.
|