ClaudeBox: Claude Code Docker Development Environment

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.

• Per-Project Docker Images: Each project now maintains its own Docker image for complete isolation
• Intelligent Layer Caching: Optimized Docker builds with profile-specific layer caching
• Task Engine: Built-in compact task engine for reliable code generation (/taskengine)
• Automatic Profile Rebuilding: Detects profile changes and rebuilds automatically
• Enhanced Firewall Templates: Pre-configured allowlists for GitHub, GitLab, and Bitbucket
• Project-Specific Claude Config: Each project can have its own .claude.json settings
• Profile Dependencies: Smart dependency resolution (e.g., C profile 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
• Python Virtual Environments: Automatic per-project venv creation with uv
• Cross-Platform: Works on Ubuntu, Debian, Fedora, Arch, and more

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

The script will:

• ✅ Check for Docker (install if needed)
• ✅ Configure Docker for non-root usage
• ✅ Build the ClaudeBox image with MCP servers
• ✅ Create a global symlink for easy access
• ✅ Set up MCP configuration in your workspace

ClaudeBox supports running multiple instances in different projects simultaneously:

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)

ClaudeBox includes 15+ pre-configured development environments:

• c - C/C++ Development (gcc, g++, gdb, valgrind, cmake, cmocka, lcov, ncurses)
• openwrt - OpenWRT Development (cross-compilation, QEMU, build essentials)
• rust - Rust Development (cargo, rustc, clippy, rust-analyzer)
• python - Python Development (pip, venv, black, mypy, pylint, poetry, pipenv)
• go - Go Development (latest Go toolchain)
• javascript - Node.js/TypeScript (npm, yarn, pnpm, TypeScript, ESLint, Prettier)
• java - Java Development (OpenJDK 17, Maven, Gradle, Ant)
• ruby - Ruby Development (Ruby, gems, bundler)
• php - PHP Development (PHP, Composer, common extensions)
• database - Database Tools (PostgreSQL, MySQL, SQLite, Redis, MongoDB clients)
• devops - DevOps Tools (Docker, Kubernetes, Terraform, Ansible, AWS CLI)
• web - Web Development (nginx, curl, httpie, jq)
• embedded - Embedded Development (ARM toolchain, OpenOCD, PlatformIO)
• datascience - Data Science (NumPy, Pandas, Jupyter, R)
• security - Security Tools (nmap, tcpdump, wireshark, penetration testing)
• ml - Machine Learning (PyTorch, TensorFlow, scikit-learn, transformers)

Save your preferred security flags to avoid typing them every time:

View detailed information about your ClaudeBox setup:

ClaudeBox contains a compact task engine for reliable code generation tasks:

ClaudeBox stores data in:

• ~/.claude/ - Claude configuration and data
• ~/.claudebox/ - Global ClaudeBox data
• ~/.claudebox/profiles/ - Per-project profile configurations
• ~/.claudebox/<project-name>/ - Project-specific data (memory, context, firewall, .claude.json)
• Current directory mounted as /workspace in container

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

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

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
• Profile-specific development tools with intelligent layer caching

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:

1. The script will add you to the docker group
2. You may need to log out/in or run newgrp docker
3. Run claudebox again

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

ClaudeBox automatically creates a venv when Python profile is active:

Ensure the symlink was created:

Each project has its own Docker image and is fully isolated. To check status:

If builds are slow or failing:

• 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