aibox

A secure, isolated Docker environment for running multiple AI command-line tools (Claude Code, Codex, and Gemini) with multi-account support and comprehensive security features.

Optimized for Node.js/JavaScript projects - Built on Node.js 20 Alpine, includes npm, and common development tools for modern JavaScript/TypeScript development.

🚀 Features

• Multi-CLI Support: Run Claude Code, Codex, or Gemini CLI from a single unified container
• Security First: Non-root user execution, capability dropping, and filesystem isolation
• Multi-Account: Manage separate configurations for work, personal, or client projects
• Persistent Configs: Direct host mapping of ~/.claude, ~/.codex, and ~/.gemini
• Interactive by Default: Opens bash shell by default - run any CLI manually or pass args to execute directly
• Git Integration: Seamless git operations with SSH key mounting and macOS compatibility
• Resource Limited: CPU and memory constraints to prevent system exhaustion
• Simple Management: Single service architecture with docker-compose

📋 Prerequisites

• Docker installed and running
• Docker Compose installed
• Node.js (for npm installation method)

🏁 Quick Start

Installation

Option 1: Install via npm (Recommended)

# Install globally
npm install -g @zzev/aibox

# Or use with npx (no installation needed)
npx @zzev/aibox

Option 2: Install from GitHub

npm install -g https://github.com/zzev/aibox.git

Option 3: Clone and link locally

# Clone the repository
git clone https://github.com/zzev/aibox.git
cd aibox

# Link globally
npm link

Setup

# Navigate to your project directory
cd /path/to/your/project

# On first run, aibox will automatically pull the Docker image from ghcr.io
# and guide you through interactive profile setup
aibox

# Or explicitly configure a profile
aibox -p default
aibox --setup default

Run

# Default: Interactive bash shell
aibox

# Inside the container, run any CLI:
claude --dangerously-skip-permissions
codex
gemini

# Or run directly with arguments:
aibox --dangerously-skip-permissions  # Claude Code
aibox -t codex                        # Codex
aibox -t gemini                       # Gemini

# YOLO mode (unified syntax for skipping permissions):
aibox --yolo                          # Claude with --dangerously-skip-permissions
aibox -t codex --yolo                 # Codex with --sandbox danger-full-access
aibox -t gemini --yolo                # Gemini with --yolo

🎯 Usage

Basic Commands

# Interactive shell (default)
aibox

# Run specific CLI directly
aibox --dangerously-skip-permissions  # Claude Code
aibox -t codex                        # Codex (executes directly)
aibox -t gemini                       # Gemini (executes directly)

# YOLO mode (skip all permissions)
aibox --yolo                          # Claude with --dangerously-skip-permissions
aibox -t codex --yolo                 # Codex with --sandbox danger-full-access
aibox -t gemini --yolo                # Gemini with --yolo
aibox --yolo file.py                  # YOLO mode with additional arguments

# With additional arguments
aibox -t codex help
aibox -t gemini chat "Hello"

# Clean orphan containers
aibox --clean

# Check for Docker image updates
aibox --update
aibox -a work --update

# Attach to running container
aibox --attach

# Use specific account
aibox -a work

# Remove container after exit
aibox -r

Profile Management

Configure or reconfigure profiles interactively:

# Configure a profile (creates if new, reconfigures if exists)
aibox -p default
aibox --setup work

# The interactive setup will guide you through:
# - Git author name and email
# - Preferred AI CLI (claude/codex/gemini)
# - SSH key configuration
# - GitHub CLI token (optional)

Multi-Account Setup

Profiles are stored globally in ~/.aibox/profiles/ and work across all your projects:

# Create work profile interactively
aibox -p work

# Create personal profile
aibox -p personal

# Use different profiles
aibox -a work -t codex
aibox -a personal -t claude --dangerously-skip-permissions

# Reconfigure an existing profile
aibox -p work  # Will show current values as defaults

How Multi-Account Works:

Each profile uses separate configuration directories for Claude Code and Codex:

| CLI | Default Account | Other Accounts | Multi-Account Support | |-----|----------------|----------------|---------------------| | Claude Code | ~/.claude | ~/.claude-{account} | ✅ Yes (via CLAUDE_CONFIG_DIR) | | Codex | ~/.codex | ~/.codex-{account} | ✅ Yes (via CODEX_HOME) | | Gemini | ~/.gemini | ~/.gemini (shared) | ❌ No (hardcoded path) |

Important Notes:

