The Ultimate Claude Code Docker Development Environment - Run Claude AI's coding assistant in a fully containerized, reproducible environment with pre-configured development profiles and MCP servers.
██████╗██╗ █████╗ ██╗ ██╗██████╗ ███████╗
██╔════╝██║ ██╔══██╗██║ ██║██╔══██╗██╔════╝
██║ ██║ ███████║██║ ██║██║ ██║█████╗
██║ ██║ ██╔══██║██║ ██║██║ ██║██╔══╝
╚██████╗███████╗██║ ██║╚██████╔╝██████╔╝███████╗
╚═════╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
██████╗ ██████╗ ██╗ ██╗
██╔══██╗██╔═══██╗╚██╗██╔╝
██████╔╝██║ ██║ ╚███╔╝
██╔══██╗██║ ██║ ██╔██╗
██████╔╝╚██████╔╝██╔╝ ██╗
╚═════╝ ╚═════╝ ╚═╝ ╚═╝
- Enhanced UI/UX: Improved menu alignment and comprehensive info display
- New
profilesCommand: Quick listing of all available profiles with descriptions - Firewall Management: New
allowlistcommand to view/edit network allowlists - Per-Project Isolation: Separate Docker images, auth state, history, and configs
- Improved Clean Menu: Clear descriptions showing exact paths that will be removed
- Profile Management Menu: Interactive profile command with status and examples
- Persistent Project Data: Auth state, shell history, and tool configs preserved
- Smart Profile Dependencies: Automatic dependency resolution (e.g., C includes build-tools)
- Containerized Environment: Run Claude Code in an isolated Docker container
- Development Profiles: Pre-configured language stacks (C/C++, Python, Rust, Go, etc.)
- Project Isolation: Complete separation of images, settings, and data between projects
- Persistent Configuration: Settings and data persist between sessions
- Multi-Instance Support: Work on multiple projects simultaneously
- Package Management: Easy installation of additional development tools
- Auto-Setup: Handles Docker installation and configuration automatically
- Security Features: Network isolation with project-specific firewall allowlists
- Developer Experience: GitHub CLI, Delta, fzf, and zsh with oh-my-zsh powerline
- Python Virtual Environments: Automatic per-project venv creation with uv
- Cross-Platform: Works on Ubuntu, Debian, Fedora, Arch, and more
- Shell Experience: Powerline zsh with syntax highlighting and autosuggestions
- Tmux Integration: Seamless tmux socket mounting for multi-pane workflows
- Linux or macOS (WSL2 for Windows)
- Bash shell
- Docker (will be installed automatically if missing)
The source version is v2.0.1. Release downloads contain the latest published
version; use Development Installation to test changes
on main that have not yet been released.
The self-extracting installer is ideal for automated setups and quick installation:
# Download the latest release
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox.run
chmod +x claudebox.run
./claudebox.runThis will:
- Extract ClaudeBox to
~/.claudebox/source/ - Create a symlink at
~/.local/bin/claudebox(you may need to add~/.local/binto your PATH) - Show setup instructions if PATH configuration is needed
For manual installation or custom locations, use the archive:
# Download a versioned archive from the Releases page, then set its filename.
# The latest published release at the time of this update is v2.0.0.
ARCHIVE=claudebox-2.0.0.tar.gz
wget "https://github.com/RchGrav/claudebox/releases/latest/download/$ARCHIVE"
# Extract to your preferred location
mkdir -p ~/my-tools/claudebox
tar -xzf "$ARCHIVE" -C ~/my-tools/claudebox --strip-components=1
# Run main.sh to create symlink
cd ~/my-tools/claudebox
./main.sh
# Or create your own symlink
ln -s ~/my-tools/claudebox/main.sh ~/.local/bin/claudeboxFor development or testing the latest changes:
# Clone the repository
git clone https://github.com/RchGrav/claudebox.git
cd claudebox
# Build the installer
bash .builder/build.sh
# Run the installer built from this checkout
./dist/claudebox.run profilesIf claudebox command is not found after installation, add ~/.local/bin to your PATH:
# For Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# For Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcThe installer will:
- ✅ Extract ClaudeBox to
~/.claudebox/source/ - ✅ Create symlink at
~/.local/bin/claudebox - ✅ Check for Docker (install if needed on first run)
- ✅ Configure Docker for non-root usage (on first run)
A slot is a persistent Claude session/configuration directory for a project. Slots share that project's workspace, Docker image, profiles, and Python environment; each slot has its own Claude authentication, history, and tool configuration. The running container is temporary; the slot's mounted data survives normal exit.
cd ~/projects/my-project
claudebox create # Create your first slot
claudebox slots # Show slot numbers, authentication and running state
claudebox add python # Optional: add development profiles
claudebox slot 1 # Launch slot 1; authenticate inside Claude if neededFor another simultaneous session, run claudebox create again and launch the new
number shown by claudebox slots. Bare claudebox selects an available slot.
claudebox slot <number> attaches to that slot if it is already running. Extra
Claude arguments require an inactive slot because they cannot change a running
session. Bare claudebox continues to select an inactive slot.
claudebox revoke removes the highest-numbered slot if it is inactive, including
its saved authentication and history; it refuses to remove an active slot. claudebox revoke all removes inactive slots while
skipping active ones. Neither command deletes the project workspace.
See Installation, persistence and customization for installer internals, actual storage paths, host access to session logs, and persistent tools.
# Launch Claude Code CLI
claudebox
# Pass arguments to Claude
claudebox --model opus -c
# Save your arguments so you don't need to type them every time
claudebox --model opus -c
# View the Claudebox info screen
claudebox info
# Get help
claudebox --help # Shows Claude help with ClaudeBox additionsEnable clipboard access when starting a session:
claudebox --clipboard
# Or select an inactive slot:
claudebox --clipboard slot 1This optional feature requires Python 3 on the Mac. It lets container applications read clipboard images and replace clipboard text while the session is running. It does not expose host clipboard text for reading. Without this option, ClaudeBox does not start a clipboard service.
Use Claude Code's image-paste shortcut (Ctrl+V in most terminals) after copying
an image or screenshot. Text copy through Linux clipboard utilities is forwarded
to macOS too. Images are limited to 20 MiB and text writes to 1 MiB. The bridge uses
a random session token, permits only its host TCP port through the container
firewall, and shuts down with the launching session. Detached launches do not
start an independent clipboard service.
The HTTP listener binds only to host loopback; treat the session token as a
secret and enable this only for containers you trust with that
clipboard access. Enabling it on an already-running slot requires restarting that
slot unless it was started with clipboard support.
If Docker detach keys leave the container running after its launcher exits, the
bridge stops too; restart that slot to restore clipboard access.
Terminal selection is separate from application clipboard access. In Apple Terminal, if a wrapped login URL cannot be selected, use Select All, copy into an editor, then copy just the URL. This workaround was confirmed in issue #107. Terminals that support clipboard escape sequences may require permission in their settings. See tmux's clipboard guide when using host tmux.
ClaudeBox supports running multiple instances in different projects simultaneously:
# Terminal 1 - Project A
cd ~/projects/website
claudebox
# Terminal 2 - Project B
cd ~/projects/api
claudebox shell
# Terminal 3 - Project C
cd ~/projects/ml-model
claudebox profile python mlEach project maintains its own:
- Docker image (
claudebox-<project-name>) - Language profiles and installed packages
- Firewall allowlist
- Python virtual environment
- Memory and context (via MCP)
- Claude configuration (
.claude.json)
ClaudeBox includes 15+ pre-configured development environments:
# List all available profiles with descriptions
claudebox profiles
# Interactive profile management menu
claudebox profile
# Check current project's profiles
claudebox profile status
# Install specific profiles (project-specific)
claudebox profile python ml # Python + Machine Learning
claudebox profile c openwrt # C/C++ + OpenWRT
claudebox profile rust go # Rust + GoCore Profiles:
- core - Core Development Utilities (compilers, VCS, shell tools)
- build-tools - Build Tools (CMake, autotools, Ninja)
- shell - Optional Shell Tools (fzf, SSH, man, rsync, file)
- networking - Network Tools (IP stack, DNS, route tools)
Language Profiles:
- c - C/C++ Development (debuggers, analyzers, Boost, ncurses, cmocka)
- rust - Rust Development (installed via rustup)
- python - Python Development (managed via uv)
- go - Go Development (installed from upstream archive)
- flutter - Flutter Framework (installed using fvm, use FLUTTER_SDK_VERSION to set different version)
- javascript - JavaScript/TypeScript (Node installed via nvm)
- java - Java Development (Latest LTS via SDKMan, Maven, Gradle, Ant)
- ruby - Ruby Development (gems, native deps, XML/YAML)
- php - PHP Development (PHP + extensions + Composer)
Specialized Profiles:
- openwrt - OpenWRT Development (cross toolchain, QEMU, distro tools)
- database - Database Tools (clients for major databases)
- devops - DevOps Tools (Docker, Kubernetes, Terraform, etc.)
- web - Web Dev Tools (nginx, HTTP test clients)
- embedded - Embedded Dev (ARM toolchain, serial debuggers)
- datascience - Data Science (Python, Jupyter, R)
- security - Security Tools (scanners, crackers, packet tools)
- ml - Machine Learning (build layer only; Python via uv)
Save your preferred security flags to avoid typing them every time:
# Save default flags
claudebox save --enable-sudo --disable-firewall
# Clear saved flags
claudebox save
# Now all claudebox commands will use your saved flags automatically
claudebox # Will run with sudo and firewall disabledView comprehensive information about your ClaudeBox setup:
# Show detailed project and system information
claudebox infoThe info command displays:
- Current Project: Path, ID, and data directory
- ClaudeBox Installation: Script location and symlink
- Saved CLI Flags: Your default flags configuration
- Claude Commands: Global and project-specific custom commands
- Project Profiles: Installed profiles, packages, and available options
- Docker Status: Image status, creation date, layers, running containers
- All Projects Summary: Total projects, images, and Docker system usage
# Install additional packages (project-specific)
claudebox install htop vim tmux
# Open a powerline zsh shell in the container
claudebox shell
# Update Claude CLI
claudebox update
# View/edit firewall allowlist
claudebox allowlistClaudeBox provides tmux support for multi-pane workflows:
# Launch ClaudeBox with tmux support
claudebox tmux
# If you're already in a tmux session, the socket will be automatically mounted
# Otherwise, tmux will be available inside the container
# Use tmux commands inside the container:
# - Create new panes: Ctrl+b % (vertical) or Ctrl+b " (horizontal)
# - Switch panes: Ctrl+b arrow-keys
# - Create new windows: Ctrl+b c
# - Switch windows: Ctrl+b n/p or Ctrl+b 0-9ClaudeBox automatically detects and mounts existing tmux sockets from the host, or provides tmux functionality inside the container for powerful multi-context workflows.
ClaudeBox contains a compact task engine for reliable code generation tasks:
# In Claude, use the task command
/task
# This provides a systematic approach to:
# - Breaking down complex tasks
# - Implementing with quality checks
# - Iterating until specifications are met# Run with sudo enabled (use with caution)
claudebox --enable-sudo
# Disable network firewall (allows all network access)
claudebox --disable-firewall
# Skip permission checks
claudebox --dangerously-skip-permissions# Interactive clean menu
claudebox clean
# Project-specific cleanup options
claudebox clean --project # Shows submenu with options:
# profiles - Remove profile configuration (*.ini file)
# data - Remove project data (auth, history, configs, firewall)
# docker - Remove project Docker image
# all - Remove everything for this project
# Global cleanup options
claudebox clean --containers # Remove ClaudeBox containers
claudebox clean --image # Remove containers and current project image
claudebox clean --cache # Remove Docker build cache
claudebox clean --volumes # Remove ClaudeBox volumes
claudebox clean --all # Complete Docker cleanup
# Rebuild the image from scratch
claudebox rebuildClaudeBox stores data in:
~/.claudebox/source/- Installed source files~/.claudebox/projects/<project-id>/- Shared project state, includingprofiles.ini~/.claudebox/projects/<project-id>/<slot-id>/.claude/- Per-slot authentication, sessions and history~/.claudebox/projects/<project-id>/<slot-id>/.claude.json,.config/,.cache/- Per-slot settings and tool data~/.claudebox/projects/<project-id>/.venv/and.local/share/uv/python/- Shared Python environment and managed interpreters~/.claudebox/ssh/- Optional dedicated SSH directory- Current project directory - Mounted read-write at
/workspace, including a normal repository's.gitdirectory
The host's entire ~/.claude/ directory is not mounted. User MCP configuration
is read from ~/.claude.json; commands are synchronized separately. Global skill
packages are not automatically imported.
ClaudeBox prefers ~/.claudebox/ssh/ and mounts it read-write, allowing persistent
known_hosts updates. This applies even when the directory is empty. Otherwise,
an existing host ~/.ssh/ is mounted read-only.
Read-only is not secret isolation. Container processes can read and use private keys in the mounted directory; read-only only prevents changing those host files. A dedicated directory limits which keys are exposed. An empty dedicated directory avoids mounting the host's normal SSH keys.
mkdir -p ~/.claudebox/ssh
chmod 700 ~/.claudebox/ssh
# Optional: generate a dedicated key and register its public key with your service.
ssh-keygen -t ed25519 -f ~/.claudebox/ssh/id_ed25519 -C "claudebox@$(hostname)"Use claudebox add shell to include openssh-client when ssh is missing. The
profile is installed on the next image build. SSH-agent forwarding is not provided
by this directory-mount mechanism.
Each project automatically gets:
- Docker Image:
claudebox-<project-name>with installed profiles - Profile Configuration:
~/.claudebox/projects/<project-id>/profiles.ini - Python Virtual Environment:
.venvcreated with uv when Python profile is active - Firewall Allowlist: Customizable per-project network access rules
- Claude Configuration: Project-specific
.claude.jsonsettings
A project .env file is both mounted read-only at /workspace/.env and loaded by
Docker's --env-file. For example:
ANTHROPIC_BASE_URL=https://your-api-endpoint.example
GH_TOKEN=your-fine-grained-token
ANTHROPIC_API_KEY=your-api-keyUse Docker env-file syntax (NAME=value), not shell commands or export statements.
The file is not executed or sourced. Keep real credentials out of Git commits.
An explicitly set host ANTHROPIC_API_KEY overrides the file, including an explicitly
empty value; an unset host key leaves the file's value intact. NODE_ENV is explicitly
forwarded from the host and defaults to production.
The host's ~/.gitconfig is also mounted read-only when it exists. Paths referenced
by that file, such as external include files or credential helpers, must be available
inside the container to work.
ClaudeBox creates a per-project Debian-based Docker image with:
- Node.js (via NVM for version flexibility)
- Claude Code CLI (@anthropic-ai/claude-code)
- User account matching host UID/GID
- Network firewall (project-specific allowlists)
- Volume mounts for workspace and configuration
- GitHub CLI (gh) for repository operations
- Delta for enhanced git diffs (version 0.17.0)
- uv for fast Python package management
- Nala for improved apt package management
- fzf for fuzzy finding
- zsh with oh-my-zsh and powerline theme
- Profile-specific development tools with intelligent layer caching
- Persistent project state (auth, history, configs)
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
ClaudeBox automatically handles Docker setup, but if you encounter issues:
- The script will add you to the docker group
- You may need to log out/in or run
newgrp docker - Run
claudeboxagain
# Clean and rebuild for current project
claudebox clean --project
claudebox rebuild
claudebox profile <name>ClaudeBox automatically detects profile changes and rebuilds when needed. If you're having issues:
# Force rebuild
claudebox rebuildClaudeBox automatically creates a venv when Python profile is active:
# The venv is created at ~/.claudebox/projects/<project-id>/.venv
# It's automatically activated in the container
claudebox shell
which python # Should show the venv pythonEnsure the symlink was created:
ls -la ~/.local/bin/claudebox
# Or manually create it
ln -s /path/to/claudebox ~/.local/bin/claudeboxEach project has its own Docker image and is fully isolated. To check status:
# Check all ClaudeBox images and containers
claudebox info
# Clean project-specific data
claudebox clean --projectIf builds are slow or failing:
# Clear Docker build cache
claudebox clean --cache
# Complete cleanup and rebuild
claudebox clean --all
claudebox- Anthropic for Claude AI
- Model Context Protocol for MCP servers
- Docker community for containerization tools
- All the open-source projects included in the profiles
Made with ❤️ for developers who love clean, reproducible environments
Author/Maintainer: RchGrav
GitHub: @RchGrav
