- Shell 48%
- Python 25%
- Nix 18%
- Docker 9%
agent-sandbox #
A self-contained Docker image for running AI coding agents — Claude Code, OpenCode, and Codex CLI — in a sandbox, preloaded with a full dev/ops toolchain (nix, rust, go, node, terraform, kubectl, abra, …). You point it at a project folder; it mounts that folder, runs the agent as a non-root user whose UID matches yours, and masks sensitive files from the agent.
All three harnesses live in one image. You pick which one runs by passing its command — nothing special, it's just the command the container execs:
python3 /path/to/agent.py claude # launch Claude Code in $PWD
python3 /path/to/agent.py opencode # launch OpenCode
python3 /path/to/agent.py codex # launch Codex CLI
python3 /path/to/agent.py bash # drop into a shell as the agent user
python3 /path/to/agent.py # defaults to Claude Code
Convenient alias:
alias agent='python3 /home/notplants/computer/projects/agent-sandbox/agent.py'
cd ~/some/project && agent opencode
Flags (consumed by the launcher, everything else is forwarded to the container as the command to run):
-p <name>— docker-compose project name (run multiple containers side by side)--debian— use the Debian-based image instead of the nix one--gpu— pass through the host GPU + display (see below)
What it is #
Two interchangeable image variants, same entrypoint and behaviour:
agent-sandbox(default) — built fromflake.nixvia Nix'sdockerTools. The toolchain comes from the host's nix store / binary cache, so nothing is recompiled inside Docker.agent-sandbox-debian— built fromDockerfile-debian, same tools on a Debian base.
Both images can themselves run nix (flakes enabled, build sandbox disabled,
a nix-daemon started at boot) and give the agent user passwordless sudo
— useful for debugging builds from inside the sandbox.
Harnesses #
Both images also include tg, the Tangled
CLI, pinned to v0.6.0 with the TG_VERSION Docker build argument. It is built
from the upstream Go module during the Docker build (including for the Nix
image); Go downloads the required toolchain automatically. Run tg --help
for commands or tg issue list / tg pr list inside a Tangled checkout.
Authentication is configured at runtime with tg auth login; credentials
are not baked into the images.
| Harness | Install (nix image) | Install (debian image) | Notes |
|---|---|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
official installer | self-updating native install bootstrapped into ~/.local on first boot |
| OpenCode | official installer | official installer | checksum-verified auto-update on each boot (scripts/auto-update.sh) |
| Codex CLI | npm install -g @openai/codex (Node 22+) |
npm install -g @openai/codex |
the unscoped codex npm package is unrelated — always use @openai/codex |
Each harness gets its own FHS-compat wrapper at ~/.local/<harness>-fhs/<harness>
that scopes the nix-store glibc LD_LIBRARY_PATH to that binary only (the
prebuilt ELFs aren't nix-built). With no command passed, the entrypoint defaults
to claude --dangerously-skip-permissions.
Codex sandbox note: Codex uses bubblewrap (
bwrap) for its Linux sandbox, which needs user namespaces — typically unavailable in an unprivileged container. If it complains about the sandbox, run it with Codex's sandbox-bypass flag (e.g.agent codex --dangerously-bypass-approvals-and-sandboxor setOPENAI_SANDBOX_MODE=noneper Codex's docs).
Self-extending environment #
The container can grow its own toolchain without a rebuild, and durably evolve its own definition:
-
On-demand tools.
nixpkgsis pinned (baked source + flake registry), so any package is one command away — offline and deterministic:nix shell nixpkgs#cowsay -c cowsay hi # run a tool ephemerally nix develop # dev shell for this repo nix-shell -p ripgrep --run rg # classic form also worksThe
nix-tempskill (installed into~/.claude/skills/) tells the agent to reach for these when a command is missing. -
A flake it can edit and keep. The authoritative
flake.nixlives in theagent_flakedocker volume at/srv/agent-flake, seeded from the image as a git repo on first boot. The agent edits it there; the history persists across runs.flake-syncmanages it:flake-sync status # diff the volume's flake repo flake-sync commit "add foo" # commit the edit (author: notplants) flake-sync export # copy it into /workspace to land in this repoTo actually bake an edit into a future image:
flake-sync exportinto a mounted copy of this repo, commit there, and run./build.shon the host.
How it works #
Build (build.sh):
- On Linux,
nix build .#dockerImageproduces a layered image tarball (./result). On macOS, the script performs the same Linux build in the officialnixos/nixDocker image, since Darwin cannot execute Linux Nix derivations directly. with the nix store DB seeded so the baked-in paths are registered. docker load < resultloads it asagent-sandbox-base:latest.docker build -t agent-sandbox .(Dockerfile) layers on the non-nix bits: the three harness CLIs, theabraandtgbinaries, a setuidsudo, the rust toolchain, and OpenCode config.- The complete
secrets/directory (including hidden files) is synced into the explicitly namedagent_secretsDocker volume. Every sandbox mounts that volume read-write at/secrets, without baking secrets into an image. - The latest
agent-orchestratorrepository is cloned into the explicitly namedagent_toolsDocker volume, mounted read-write in every sandbox at/tools/agent-orchestrator.
./build.sh --debian builds only agent-sandbox-debian; --all builds both.
Run (agent.py): wraps docker compose run --rm and
- mounts your current directory at
/workspace, persists/home/agentand the buildtarget/in named volumes, and mounts build-synced test secrets read-write at/secrets; - mounts the build-synced
agent-orchestratorcheckout read-write at/tools/agent-orchestrator; - passes
HOST_UID/HOST_GIDso files written in/workspaceare owned by you; - generates a compose override that masks sensitive files (
.env,secret.json, …) with/dev/nullandtmpfsover sensitive directories, so the agent cannot read them — seeSENSITIVE_NAMES/SENSITIVE_DIRSinagent.py.
Boot (entrypoint.sh, runs as root then drops to agent via gosu):
reconciles the agent user/UID with the host, grants passwordless sudo, starts
the nix-daemon, auto-updates OpenCode, builds the FHS wrappers for all three
harnesses, and locates the Claude Code native install — then launches the
command you passed (or Claude Code by default).
GPU passthrough #
agent.py --gpu layers compose.gpu.yaml, which passes through /dev/dri and
the Wayland/X11 display sockets so GUI OpenGL apps (e.g. ghostty) can run
against the host GPU from inside the sandbox. The container drives the GPU with
its own Mesa; the entrypoint wires /run/opengl-driver and joins the device
groups.
Security model #
The container is unprivileged: no --privileged, no added capabilities, no
Docker socket mounted, no host networking. In-container sudo/root only grants
root inside the sandbox — it adds nothing on the host. The only host surface
is the explicit bind mounts (your $PWD and the named volumes); since Docker
does not enable user-namespace remapping by default, container-root maps to
host-root on those mounts, which is why agent.py masks secrets before they're
exposed.
Layout #
| Path | Purpose |
|---|---|
flake.nix |
Nix build of the agent-sandbox-base image + tool list |
Dockerfile |
Layers claude/opencode/codex / abra / sudo onto the nix base |
Dockerfile-debian |
Debian variant of the full image |
entrypoint.sh |
User/UID setup, sudo, nix-daemon, FHS wrappers, launch |
agent.py |
Host-side launcher (mounts, UID mapping, secret masking) |
build.sh |
Build orchestration (--debian / --all) |
docker-compose.yml |
Volumes + env for the run |
compose.gpu.yaml |
GPU/display passthrough override (agent.py --gpu) |
opencode.json |
OpenCode config (Swiss AI / Infomaniak provider, agents) |
scripts/flake-sync.sh |
Manages the self-editable flake in the agent_flake volume |
scripts/auto-update.sh |
Checksum-verified OpenCode CLI auto-updater |
.agent/skills/nix-temp/SKILL.md |
Skill: get tools on demand via nix shell/nix develop |
tests/ |
test_env_hiding.py — verifies secret masking |
Requirements: docker and (for the default image) nix with flakes on the host.