• Claude Code: Uses CLAUDE_CONFIG_DIR environment variable (undocumented feature, some known issues)
• Codex: Uses CODEX_HOME environment variable (fully supported)
• Gemini: Does not support custom config directories - all accounts share ~/.gemini

To use multiple Gemini accounts, you would need to manually switch configurations by logging out/in.

⚙️ Configuration

aibox Profiles (~/.aibox/profiles/)

Profiles are stored globally in ~/.aibox/profiles/ and contain your personal settings (git config, SSH keys, Docker image, etc.)

Project Environment - Optional

Project-specific environment variables are optional. If your project has them, aibox will automatically detect and load them.

🔒 Security Features

• Non-root execution: Runs as ai user (UID 1001)
• Capability dropping: Minimal Linux capabilities
• No privilege escalation: no-new-privileges security option
• Read-only mounts: SSH keys and configs mounted read-only
• Network isolation: Dedicated ai-network
• Resource limits: 2 CPU cores, 4GB RAM max
• SSH config filtering: Automatic macOS → Linux compatibility

🗂️ Volume Mappings

All configurations are mapped from your host for instant persistence:

| Host Path | Container Path | Purpose | |-----------|---------------|---------| | ~/.claude or ~/.claude-{account} | /home/ai/.claude | Claude Code config (account-specific) | | ~/.codex or ~/.codex-{account} | /home/ai/.codex | Codex config (account-specific) | | ~/.gemini | /home/ai/.gemini | Gemini config (shared across accounts) | | ~/.ssh | /home/ai/.ssh | SSH keys (read-only) | | ~/.gitignore_global | /home/ai/.gitignore_global | Global gitignore | | ~/.config/ccstatusline | /home/ai/.config/ccstatusline | ccstatusline config | | ./ | /home/ai/code | Project directory |

🐳 Container Naming

Containers are named: aibox-{AI_ACCOUNT}

Examples:

• aibox-default
• aibox-work
• aibox-personal

The same container is reused for all CLI types (Claude, Codex, Gemini), making it more efficient.

📖 Documentation

For comprehensive documentation, see DOCKER.md which includes:

• Detailed usage examples
• Troubleshooting guide
• Advanced configuration
• SSH key setup
• Git integration
• Best practices

🛠️ Common Operations

Managing Containers

# List all aibox containers
docker ps -a --filter "name=aibox"

# Stop specific container
docker stop aibox-default

# Remove specific container
docker rm aibox-default

# Clean all stopped containers
aibox --clean

Viewing Logs

# View container logs
docker logs aibox-default
docker logs aibox-work

# Follow logs
docker logs -f aibox-personal

🔧 Troubleshooting

Container won't start

# Clean orphaned containers
aibox --clean

# Remove the container and let it be recreated
docker rm -f aibox-default
aibox

SSH/Git issues

# Verify SSH keys exist
ls -la ~/.ssh

# Enter container and test
aibox
ssh -T [email protected]

Permission errors

# Container runs as ai:ai (1001:1001)
# Ensure host directories are accessible
ls -la ~/.claude ~/.codex ~/.gemini

🆚 aibox vs devcontainers

While both use Docker for isolated development, they serve different purposes:

| Feature | aibox | devcontainers | |---------|-------|---------------| | Purpose | Run AI CLIs securely with multi-account support | Full development environment in container | | Setup | Single global installation via npm | Per-project .devcontainer configuration | | Usage | CLI-first: aibox command from any project | IDE-integrated: requires VS Code/supported editor | | Configuration | Reusable across all projects | Project-specific configuration | | AI Account Management | Native multi-account support | Manual configuration per project | | Config Persistence | Direct host mapping (~/.claude, etc.) | Volumes or per-project setup | | Complexity | Minimal: one command to start | Higher: JSON config, IDE integration | | Best for | Quick AI CLI access, multiple AI accounts, JS projects | Full-stack development, polyglot projects, team standardization |

Use aibox when: You want instant AI CLI access across projects without per-project configuration.

Use devcontainers when: You need a fully customized development environment with IDE integration.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

This project is provided as-is for use with AI CLIs. Ensure compliance with the respective terms of service:

• Anthropic Terms of Service (Claude Code)
• OpenAI Terms of Use (Codex)
• Google Terms of Service (Gemini)

⚠️ Disclaimer

This Docker environment is designed for development and testing purposes. The --dangerously-skip-permissions flag for Claude Code should only be used in isolated environments like this Docker container.

🙏 Acknowledgments

• Built for secure execution of AI command-line tools
• Inspired by best practices in Docker security and isolation
• Designed for developers who work with multiple AI CLIs

Need help? Check out the detailed documentation or open an issue.