RchGrav/claudebox

ClaudeBox – A Docker‑based Development Environment for Anthropic’s Claude Code

What it is

• A command‑line tool that sets up an isolated Docker container pre‑loaded with the Claude Code CLI (Anthropic’s AI coding assistant) and a suite of development tools.
• Each project gets its own Docker image, Python virtual environment, firewall allowlist, and persistent Claude authentication/history, so you can work on many projects side‑by‑side without cross‑contamination.

Key capabilities

Feature	What you get
Containerized Claude	Runs Claude Code inside a Debian‑based Docker image, automatically installing Docker if it’s missing.
Development profiles	One‑click installation of language stacks (C/C++, Python, Rust, Go, Java, JavaScript, etc.) and specialised toolsets (OpenWRT, DevOps, Security, Data‑Science, etc.).
Per‑project isolation	Separate Docker images, auth files, shell history, and tool configs for each project (called slots).
Persistent configuration	Profiles, installed packages, and the Python uv virtual environment survive container restarts.
Multi‑instance support	Launch independent Claude sessions in different project directories simultaneously.
Security controls	Project‑specific firewall allowlists; optional --enable‑sudo, --disable‑firewall, or --dangerously‑skip‑permissions flags.
Rich developer experience	GitHub CLI, Delta, fzf, Powerline‑styled Zsh, and built‑in tmux integration for multi‑pane workflows.
Clipboard bridge (macOS)	Optional service that forwards images/text between the host clipboard and the container (limited to 20 MiB images / 1 MiB text).
Task engine	Simple /task command inside Claude to break down and iterate on code‑generation tasks.

Installation (quick start)

# Grab the self‑extracting installer
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox.run
chmod +x claudebox.run
./claudebox.run          # extracts to ~/.claudebox/source/ and links ~/.local/bin/claudebox

The installer will also check for Docker and configure it for non‑root use on first run.

If you prefer a manual archive, download the tarball from the Releases page, extract it, and run ./main.sh to create the symlink.

Typical workflow

# Inside a project directory
claudebox create               # creates a new “slot” (persistent Claude session)
claudebox slots                # list existing slots and their status
claudebox add python           # add a development profile (optional)
claudebox slot 1               # attach to slot 1 – you’ll be dropped into a shell with Claude ready

You can start another slot in the same or a different project with another claudebox create. Running claudebox without arguments automatically picks an inactive slot.

Managing profiles

claudebox profiles                 # list all available profiles with descriptions
claudebox profile                 # interactive menu to add/remove profiles
claudebox profile status          # see which profiles are active for the current project
claudebox profile rust go         # install Rust and Go toolchains for this project

Profiles are cached in the project’s Docker image, so installing a new one triggers a rebuild of that image only.

Running Claude with custom flags

claudebox --model opus -c          # start Claude with the *opus* model and code‑generation mode
claudebox save --enable-sudo       # remember the flag so future runs inherit it

Saved flags are stored locally and applied automatically to subsequent claudebox commands.

Clipboard support (macOS only)

claudebox --clipboard               # start a session that can read/write the host clipboard

The bridge creates a short‑lived HTTP listener bound to localhost; the session token acts as a secret. It is disabled by default for security.

Cleaning & maintenance

• claudebox clean – interactive menu to delete profile files, project data, Docker images, or everything for the current project.
• claudebox clean --containers / --image / --cache / --volumes – global Docker cleanup options.
• claudebox rebuild – force a fresh rebuild of the project’s Docker image.

Where data lives

• ~/.claudebox/source/ – the installed scripts.
• ~/.claudebox/projects/<project‑id>/ – per‑project state (profiles, Docker image tag, firewall rules, Python venv, etc.).
• ~/.claudebox/projects/<project‑id>/<slot‑id>/.claude/ – Claude authentication tokens, session history, and config files.
• The host workspace is mounted read‑write at /workspace inside the container; the host’s ~/.gitconfig is mounted read‑only.

Who might use this

• Developers who want a reproducible, isolated environment for Claude Code without manually configuring Docker, language runtimes, or security settings.
• Teams that need per‑project sandboxing (different Python versions, separate network allowlists, etc.) while still sharing a single host machine.
• Anyone looking for a “plug‑and‑play” AI‑assisted coding setup that mirrors a full development workstation.

License

• MIT (see LICENSE).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.