ai-sandbox/docs/recipes.md

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

Ports: two directions, two answers

Outbound — a service on your machine (dev postgres, redis, a mock API, a local model server). That is egress, so it is an allow entry, not a flag. 100.64.0.1 is the address that stands for the host's loopback inside the container:

# .ai-sandbox/allow
100.64.0.1:5432            # postgres from `docker compose up db`, on the host

# .ai-sandbox/config -- point the app at the mapped address (no secret is a URL like this)
env = DATABASE_URL=postgresql://dev@100.64.0.1:5432/app_dev
# HTTP on anything but 80/443/8443 also has to skip the proxy, or the gate is asked for it:
env = NO_PROXY=100.64.0.1,localhost,127.0.0.1,::1
env = no_proxy=100.64.0.1,localhost,127.0.0.1,::1

Inbound — a server the sandbox runs, to be seen from the host. Publish it. Bound to loopback by default, so http://127.0.0.1:8000 in your browser works and nothing on your network can reach it:

# the one-off preview: the agent runs the server, you look at it
ai-sandbox --allow aipi.reeseapps.com --publish 8000 -- npm run dev -- --host 0.0.0.0

# a host port that is free, a different container port
ai-sandbox --publish 18080:3000 -- npm run dev -- --host 0.0.0.0

# from a project's own config, so `ai-sandbox` alone is the invocation
#   .ai-sandbox/config:  publish = 8000
#                        publish = 18080:3000

Four things worth knowing before it looks broken (all measured, all in networking.md):

• the server must listen on 0.0.0.0 inside — --host 0.0.0.0, uvicorn --host 0.0.0.0, runserver 0.0.0.0:8000. A 127.0.0.1-only server answers inside and refuses the published port.
• egress is unaffected. A published port is ingress: the run keeps its allowlist, its unprivileged uid and its ruleset, and the ruleset names the ports it opened.
• --net none refuses to publish rather than start with nothing listening; a host port that is already taken is named before the container starts, not after the build.
• a non-loopback bind (publish = 0.0.0.0:18080:3000) means exactly what it says: anything that can route to this machine can reach that server. It warns, and it does not belong in a committed config — that file outlives the run that justified it.

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.

An unattended pipeline: phases in the sandbox, pushes on the host

The nightly case: .agents/phases/todo/ full of task files, nobody watching, an agent that must not be able to reach the git remote or touch the host.

# ~/.bashrc.d/ai-sandbox.bash -- the launcher, the way you already write it, plus the
# "$@" that lets a run hand it the command to sandbox
sandbox-pi () {
    export AI_API_TOKEN=$(pass aipi/dev-token)
    ai-sandbox --allow aipi.reeseapps.com --allow github.com \
               --allow pi.dev --allow release-assets.githubusercontent.com \
               --env AI_API_TOKEN "$@"
}

A function written for typing by hand usually stops at --env AI_API_TOKEN, and that is the one thing the driver cannot work with silently: everything after the function name is the run, so dropping it starts the image's default harness with no prompt. With a terminal behind it that is an interactive agent waiting for input, its output going into a pipe the driver is reading — a run that appears to do nothing at all. --status names a launcher that takes no arguments and the preflight refuses it; the fix is the "$@" above.

cd ~/Projects/foo
ai-sandbox-autophase --status     # what it resolved, what is pending, the git plan
ai-sandbox-autophase --dry-run    # the exact child and gate commands, nothing run
ai-sandbox-autophase              # every pending task, in pipeline order

What it does with that function is the interesting part. A script cannot see an interactive shell's functions, so it reads the rc files, takes the definition, and starts each child as:

sandbox-pi --no-tty --no-interactive -- pi --no-approve --session-dir .agents/phase-sessions --name <unit> --mode json <prompt>

pass runs again per unit, so a run that starts at 23:00 is not holding a token fetched at 09:00. Reading the definition is all the probe does: --status and --dry-run never call the launcher, fetch a token, build an image or start a container. It reads it in a session of its own with no stdin — an interactive bash started from a terminal tries to take that terminal, gets stopped for trying, and a stopped process does not take the timeout meant for it. Every child is started with its stdin on /dev/null for the same reason in the other direction: nothing inside the sandbox can be waiting for your keyboard.

you want	flag
a different launcher	--pi-cmd sandbox-claude, --pi-cmd pi, or a whole command line
the function somewhere else	--rc-files ~/.bashrc.d/zz-ai.bash
fewer flags of its own	--sandbox-args '' (the defaults are --no-tty --no-interactive)
the gate on the host, because the toolchain lives there	--validate-in host (warns: the gate file is in the writable mount)
one task, one phase, a short run	--unit 03_api/02_routes.md, --phase 03_api, --max-units 4
commits that stay local while you watch	--no-push
no warm-up container (it costs a build the first time)	--no-preflight

Where the work goes when it finishes: the executor agents never commit; the driver commits each completed phase on the host and pushes it, checks again before starting the next phase, and pushes whatever is left at the end of the run. A failed push stops the run and prints the command that finishes it — the commit is never lost, and the next run's push sweeps it up:

[2026-10-28 02:14:07] pushing 1 unpushed commit(s) on main (between 03_api and 04_docs)
  (pushed: 9f1c2ab phase: 03_api)

Inside the sandbox the agent has the repository but not the remote, and it is told so in its own prompt (--no-notes to drop that block) — git status, git diff, git log work; git push, fetch, pull and clone <url> are not attempted, so no fixer round is spent rediscovering that. That is also why the gate runs in the sandbox: .agents/validate.sh is inside the writable mount, and a jailer the prisoner can edit is not a jailer.

One consequence of committing out here is worth naming: a repository is not only what git records, it is what git runs — .git/config, and .git/hooks/ especially. So the driver's git calls run with an empty hooks path, no pager, no system config and no ext:: transport, and the run refuses to deliver if a sandboxed unit changed either:

✗ ERROR: refusing to deliver (commit/push) -- the sandbox changed this repository's own git configuration.
    look at it by hand:  git config --local --list;  ls -l .git/hooks
    if the change was yours:  re-run with --trust-git-changes

The commits and the work stay exactly where they are; nothing is pushed and no hook runs either way.

A project whose tests need something the image lacks gets it from the launcher:

sandbox-pi () {
    export AI_API_TOKEN=$(pass aipi/dev-token)
    ai-sandbox --allow aipi.reeseapps.com --allow pypi.org --allow files.pythonhosted.org \
               --install python3-pip --install ripgrep --env AI_API_TOKEN "$@"
}

A new --install set is a new image tag, so the first run after changing it builds: that one run says which packages are going in and reports every step until the image exists (AISB_BUILD_OUTPUT=quiet if you would rather it did not talk). Every later run starts without a word about the image, because there is nothing left to do.

doctor, inspect, clean and the rest of ai-sandbox work unchanged underneath it — --status prints the policy the launcher will apply, without applying it.