finbarr/yolobox provides a secure, sandboxed environment for running AI coding agents, mitigating the risk of accidental system damage. It targets developers who want to leverage powerful AI assistants like Claude Code or Codex in "YOLO mode" (unrestricted command execution) without compromising their host system's integrity, particularly their home directory. The primary benefit is enabling aggressive AI-driven development workflows with a robust safety net.

How It Works

yolobox utilizes containerization (Docker or Podman) as its security boundary. It launches a container where the user's project directory is mounted at /workspace with read-write permissions. Inside the container, the AI agent has full permissions and sudo access. Crucially, the host's home directory is intentionally not mounted by default, preventing accidental rm -rf ~ scenarios. Persistent volumes ensure tools and configurations are retained across sessions, offering a balance between AI freedom and host system protection.

Quick Start & Requirements

• Install: Requires Go. Installation via curl -fsSL https://raw.githubusercontent.com/finbarr/yolobox/master/install.sh | bash or by cloning the repository and running make install.
• Prerequisites: Go, Docker or Podman. Claude Code requires 4GB+ RAM allocated to the container runtime (e.g., Docker Desktop, Colima).
• Usage: Navigate to your project directory (cd /path/to/your/project) and run yolobox.
• Runtime Support: macOS (Docker Desktop, OrbStack, Colima), Linux (Docker, Podman).

Highlighted Details

• Includes pre-configured AI CLIs (Claude Code, Gemini, Codex, Copilot) aliased for "YOLO mode" (auto-confirmation skipping).
• Base image is "batteries-included" with Node.js 22, Python 3, build tools, Git, GitHub CLI, and common utilities.
• Supports runtime configuration via CLI flags or TOML files (~/.config/yolobox/config.toml, .yolobox.toml) for image, mounts, environment variables, and network settings.
• Automatically forwards common API keys (Anthropic, OpenAI, Copilot, Gemini) into the container.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord/Slack), or roadmap were provided in the README excerpt.

Licensing & Compatibility

Licensed under the MIT License. This license generally permits commercial use and integration with closed-source projects without significant restrictions.

Limitations & Caveats

The security model relies on container isolation and does not protect against sophisticated container escape vulnerabilities or deliberate adversarial AI attempts to break out of the sandbox. For maximum security against kernel-level exploits, VM-level isolation is recommended. The project directory is mounted read-write by default, and network access is enabled unless explicitly disabled.