Agent in a Box (aib)

One command gives your coding agent a full dev environment per project, and keeps it off your host.

cd ~/code/anything
aib claude

That's it. You get a Debian box with Go, Node, Python, docker, git, gh, zsh, tmux, and ripgrep already in it, your workspace mounted at the same path it has on your host, and Claude Code (or Codex) running inside. Log in once and the token persists across rebuilds.

The agent can install packages, start databases, run docker compose, and use --dangerously-skip-permissions, all inside the box.

AIB_high_no.mp4

Warning

Do consider AIB a developer experience solution rather than a security solution. It tries to bridge "agent sandbox" with "developer convenience" of your favorite editor. "Bridge" explicitly means, that 100% isolation is not the foremost design goal.

Why

Coding agents are most useful when you let them work.

But giving an agent unrestricted shell access on your laptop is uncomfortable for good reasons. It can install packages, modify files outside your project, access credentials etc.

Keeping an agent on "per command" approval is safer but slow and cumbersome.

AIB aims to give an agent freedom inside a disposable development environment.

Requirements

macOS. Linux is not supported yet, because the approval daemon is a launchd user agent and the prompt is AppleScript (#2). Windows is not supported.

• A Docker-compatible daemon reachable via docker: OrbStack, Docker Desktop, or Colima.
• devcontainer CLI: npm install -g @devcontainers/cli
• VS Code (optional, for aib code), Zed (optional, for aib zed)

Install

Download the archive for your architecture from the latest release, put aib on your PATH, and run aib doctor.

Or from source:

git clone https://github.com/agentic-commerce-lab/agent-in-a-box.git
cd agent-in-a-box
make install                        # installs into $HOME/.local/bin
export PATH="$HOME/.local/bin:$PATH"
aib doctor

The dev-container base and proxy images are published to GHCR and pulled on first use, so there is no image build in the install path.

Quickstart

mkdir ~/code/foo && cd ~/code/foo
aib claude                          # Claude Code in the box
aib codex                           # Codex in the box
aib enter                           # just a shell
aib code                            # VS Code, attached to the container
aib zed                             # Zed (prompts to reopen in container)

The first of these you run in a fresh directory asks:

No aib.yml in /Users/you/code/foo. Scaffold a default project here (home_mode=hybrid)? [Y/n]

Say yes and AIB writes aib.yml plus .devcontainer/, reserves a globally unique project_name in ~/.aib/projects.yaml, starts the container, and opens your editor. Directory-name collisions are auto-numbered (foo, foo-1, …).

What you get

No-prompting development

aib claude --danger                 # --dangerously-skip-permissions
aib codex --danger                  # --dangerously-bypass-approvals-and-sandbox

--danger disables the agent's prompting, not the box. This is the main reason to use AIB: the blast radius is a container, so you can stop click-approving every file write.

Docker inside

docker and docker compose work normally in the box. Your app containers come up as siblings, reachable at host.docker.internal:<port>, and published ports work from the host as usual. If your stack uses an internal network, join it:

# aib.yml
network_join: myapp_default

Brownfield projects

Scaffolding detects an existing .devcontainer/ or compose.yml and leaves them alone, adding only aib.yml. Because the workspace is mounted at the same absolute path inside and out, existing compose volumes: keep resolving.

Paste screenshots into your agent

aib paste-image
# ![pasted image](/tmp/pasted/0f3a....png)

Copies the image on your clipboard into the container and puts a Markdown link on your clipboard, ready to paste into a Claude or Codex prompt.

This is still cumbersome - but only needed for codex/claude directly. VCCode and Zed support pasting images OOTB

Copy agent config

Host ~/.claude and ~/.codex config is not visible in the box by default. Copy it in explicitly:

aib push-agent-config               # plugins, agents, commands, CLAUDE.md
aib push-agent-config --dry-run
aib push-agent-config --include-memory

Credentials and session state are never copied. Log in inside the box once.

Templates that move forward

AIB generates .devcontainer/compose.yml, Dockerfile, devcontainer.json, and post-create.sh. After upgrading aib, pull the new versions in:

aib update-config                   # diff per file, prompt to apply
aib update-config --yes
aib rebuild                         # rebuild with the new config

aib.yml is never modified. compose.yml also re-renders on every entry-point command while its # aib-managed: header is intact, so small template changes land without you doing anything.

Teardown

aib down                            # stop the dev container
aib down --apps                     # also stop sibling app containers
aib rebuild                         # from scratch, no cache
aib nuke                            # remove per-project volumes, deregister
aib nuke --path /abs/path           # from anywhere
aib nuke --select                   # pick interactively

Configuration

# aib.yml
project_name: foo                   # reserved globally in ~/.aib/projects.yaml
host_path: /Users/you/code/foo       # bind-mount target
home_mode: hybrid                   # isolated | shared | hybrid
# network_join: myapp_default
# allowed_binds: [/Users/you/shared-data]

home_mode controls how much of /home/agent is shared between projects. Your host filesystem is never exposed through it in any mode.

• hybrid (default): caches and agent auth shared, so you log into Claude once; shell history, loose files, and self-updated agent CLIs stay per-project.
• isolated: nothing shared. A new project re-installs and re-authenticates.
• shared: one home for everything. Most convenient, and an agent in one project can read another's tokens.

aib list shows every registered project with a status: ok, missing (path gone), uninitialized (no aib.yml), or mismatch (registry and aib.yml disagree on the name).

How the boundary works

Short version:

• Workspace bind-mount at the same absolute path. No other host path is visible.
• aib-proxy inspects every Docker API call and rejects --privileged, host namespace sharing, host bind mounts, and Docker socket re-mounts. The agent only sees containers it created itself.
• Read-only config mounts, so the agent can't rewrite its own next boot.
• aib-hostd, a host-side daemon that prompts before anything in the box uses your real SSH agent.

Longer versions: docs/architecture.md for the shape, and docs/internals/ for the implementation, including what is trusted, what is enforced, and what is out of scope.

What this does not do

AIB keeps the agent off your host. It does not make what the agent writes safe.

• Local code. The workspace is a bind-mount; agent-written code persists on your disk. Review before running it outside the box.
• Remote side effects. git push, deploys, outbound API calls. AIB does not mediate outbound network traffic. If you need egress control, add iptables rules to the generated .devcontainer/Dockerfile; Anthropic's example dev container has a default-deny setup worth copying.
• Checked-in secrets. .env files and tokens inside the workspace are readable from the box.
• Git over HTTPS credential helpers are gated on a best-effort basis from inside the container; only SSH goes through the host-side approval path.

Treat it as a safety net, not a shield.

Alternatives

A lot of options appeared in the last months, each with different strengths and trade-offs. Please have a look at awesome-agent-sandbox for an overview.

Docs

• Architecture: the boundary in detail
• Internals: implementation reference, per component
• VS Code setup: DOCKER_HOST for GUI apps, extension paths
• Zed setup: aib zed and current Zed dev container caveats
• Troubleshooting
• Contributing

License

MIT. See LICENSE.