Files

T

ducoterra b273bfef09 name the sandbox's working directory, and drive phases through it

Two features, one shared reason: what the sandbox calls things decides
what a run tells you afterwards.

The cwd is now mounted at the path it has on the host and that is the
working directory, so pwd, an error the agent quotes, a commit message and
the window title a harness derives from the cwd all name this project
instead of reading the same as every sandbox in the session. The mount is
unchanged: same directory, same rw, same :z, still the only writable one.

Only the destination changed, and a destination is where a bind mount can
do damage -- it hides whatever the image already had there. So
mirror_block_of() refuses the paths the image or the sandbox owns (/usr,
/etc, /var, /opt, /bin, /sbin, /lib*, /boot, /proc, /sys, /dev, /root,
/run, /tmp, /home, /home/sandbox*) and / itself, while /home/<user>/...
mirrors: the one standard hierarchy where work lives, and the one whose
per-user tree never meets the container's /home/sandbox volume or the
read-only .agents share inside it.

/tmp is what set the shape, and it was measured rather than assumed: with
--tmpfs /tmp and -v /tmp/x:/tmp/x in one run podman puts the tmpfs on top,
so pwd prints the right path, writes succeed, and the project is not there.
A failure that quiet earns a refusal plus a line of output instead:
workdir_note in --print-policy, a comment in --dry-run, one log line on a
real run. --workdir DIR still chooses the mount point; onto a refused path
it is honoured (it was asked for) and warned about. /project, the one
directory baked into the image, is every fallback, so a workdir always
exists -- --no-cwd included.

ai-sandbox-autophase runs a .agents/phases/ pipeline with the split the
sandbox forces: every executor agent and the .agents/validate.sh gate
inside, the commits and the pushes outside. The gate is in the writable
mount, so running it on the host is running agent-editable bash on the
host; the git remote is deliberately unreachable in there, because an agent
that can push can ship what you are about to review. It runs your launcher,
not a copy of it -- the definition is read out of your rc files and never
called, which is what lets --status and --dry-run promise no token fetch,
no build, no container. Host git runs with an empty hooks path and no ext::
transport, and delivery is refused if a sandboxed unit rewrote .git/config
or planted a hook. Needs --no-interactive to go with --no-tty: an
unattended run must not leave stdin open on your keyboard, and the two are
now separate choices on both sides.

Tests and tooling, most of it forced by what the two changes exposed:
mirror_block_of is extracted from the script and asked about /usr and
/home/sandbox, which a test cannot create (the 06_entrypoint.sh pattern),
and both real branches are driven from a scratch dir under $HOME, since
$TMPDIR is always the fallback -- which is why the whole suite had only
ever seen /project. e2e/12 holds a real container to the same promise,
including that /project, /home/sandbox and a home-volume marker survive a
mirrored run. The "nothing was started" checks now compare the set of
container ids before and after instead of counting every sandbox on the
machine, so a session you have open is not a test failure; the pty cases
fall back to python3 where util-linux's script is not installed.
shellcheck covers both programs, the completion file and the fixtures, so
the completion builds are word-by-word now, and a colon in the project path
is refused with the reason instead of podman's "invalid option type".

558 unit assertions, 719 with e2e; lint and bash -n clean.

LLM-Generated: true

2026-10-28 10:06:31 -04:00

12 KiB

Raw Blame History

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.

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
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
}

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.

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 ripgrep' --env AI_API_TOKEN
}

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

12 KiB Raw Blame History