claudebox: a shell-driven Docker wrapper that puts Claude Code in a disposable container

A shell program, not a framework, and that shapes everything

GitHub reports Shell as the primary language, and the file listing explains why. There is a `main.sh` at the root, a `lib/` directory for the command implementations, a `build/` directory, a checked-in `claudebox.run` self-extracting installer, `templates/` for image generation, and `tests/` for the compatibility suite. There is also a `CLAUDE.md` and a `.claude/` directory at the root, plus a `forge.yaml`, which tells you the author uses Claude Code to work on ClaudeBox.

That matters for how you should judge it. A shell installer can be read in an afternoon and audited before you run it, which is a genuine advantage over an opaque binary. The same size of shell program also has no type system and no runtime safety net, which is why the v1.0.0-rc5 notes are almost entirely about Bash 3.2 unbound variable errors and why v2.0.1 opens with a list of Bash 3.2 empty-array fixes in fresh installs, saved flags, profiles and runtime paths.

The project description gives the aim without hedging: a containerized, reproducible development environment for Claude Code with pre-configured profiles and MCP servers. The stated prerequisites are Linux or macOS, a Bash shell, and Docker, which the installer will install for you on first run.

Slots are the unit of persistence, and the container is disposable

The README explains the central model carefully, and it is the part most worth understanding before you use it. A slot is a persistent Claude session and configuration directory for a project. Slots share the project's workspace, Docker image, profiles and Python environment, but each slot has its own Claude authentication, history and tool configuration.

The running container, by contrast, is temporary. When you exit normally, the slot's mounted data survives; the container itself does not. So the security property you get is that a session's filesystem changes and installed tools do not carry into a later run unless you persist them deliberately, while your login and history do carry across runs.

The commands follow from that. `claudebox create` makes a first slot, `claudebox slots` shows slot numbers with authentication and running state, `claudebox add python` adds profiles, and `claudebox slot 1` launches a specific one. Bare `claudebox` picks an available inactive slot, and `claudebox slot <number>` attaches to that slot when it is already running.

Two constraints are stated and both are reasonable guardrails. Extra Claude arguments need an inactive slot, because you cannot change a running session's flags. And `claudebox revoke` removes the highest-numbered inactive slot including its saved authentication and history, refusing to remove an active one, while `revoke all` skips active slots. Neither command touches the project workspace.

Profiles decide what is in the image

Profiles are pre-configured language stacks, and the README names C/C++, Python, Rust and Go among them. Adding a profile is one command, `claudebox add python`, and the feature list advertises automatic dependency resolution, with C pulling in build-tools as the example.

The Python path is the most opinionated. The feature list includes automatic per-project virtual environment creation with uv, and the release notes for v2.0.1 mention preserving managed Python interpreters across fresh containers and slot changes, which is the fix for the case where a rebuilt image quietly lost a venv the user had been working in.

Beyond language stacks, the feature list covers the parts of a shell that people actually miss. GitHub CLI, Delta for diffs, fzf for fuzzy finding, zsh with oh-my-zsh powerline, syntax highlighting and autosuggestions, and tmux socket mounting for multi-pane workflows. That last one is the kind of detail that separates a usable dev environment from a bare container, since a shared tmux socket lets you keep several panes on the same session.

A `profiles` command exists to list everything available with descriptions, and the feature list also names package management for adding further tools after the fact. Existing project images rebuild when changed build inputs are detected, so a profile change does not require deleting the image.

The firewall fails closed, which is the detail to check first

Security in this project rests on network isolation with project-specific firewall allowlists, and there is an `allowlist` command to view and edit them. The v2.0.1 notes record a bug here that is worth understanding, because the fix direction tells you what the design intends.

The bug: firewall startup could leave default policies open if DNS resolution failed. The fix: firewall setup failures now stop session startup. In other words, if the allowlist cannot be applied, the session does not start. A tool that quietly runs with unrestricted egress when its own hardening step fails is worse than one that refuses to run, and the maintainer chose the refusing behaviour.

The other security-relevant item is the opt-in macOS clipboard bridge, added in v2.0.1 as `claudebox --clipboard`, enabled per session with `claudebox --clipboard slot 1`. The constraints are spelled out and they are tight: it requires host Python 3, the bridge is loopback-only, authenticated per session, bounded, and stopped with its launcher. It handles clipboard images and application text copy, and explicitly does not read host clipboard text.

So the trust boundary to hold in your head is this. The container is the sandbox for Claude Code. The clipboard bridge is a deliberate, opt-in, authenticated channel out of it, and it is the one place where data crosses back to the host by design.

Installation is one script, and you can build it yourself first

The recommended path is a self-extracting installer from the releases page:

wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox.run
chmod +x claudebox.run
./claudebox.run

What that does is documented: extract to `~/.claudebox/source/`, create a symlink at `~/.local/bin/claudebox`, check for Docker and install it if absent, and configure Docker for non-root usage on first run. If `~/.local/bin` is not on your PATH the installer says so and prints the two lines to add, one for bash and one for zsh.

A second method downloads a versioned archive and runs `./main.sh` from wherever you extracted it, or you make your own symlink. The README is careful about version here: the source tree is v2.0.1, release downloads carry the latest published version, and for the archive example the latest published release at the time of writing is v2.0.0.

The development path is the one to use if you want to see what you are running. Clone the repository, `bash .builder/build.sh`, then `./dist/claudebox.run profiles`. That builds an installer from your own checkout instead of fetching a binary, which is the reasonable habit for a shell program that installs Docker and manages your agent credentials.

Updates commit the container back into the image

The v1.0.0-rc5 notes explain the update mechanism in enough detail to be worth quoting, because it is a non-obvious approach. Rather than reinstalling into a fresh container, the update command creates a named container instead of using `--rm`, runs `claude update` inside it, verifies with `claude --version`, commits that container back to the image, then removes the temporary container, and preserves the wrapper for future runs.

Committing is the key word. It means the updated Claude binary becomes part of the project's image, so every future slot launch gets the new version without re-running the update. The same notes record the bugs that shaped this: `claudebox update` failing with a container not running error, and the claude wrapper being deleted mid-update. A `SHOULD_PERSIST` flag was added to stop that deletion during updates.

The v2.0.0 release, dated 2025-07-25, is the macOS milestone and a build system overhaul. It fixed Docker Desktop detection so the installer no longer tried `systemctl` on macOS, resolved Docker build permission problems, put Python on the PATH inside tmux sessions, added version tracking through a `CLAUDEBOX_VERSION` constant, moved build output into `dist/`, and added first-run PATH detection that works in both bash and zsh.

The gap worth noting is that the README on the repository page ends mid-sentence in its macOS clipboard section, and 18 open issues sit against 1,156 stars and 128 forks. The tree carries `docs/`, and the README points at docs/operations.md for installer internals, real storage paths, host access to session logs and persistent tools, which is the document to read before you trust anything with your source tree.

Editorial conclusion

claudebox is a reasonable answer to a real problem, which is that a coding agent with shell access on your machine is a different risk profile from the same agent in a container. The design is sound where it counts: per-project images, per-slot authentication, an allowlist that fails closed, and an update command that commits the container back into the image rather than throwing work away. The cost is that this is a Bash program of real size doing a lot, it needs Docker running before anything works, and it manages your Claude credentials itself, so the security of the host machine is now partly a property of a shell script you downloaded. If you take one thing from the v2.0.1 notes, take the firewall behaviour, where a DNS resolution failure now stops the session instead of leaving the network wide open. Read the storage paths in docs/operations.md before your first commit, then start with a profile for a language you already have tools for.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. RchGrav/claudebox on GitHub
4. README
5. Releases