PkgFoundry
Catalog PyPI
Back to packageRELEASE DETAILS

0.3.3

PyPI

aibox-cli

Container-Based Multi-AI Development Environment

aiclaudecontainersdevelopmentdockergeminiopenai
Published17 Mar 2026
Direct dependencies15
Transitive dependenciesNot calculated

README

Version 0.3.3 documentation

aiBox

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

Container-Based Multi-AI Development Environment

Tests Python 3.11+ License: MIT

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

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

Links

Built with ❤️ for AI-powered development

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 15

Native requirements
15 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
docker
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
docker>=7.0.0runtime
httpx
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
httpx>=0.27.0runtime
pydantic
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pydantic>=2.6.0runtime
pyyaml
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pyyaml>=6.0.1runtime
questionary
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
questionary>=2.0.0runtime
rich
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
rich>=13.7.0runtime
typer
Environment
{
  "extras": "",
  "marker": null,
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
typer>=0.12.0runtime
mypy
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
mypy>=1.8.0; extra == "dev"runtime
pre-commit
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pre-commit>=3.6.0; extra == "dev"runtime
pytest-cov
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pytest-cov>=4.1.0; extra == "dev"runtime
pytest-docker
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pytest-docker>=3.1.0; extra == "dev"runtime
pytest-mock
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pytest-mock>=3.12.0; extra == "dev"runtime
pytest
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
pytest>=8.0.0; extra == "dev"runtime
ruff
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
ruff>=0.2.0; extra == "dev"runtime
types-pyyaml
Environment
{
  "extras": "",
  "marker": "extra == \"dev\"",
  "requires_python": ">=3.11",
  "evaluation": "NOT_EVALUATED"
}
types-pyyaml>=6.0.0; extra == "dev"runtime

Distribution files

2 collected
aibox_cli-0.3.3-py3-none-any.whl

bdist_wheel · 70.45 KB · Python py3

Source file
aibox_cli-0.3.3.tar.gz

sdist · 102.44 KB · Python source

Source file

Repository

PENDING
fogxploit/aibox

Shared repository data · GitHub

License detected in repository
Not collected

Metadata history

Meaningful changes
Current collected state Current

Observed since 21 Oct, 10:03 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:aa5c19cb4991655139337155efaa296ae48d9881d1fb409e8beab62dbb7414ed

Other collected versions

View all collected versions →