{"id":31558032,"url":"https://github.com/zzev/aibox","last_synced_at":"2026-02-05T22:05:14.778Z","repository":{"id":317658544,"uuid":"1067315911","full_name":"zzev/aibox","owner":"zzev","description":"🐳 Secure Docker sandbox for Claude Code, Codex \u0026 Gemini CLI • Multi-account • Persistent configs • SSH/Git integrated • macOS optimized","archived":false,"fork":false,"pushed_at":"2025-10-30T08:33:06.000Z","size":135,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T13:41:54.668Z","etag":null,"topics":["ai-tools","anthropic","claude-code","codex","development-environment","devtools","docker","docker-compose","gemini","git-integration","google","isolation","linux","macos","multi-account","openai","productivity","ssh"],"latest_commit_sha":null,"homepage":"https://aibox.sh","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zzev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T17:22:20.000Z","updated_at":"2025-10-30T08:33:07.000Z","dependencies_parsed_at":"2025-10-02T09:19:53.767Z","dependency_job_id":"8f649ba5-a410-42aa-a8c7-27a9d734a13f","html_url":"https://github.com/zzev/aibox","commit_stats":null,"previous_names":["zzev/aibox"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/zzev/aibox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzev%2Faibox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzev%2Faibox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzev%2Faibox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzev%2Faibox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zzev","download_url":"https://codeload.github.com/zzev/aibox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzev%2Faibox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29135963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T21:59:57.939Z","status":"ssl_error","status_checked_at":"2026-02-05T21:59:57.628Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","anthropic","claude-code","codex","development-environment","devtools","docker","docker-compose","gemini","git-integration","google","isolation","linux","macos","multi-account","openai","productivity","ssh"],"created_at":"2025-10-05T00:11:52.120Z","updated_at":"2026-02-05T22:05:14.765Z","avatar_url":"https://github.com/zzev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aibox\n\nA secure, isolated Docker environment for running multiple AI command-line tools (Claude Code, Codex, and Gemini) with multi-account support and comprehensive security features.\n\n**Optimized for Node.js/JavaScript projects** - Built on Node.js 20 Alpine, includes npm, and common development tools for modern JavaScript/TypeScript development.\n\n## 🚀 Features\n\n- **Multi-CLI Support**: Run Claude Code, Codex, or Gemini CLI from a single unified container\n- **Security First**: Non-root user execution, capability dropping, and filesystem isolation\n- **Multi-Account**: Manage separate configurations for work, personal, or client projects\n- **Persistent Configs**: Direct host mapping of `~/.claude`, `~/.codex`, and `~/.gemini`\n- **Interactive by Default**: Opens bash shell by default - run any CLI manually or pass args to execute directly\n- **Git Integration**: Seamless git operations with SSH key mounting and macOS compatibility\n- **Resource Limited**: CPU and memory constraints to prevent system exhaustion\n- **Simple Management**: Single service architecture with docker-compose\n\n## 📋 Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/) installed and running\n- [Docker Compose](https://docs.docker.com/compose/install/) installed\n- [Node.js](https://nodejs.org/) (for npm installation method)\n\n## 🏁 Quick Start\n\n### Installation\n\n**Option 1: Install via npm (Recommended)**\n\n```bash\n# Install globally\nnpm install -g @zzev/aibox\n\n# Or use with npx (no installation needed)\nnpx @zzev/aibox\n```\n\n**Option 2: Install from GitHub**\n\n```bash\nnpm install -g https://github.com/zzev/aibox.git\n```\n\n**Option 3: Clone and link locally**\n\n```bash\n# Clone the repository\ngit clone https://github.com/zzev/aibox.git\ncd aibox\n\n# Link globally\nnpm link\n```\n\n### Setup\n\n```bash\n# Navigate to your project directory\ncd /path/to/your/project\n\n# On first run, aibox will automatically pull the Docker image from ghcr.io\n# and guide you through interactive profile setup\naibox\n\n# Or explicitly configure a profile\naibox -p default\naibox --setup default\n```\n\n### Run\n\n```bash\n# Default: Interactive bash shell\naibox\n\n# Inside the container, run any CLI:\nclaude --dangerously-skip-permissions\ncodex\ngemini\n\n# Or run directly with arguments:\naibox --dangerously-skip-permissions  # Claude Code\naibox -t codex                        # Codex\naibox -t gemini                       # Gemini\n\n# YOLO mode (unified syntax for skipping permissions):\naibox --yolo                          # Claude with --dangerously-skip-permissions\naibox -t codex --yolo                 # Codex with --sandbox danger-full-access\naibox -t gemini --yolo                # Gemini with --yolo\n```\n\n## 🎯 Usage\n\n### Basic Commands\n\n```bash\n# Interactive shell (default)\naibox\n\n# Run specific CLI directly\naibox --dangerously-skip-permissions  # Claude Code\naibox -t codex                        # Codex (executes directly)\naibox -t gemini                       # Gemini (executes directly)\n\n# YOLO mode (skip all permissions)\naibox --yolo                          # Claude with --dangerously-skip-permissions\naibox -t codex --yolo                 # Codex with --sandbox danger-full-access\naibox -t gemini --yolo                # Gemini with --yolo\naibox --yolo file.py                  # YOLO mode with additional arguments\n\n# With additional arguments\naibox -t codex help\naibox -t gemini chat \"Hello\"\n\n# Clean orphan containers\naibox --clean\n\n# Check for Docker image updates\naibox --update\naibox -a work --update\n\n# Attach to running container\naibox --attach\n\n# Use specific account\naibox -a work\n\n# Remove container after exit\naibox -r\n```\n\n### Profile Management\n\nConfigure or reconfigure profiles interactively:\n\n```bash\n# Configure a profile (creates if new, reconfigures if exists)\naibox -p default\naibox --setup work\n\n# The interactive setup will guide you through:\n# - Git author name and email\n# - Preferred AI CLI (claude/codex/gemini)\n# - SSH key configuration\n# - GitHub CLI token (optional)\n```\n\n### Multi-Account Setup\n\nProfiles are stored globally in `~/.aibox/profiles/` and work across all your projects:\n\n```bash\n# Create work profile interactively\naibox -p work\n\n# Create personal profile\naibox -p personal\n\n# Use different profiles\naibox -a work -t codex\naibox -a personal -t claude --dangerously-skip-permissions\n\n# Reconfigure an existing profile\naibox -p work  # Will show current values as defaults\n```\n\n**How Multi-Account Works:**\n\nEach profile uses separate configuration directories for Claude Code and Codex:\n\n| CLI | Default Account | Other Accounts | Multi-Account Support |\n|-----|----------------|----------------|---------------------|\n| **Claude Code** | `~/.claude` | `~/.claude-{account}` | ✅ Yes (via `CLAUDE_CONFIG_DIR`) |\n| **Codex** | `~/.codex` | `~/.codex-{account}` | ✅ Yes (via `CODEX_HOME`) |\n| **Gemini** | `~/.gemini` | `~/.gemini` (shared) | ❌ No (hardcoded path) |\n\n**Important Notes:**\n- **Claude Code**: Uses `CLAUDE_CONFIG_DIR` environment variable (undocumented feature, some known issues)\n- **Codex**: Uses `CODEX_HOME` environment variable (fully supported)\n- **Gemini**: Does not support custom config directories - all accounts share `~/.gemini`\n\nTo use multiple Gemini accounts, you would need to manually switch configurations by logging out/in.\n\n## ⚙️ Configuration\n\n### aibox Profiles (`~/.aibox/profiles/`)\n\nProfiles are stored globally in `~/.aibox/profiles/` and contain your personal settings (git config, SSH keys, Docker image, etc.)\n\n### Project Environment - Optional\n\nProject-specific environment variables are **optional**. If your project has them, aibox will automatically detect and load them.\n\n## 🔒 Security Features\n\n- **Non-root execution**: Runs as `ai` user (UID 1001)\n- **Capability dropping**: Minimal Linux capabilities\n- **No privilege escalation**: `no-new-privileges` security option\n- **Read-only mounts**: SSH keys and configs mounted read-only\n- **Network isolation**: Dedicated `ai-network`\n- **Resource limits**: 2 CPU cores, 4GB RAM max\n- **SSH config filtering**: Automatic macOS → Linux compatibility\n\n## 🗂️ Volume Mappings\n\nAll configurations are mapped from your host for instant persistence:\n\n| Host Path | Container Path | Purpose |\n|-----------|---------------|---------|\n| `~/.claude` or `~/.claude-{account}` | `/home/ai/.claude` | Claude Code config (account-specific) |\n| `~/.codex` or `~/.codex-{account}` | `/home/ai/.codex` | Codex config (account-specific) |\n| `~/.gemini` | `/home/ai/.gemini` | Gemini config (shared across accounts) |\n| `~/.ssh` | `/home/ai/.ssh` | SSH keys (read-only) |\n| `~/.gitignore_global` | `/home/ai/.gitignore_global` | Global gitignore |\n| `~/.config/ccstatusline` | `/home/ai/.config/ccstatusline` | ccstatusline config |\n| `./` | `/home/ai/code` | Project directory |\n\n## 🐳 Container Naming\n\nContainers are named: `aibox-{AI_ACCOUNT}`\n\nExamples:\n- `aibox-default`\n- `aibox-work`\n- `aibox-personal`\n\nThe same container is reused for all CLI types (Claude, Codex, Gemini), making it more efficient.\n\n## 📖 Documentation\n\nFor comprehensive documentation, see [DOCKER.md](./DOCKER.md) which includes:\n\n- Detailed usage examples\n- Troubleshooting guide\n- Advanced configuration\n- SSH key setup\n- Git integration\n- Best practices\n\n## 🛠️ Common Operations\n\n### Managing Containers\n\n```bash\n# List all aibox containers\ndocker ps -a --filter \"name=aibox\"\n\n# Stop specific container\ndocker stop aibox-default\n\n# Remove specific container\ndocker rm aibox-default\n\n# Clean all stopped containers\naibox --clean\n```\n\n### Viewing Logs\n\n```bash\n# View container logs\ndocker logs aibox-default\ndocker logs aibox-work\n\n# Follow logs\ndocker logs -f aibox-personal\n```\n\n## 🔧 Troubleshooting\n\n### Container won't start\n\n```bash\n# Clean orphaned containers\naibox --clean\n\n# Remove the container and let it be recreated\ndocker rm -f aibox-default\naibox\n```\n\n### SSH/Git issues\n\n```bash\n# Verify SSH keys exist\nls -la ~/.ssh\n\n# Enter container and test\naibox\nssh -T git@github.com\n```\n\n### Permission errors\n\n```bash\n# Container runs as ai:ai (1001:1001)\n# Ensure host directories are accessible\nls -la ~/.claude ~/.codex ~/.gemini\n```\n\n## 🆚 aibox vs devcontainers\n\nWhile both use Docker for isolated development, they serve different purposes:\n\n| Feature | aibox | devcontainers |\n|---------|-------|---------------|\n| **Purpose** | Run AI CLIs securely with multi-account support | Full development environment in container |\n| **Setup** | Single global installation via npm | Per-project `.devcontainer` configuration |\n| **Usage** | CLI-first: `aibox` command from any project | IDE-integrated: requires VS Code/supported editor |\n| **Configuration** | Reusable across all projects | Project-specific configuration |\n| **AI Account Management** | Native multi-account support | Manual configuration per project |\n| **Config Persistence** | Direct host mapping (`~/.claude`, etc.) | Volumes or per-project setup |\n| **Complexity** | Minimal: one command to start | Higher: JSON config, IDE integration |\n| **Best for** | Quick AI CLI access, multiple AI accounts, JS projects | Full-stack development, polyglot projects, team standardization |\n\n**Use aibox when**: You want instant AI CLI access across projects without per-project configuration.\n\n**Use devcontainers when**: You need a fully customized development environment with IDE integration.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\n## 📄 License\n\nThis project is provided as-is for use with AI CLIs. Ensure compliance with the respective terms of service:\n- [Anthropic Terms of Service](https://www.anthropic.com/legal/consumer-terms) (Claude Code)\n- [OpenAI Terms of Use](https://openai.com/policies/terms-of-use) (Codex)\n- [Google Terms of Service](https://policies.google.com/terms) (Gemini)\n\n## ⚠️ Disclaimer\n\nThis 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.\n\n## 🙏 Acknowledgments\n\n- Built for secure execution of AI command-line tools\n- Inspired by best practices in Docker security and isolation\n- Designed for developers who work with multiple AI CLIs\n\n---\n\n**Need help?** Check out the [detailed documentation](./DOCKER.md) or open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzev%2Faibox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzzev%2Faibox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzev%2Faibox/lists"}