Sandboxed development environment for Claude Code, OpenCode, and Codex
README.md

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 from flake.nix via Nix's dockerTools. The toolchain comes from the host's nix store / binary cache, so nothing is recompiled inside Docker.
  • agent-sandbox-debian — built from Dockerfile-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-sandbox or set OPENAI_SANDBOX_MODE=none per 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. nixpkgs is 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 works
    

    The nix-temp skill (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.nix lives in the agent_flake docker 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-sync manages 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 repo
    

    To actually bake an edit into a future image: flake-sync export into a mounted copy of this repo, commit there, and run ./build.sh on the host.

How it works #

Build (build.sh):

  1. On Linux, nix build .#dockerImage produces a layered image tarball (./result). On macOS, the script performs the same Linux build in the official nixos/nix Docker image, since Darwin cannot execute Linux Nix derivations directly. with the nix store DB seeded so the baked-in paths are registered.
  2. docker load < result loads it as agent-sandbox-base:latest.
  3. docker build -t agent-sandbox . (Dockerfile) layers on the non-nix bits: the three harness CLIs, the abra and tg binaries, a setuid sudo, the rust toolchain, and OpenCode config.
  4. The complete secrets/ directory (including hidden files) is synced into the explicitly named agent_secrets Docker volume. Every sandbox mounts that volume read-write at /secrets, without baking secrets into an image.
  5. The latest agent-orchestrator repository is cloned into the explicitly named agent_tools Docker 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/agent and the build target/ in named volumes, and mounts build-synced test secrets read-write at /secrets;
  • mounts the build-synced agent-orchestrator checkout read-write at /tools/agent-orchestrator;
  • passes HOST_UID/HOST_GID so files written in /workspace are owned by you;
  • generates a compose override that masks sensitive files (.env, secret.json, …) with /dev/null and tmpfs over sensitive directories, so the agent cannot read them — see SENSITIVE_NAMES/SENSITIVE_DIRS in agent.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.