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.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
bin		bin
scripts		scripts
src		src
.aibox-profile.example.toml		.aibox-profile.example.toml
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

License

zzev/aibox

Folders and files

Latest commit

History

Repository files navigation