A Docker-based development environment for running agentic coding tools in a more safe, isolated fashion. This makes it less dangerous to give your agent full permissions (YOLO mode / --dangerously-skip-permissions), which is, in my opinion, the only way to use AI agents.
- Shares project directory with host: Maps a volume with the source code so that you can see and modify the agent's changes on the host machine - just like if you were running your tool without a container.
- Multi-Tool Support: Choose between Claude Code (default) or OpenCode via
--toolflag orAGENTBOX_TOOLenv var - Unified Development Environment: Single Docker image with Python, Node.js, Java, and Shell support
- Low-Maintenance Philosophy: Always uses latest LTS tool versions, rebuilds container automatically when necessary
- Isolated SSH: Dedicated SSH directory for secure Git operations
- Docker: Must be installed and running
- Bash 4.0+: macOS ships with Bash 3.2, I recommend upgrading via Homebrew (
brew install bash).
- Clone AgentBox to your preferred location (e.g.
~/code/agentbox/agentbox) - Ensure Docker is installed and running
- Make the script executable:
chmod +x agentbox - (Strongly recommended) add an alias for global access - e.g. alias
agentboxto~/code/agentbox/agentbox. - Run
agentboxfrom your desired working directory (wherever you would normally start your agentic coding tool).
# Start Claude CLI in container (--dangerously-skip-permissions is automatically included)
agentbox
# Use OpenCode instead of Claude
agentbox --tool opencode
# Or set via environment variable
AGENTBOX_TOOL=opencode agentbox
# Show available commands
agentbox --help
# Non-agentbox CLI flags are passed through to claude.
# For example, to continue the most recent session
agentbox -c
# Mount additional directories for multi-project access
agentbox --add-dir ~/proj1 --add-dir ~/proj2
# Start shell with sudo privileges
agentbox shell --admin
# Set up SSH keys for AgentBox
agentbox ssh-initNote: Tool selection via --tool flag takes precedence over the AGENTBOX_TOOL environment variable.
AgentBox creates ephemeral Docker containers (with --rm) that are automatically removed when you exit. However, important data persists between sessions:
Single Dockerfile → Build once → agentbox:latest image
↓
┌────────────────────┼────────────────────┐
↓ ↓ ↓
Container: project1 Container: project2 Container: project3
(ephemeral, --rm) (ephemeral, --rm) (ephemeral, --rm)
Mounts: ~/code/api Mounts: ~/code/web Mounts: ~/code/cli
Persistent data (survives container removal):
Cache: ~/.cache/agentbox/agentbox-<hash>/
History: ~/.agentbox/projects/agentbox-<hash>/history/
Claude: ~/.claude
OpenCode: ~/.config/opencode and ~/.local/share/opencode
The unified Docker image includes:
- Python: Latest version with
uvfor fast package management - Node.js: Latest LTS via NVM with npm, yarn, and pnpm
- Java: Latest LTS via SDKMAN with Gradle
- Shell: Zsh (default) and Bash with common utilities
- Claude CLI: Pre-installed with per-project authentication
- OpenCode: Pre-installed as an alternative AI coding tool
The gh tool is included in the image and can be used for all GitHub operations. My recommendation:
- Visit this link to configure a fine-grained access-token with a sensible set of permissions predefined.
- On that page, restrict the token to the project repository.
- Create a .env file at the root of your project repository with entry
GH_TOKEN=<token> - Add some instructions to the CLAUDE.md file, telling it to use the
ghtool for Git operations. You can see a slightly more complicated example in this repo, there is a sub-agent for git operations in .claude/agents and instructions in CLAUDE.md to remember to use agents.
You or your agent should convert ssh git remotes to https, ssh remotes don't work with tokens.
The glab tool is included in the image. You can use it with a GitLab token for API operations, but not for git operations as far as I know. So for GitLab I recommend the SSH configuration detailed below.
AgentBox copies your host ~/.gitconfig into the container on each startup. If you don't have a host gitconfig, it uses agent@agentbox as the default identity.
AgentBox uses a dedicated SSH directory (~/.agentbox/ssh/) isolated from your main SSH keys:
# Initialize SSH for AgentBox
agentbox ssh-initThis will:
- Create ~/.agentbox/ssh/ directory
- Copy your known_hosts for host verification
- Generate a new Ed25519 key pair (if preferred, delete them and manually place your desired SSH keys in
~/.agentbox/ssh/).
Environment variables are loaded from .env files in this order (later overrides earlier):
~/.agentbox/.env(global)<project-dir>/.env(project-specific)
AgentBox includes direnv support - .envrc files are evaluated if direnv allowed on the host.
Due to Claude Code bug #6130, by default you won't be prompted to enable MCP servers when running agentbox directly.
Workaround options:
-
Enable individual MCP servers interactively:
agentbox shell claude
-
Enable all MCP servers by default by adding
"enableAllProjectMcpServers": trueto your Claude project or user settings.
Package manager caches are stored in ~/.cache/agentbox/<container-name>/:
- npm packages:
~/.cache/agentbox/<container-name>/npm - pip packages:
~/.cache/agentbox/<container-name>/pip - Maven artifacts:
~/.cache/agentbox/<container-name>/maven - Gradle cache:
~/.cache/agentbox/<container-name>/gradle
Zsh history is preserved in ~/.agentbox/projects/<container-name>/history
Both tools use bind mounts to share authentication across all AgentBox projects:
Claude CLI:
~/.claudemounted at/home/agent/.claude
OpenCode:
- Config:
~/.config/opencodemounted at/home/agent/.config/opencode - Auth:
~/.local/share/opencodemounted at/home/agent/.local/share/opencode
If you need to run a single command in the containerized environment without starting Claude CLI or an interactive shell:
# Run any command
agentbox npm test# Force rebuild the Docker image
agentbox --rebuildThe image automatically rebuilds when the Dockerfile or entrypoint.sh changes
The Dockerfile is configured to pull the latest stable version of each tool (NVM, GitLab CLI, etc.) during the build process. This makes maintenance easy and ensures that we always use current software. It also means that rebuilding the Docker image may automatically result in newer versions of tools being installed, which could introduce unexpected behavior or breaking changes. If you require specific tool versions, consider pinning them in the Dockerfile.
Anthropic offers a devcontainer which achieves a similar goal. If you like devcontainers, that's a good option. Unfortunately, I find that devcontainers sometimes have weird bugs, problematic support in IntelliJ/Mac, or they are just more cumbersome to use (try switching to a recent project with a shortcut, for example). I don't want to force people to use a devcontainer if what they really want is safe YOLO-mode isolation - the simpler solution to the problem is just Docker, hence, this project.
AgentBox began as a simplified replacement for ClaudeBox. I liked the ClaudeBox project, but its complexity caused a lot of bugs and I found myself maintaning my own fork with my not-yet-merged PRs. It became easier for me to build something leaner for my own needs. Comparison:
| Feature | AgentBox | ClaudeBox |
|---|---|---|
| Files | 3 core files | 20+ files |
| Profiles | Single unified image | 20+ language profiles |
| Container Management | Simple per-project | Advanced slot system |
| Setup | Automatic | Manual configuration |
I make no guarantee to support this project in the future, however the history is positive: I've actively supported it since September 2025. Feel free to create issues and submit PRs. The project is designed to be understandable enough that if you need specific custom changes which we don't want centrally, you can fork or just make them locally for yourself.
If you do contribute, consider that AgentBox is designed to be simple and maintainable. The value of new features will always be weighed against the added complexity. Try to find the simplest possible way to get things done and control the AI's desire to write such bloated doco.