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 (a