aiBox

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║             █████╗ ██╗  ██████╗  █████╗  ██╗  ██╗             ║
║            ██╔══██╗██║  ██╔══██╗██╔══██╗░╚██╗██╔╝             ║
║            ███████║██║  ██████╔╝██║░░██║░░╚███╔╝░             ║
║            ██╔══██║██║  ██╔══██╗██║░░██║░░██╔██╗░             ║
║            ██║░░██║██║  ██████╔╝╚█████╔╝ ██╔╝╚██╗             ║
║            ╚═╝░░╚═╝╚═╝  ╚═════╝░░╚════╝░ ╚═╝░░╚═╝             ║
║                                                               ║
║       Container-Based Multi-AI Development Environment        ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Container-Based Multi-AI Development Environment

Multi-AI development environment with Python-based tooling, comprehensive testing, and beautiful CLI.

Documentation | Configuration | Architecture | Agents Guide

Features

• 🤖 Multi-AI Support - Claude, Gemini, and OpenAI Codex
• 🐳 Docker-Based - Isolated, reproducible development environments
• 🔧 Profiles - Python, Node.js, Rust, Go, plus utility profiles (sudo, git)
• 🚀 Beautiful CLI - Rich terminal output with progress indicators and tables
• 🔌 Parallel Slots - Run multiple AI containers simultaneously
• ♻️ Shared Base Images - Reuse profile layers across providers; only provider CLIs rebuild
• 📦 Profile System - Declarative YAML-based language/tool configurations
• ⚙️ Type-Safe Config - Pydantic validation with helpful error messages
• 🔄 Session Continuation - Reuse the same slot container by default; optional one-off mode with --auto-delete

Quick Start

# Install aibox
pip install aibox-cli
# or with uv (recommended)
uv pip install aibox-cli

# Navigate to your project
cd my-project

# Initialize the project (select profiles and versions)
aibox init

# Start AI development environment (interactive slot/provider wizard)
aibox start

New to aibox? See the Getting Started Guide for detailed instructions.

Installation

Prerequisites

• Docker - Running and accessible (Install Docker)
• Python 3.11+ - For the CLI tool (Download Python)
• Authentication:
  • Claude: OAuth authentication (authenticates in browser on first use)
  • Gemini & OpenAi: aibox launches a short-lived login container during slot creation to capture an OAuth session

Install via pip

# Recommended: use uv
uv pip install aibox-cli

# Or use pip
pip install aibox-cli

# Verify installation
aibox --version

Install from Source

git clone https://github.com/fogXploit/aibox.git
cd aibox
uv pip install -e ".[dev]"

See Getting Started for detailed installation instructions.

Shell Autocomplete

aibox supports shell autocomplete for Bash, Zsh, Fish, and PowerShell. Once enabled, you can press TAB to autocomplete.

Install Autocomplete

# Install completion for your shell
aibox --install-completion

# Restart your terminal
# Then try it out:
aibox profile info <TAB>        # Shows: go nodejs python rust python:3.11 ...
aibox start --slot <TAB>         # Shows configured slot numbers

Supported Shells

• Bash - Automatically detected and configured
• Zsh - Automatically detected and configured
• Fish - Automatically detected and configured
• PowerShell - Automatically detected and configured

Note: If autocomplete doesn't work after installation, ensure you've restarted your terminal or sourced your shell configuration file (e.g., source ~/.bashrc or source ~/.zshrc).

Usage

Essential Commands

# Initialize project and select profiles
aibox init

# Start AI environment (interactive provider + slot wizard)
aibox start

# Reuse a specific slot (preserves container state)
aibox start --slot 2

# One-off session (stop and remove container on exit)
aibox start --auto-delete

# Slots
aibox slot list
aibox slot add          # pick slot + provider by number
aibox slot cleanup      # remove stopped slot containers and slot configs

# Profiles
aibox profile list
aibox profile info python

# Config
aibox config show
aibox config validate
aibox config edit

# Status
aibox status

See Getting Started for workflow examples.

Session Continuation & Reuse

