ClaudeBox 🐳

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.

 ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
██║     ██║     ███████║██║   ██║██║  ██║█████╗
██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝

██████╗  ██████╗ ██╗  ██╗
██╔══██╗██╔═══██╗╚██╗██╔╝
██████╔╝██║   ██║ ╚███╔╝ 
██╔══██╗██║   ██║ ██╔██╗ 
██████╔╝╚██████╔╝██╔╝ ██╗
╚═════╝  ╚═════╝ ╚═╝  ╚═╝

🚀 What's New in Latest Update

Enhanced UI/UX: Improved menu alignment and comprehensive info display
New profiles Command: Quick listing of all available profiles with descriptions
Firewall Management: New allowlist command 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)

✨ Features

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

📋 Prerequisites

Linux or macOS (WSL2 for Windows)
Bash shell
Docker (will be installed automatically if missing)

🛠️ Installation

ClaudeBox v2.0.0 offers two installation methods:

Method 1: Self-Extracting Installer (Recommended)

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.run

This will:

Extract ClaudeBox to ~/.claudebox/source/
Create a symlink at ~/.local/bin/claudebox (you may need to add ~/.local/bin to your PATH)
Show setup instructions if PATH configuration is needed

Method 2: Archive Installation

For manual installation or custom locations, use the archive:

# Download the archive
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox-2.0.0.tar.gz

# Extract to your preferred location
mkdir -p ~/my-tools/claudebox
tar -xzf claudebox-2.0.0.tar.gz -C ~/my-tools/claudebox

# 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/claudebox

Development Installation

For 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
./claudebox.run

PATH Configuration

If 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 ~/.zshrc

The 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)

📚 Usage

Basic Usage

# 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 additions

Multi-Instance Support

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 ml

Each 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)

Development Profiles

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 + Go

Available Profiles:

Core 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)

Default Flags Management

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 disabled

Project Information

View comprehensive information about your ClaudeBox setup:

# Show detailed project and system information
claudebox info

The 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

Package Management

# 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 allowlist

Tmux Integration

ClaudeBox 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-9

ClaudeBox automatically detects and mounts existing tmux sockets from the host, or provides tmux functionality inside the container for powerful multi-context workflows.

Task Engine

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

Security Options

# 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

Maintenance

# 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 rebuild

🔧 Configuration

ClaudeBox stores data in:

~/.claude/ - Global Claude configuration (mounted read-only)
~/.claudebox/ - Global ClaudeBox data
~/.claudebox/profiles/ - Per-project profile configurations (*.ini files)
~/.claudebox/<project-name>/ - Project-specific data:
- .claude/ - Project auth state
- .claude.json - Project API configuration
- .zsh_history - Shell history
- .config/ - Tool configurations
- firewall/allowlist - Network allowlist
Current directory mounted as /workspace in container

Project-Specific Features

Each project automatically gets:

Docker Image: claudebox-<project-name> with installed profiles
Profile Configuration: ~/.claudebox/profiles/<project-name>.ini
Python Virtual Environment: .venv created with uv when Python profile is active
Firewall Allowlist: Customizable per-project network access rules
Claude Configuration: Project-specific .claude.json settings

Environment Variables

ANTHROPIC_API_KEY - Your Anthropic API key
NODE_ENV - Node environment (default: production)

🏗️ Architecture

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)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Troubleshooting

Docker Permission Issues

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 claudebox again

Profile Installation Failed

# Clean and rebuild for current project
claudebox clean --project
claudebox rebuild
claudebox profile <name>

Profile Changes Not Taking Effect

ClaudeBox automatically detects profile changes and rebuilds when needed. If you're having issues:

# Force rebuild
claudebox rebuild

Python Virtual Environment Issues

ClaudeBox automatically creates a venv when Python profile is active:

# The venv is created at ~/.claudebox/<project>/.venv
# It's automatically activated in the container
claudebox shell
which python  # Should show the venv python

Can't Find Command

Ensure the symlink was created:

ls -la ~/.local/bin/claudebox
# Or manually create it
ln -s /path/to/claudebox ~/.local/bin/claudebox

Multiple Instance Conflicts

Each 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 --project

Build Cache Issues

If builds are slow or failing:

# Clear Docker build cache
claudebox clean --cache

# Complete cleanup and rebuild
claudebox clean --all
claudebox

🎉 Acknowledgments

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

Contact

Author/Maintainer: RchGrav
GitHub: @RchGrav

Name		Name	Last commit message	Last commit date
Latest commit History 221 Commits
.builder		.builder
.claude		.claude
.github/workflows		.github/workflows
build		build
claude		claude
commands		commands
docs		docs
lib		lib
pytask		pytask
templates		templates
tests		tests
tooling/profiles		tooling/profiles
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
claudebox.run		claudebox.run
forge.yaml		forge.yaml
main.sh		main.sh
tdd-system.tar.gz		tdd-system.tar.gz

License

RchGrav/claudebox

Folders and files

Latest commit

History

Repository files navigation