• aibox reuses the same container for a slot by default. Start again with the same --slot to keep your tools and filesystem state.
• When you exit the AI CLI, the container is stopped but preserved. Use --auto-delete for a one-off session (container is removed when the CLI exits).
• Provider notes:
  • Claude and Gemini persist auth/state via their mounted config directories (!TODO)
  • OpenAI Codex: container reuse preserves CLI config. To continue a Codex conversation, start with aibox start --slot <n> --resume to launch codex resume (slot must already have a Codex session); omit --resume to start a fresh Codex session in that slot.

Profiles

Built-in profiles:

• python:3.11|3.12|3.13 - Python with uv package manager
• nodejs:20 - Node.js with npm global configured
• go:1.21|1.22|1.23 - Go with modules
• rust:stable|beta|nightly|1.75|1.76|1.77 - Rust with cargo/rustfmt/clippy
• sudo:1 - Passwordless sudo for the aibox user
• git:latest - Git client

Profile definitions live in aibox/profiles/definitions/*.yml; customize or add your own as needed. TODO: More will be added

Documentation

• Getting Started - Installation and first project guide
• Configuration Reference - Complete YAML configuration docs
• Architecture - Technical architecture details
• CONTRIBUTING - Development and contribution guide

Development

Setup

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

# Install with dev dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# All tests
pytest

# Unit tests only
pytest tests/unit

# With coverage
pytest --cov=aibox --cov-report=html

Code Quality

# Lint and format
ruff check aibox/
ruff format aibox/

# Type checking
mypy aibox/

# Run all checks
pre-commit run --all-files

Architecture

aibox/
├── cli/              # CLI commands (Typer)
├── providers/        # AI provider implementations
├── containers/       # Docker management (Docker SDK)
├── profiles/         # Profile system (YAML-based)
├── config/           # Configuration (Pydantic models)
└── utils/            # Utilities (logging, errors)

See ARCHITECTURE.md for details.

Roadmap

v0.1

• ✅ Claude CLI support
• ✅ Gemini CLI support
• ✅ OpenAI CLI support
• ✅ 4+ language profiles
• ✅ Slot system (parallel containers)
• ✅ YAML configuration
• ✅ Beautiful CLI with Rich

v0.2

• ✅ Additional profiles
• ✅ AI provider integrations enhanced
• ✅ user friendly login workflow for Gemini
• ✅ status overview added

v0.3 (Current)

• ✅ persistence & one-time container support
• ✅ cleanup workflows
• ✅ login helper for codex
• ✅ codex-cli resume support

v0.4+

• TODO

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Adding a New Profile

1. Create aibox/profiles/definitions/myprofile.yml
2. Add tests in tests/unit/test_profiles.py
3. Update documentation
4. Submit PR

Troubleshooting

Docker Not Found

# Install Docker Desktop
# https://docs.docker.com/get-docker/

Gemini Login Helper

# Gemini uses OAuth. When you add a Gemini slot, aibox runs a short-lived
# host-network container to execute `gemini login` so the random callback port works.
# Follow the printed URL in your browser; the session is stored under the slot's .gemini/ directory.

OpenAI Login Helper

# OpenAI Codex also uses OAuth. aibox now runs a short-lived host-network container
# to execute `codex login` when a slot needs authentication, so the main container
# doesn't keep a lingering 1455 port binding. The session is stored under the slot's
# .codex/ directory.

Authentication Issues (Claude/OpenAI)

# Claude and OpenAI use OAuth - no API keys needed
# If authentication fails:
# 1. Ensure Docker ports are accessible (54545 for Claude, 1455 for Codex)
# 2. Check your browser isn't blocking popups
# 3. Try running the CLI inside the container again - it will re-prompt

Permission Denied

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with Typer, Rich, and Docker SDK
• Thanks to all contributors

Links

• Documentation: https://github.com/fogXploit/aibox/tree/main/docs
• PyPI: https://pypi.org/project/aibox-cli/
• GitHub: https://github.com/fogXploit/aibox
• Issues: https://github.com/fogXploit/aibox/issues
• Discussions: https://github.com/fogXploit/aibox/discussions

Built with ❤️ for AI-powered development