Installation & Setup

What yolobox does

yolobox runs an AI coding agent inside a container where:

• your project is mounted at its real path
• the agent has full permissions and sudo inside the box
• your home directory is not mounted unless you explicitly opt in
• named volumes preserve tools and session state across runs

The default workflow is simple:

cd /path/to/your/project
yolobox claude

Use claude, codex, gemini, opencode, or copilot depending on the tool you want to run.

Install

Homebrew

brew install finbarr/tap/yolobox

Install script

curl -fsSL https://raw.githubusercontent.com/finbarr/yolobox/master/install.sh | bash

The install script downloads a release binary when one is available for your platform. If it cannot, it falls back to building from source.

First run

Start from any project:

cd /path/to/your/project
yolobox claude

Other common entry points:

yolobox codex
yolobox gemini
yolobox copilot
yolobox run make test
yolobox

Use yolobox by itself when you want a shell. Use yolobox run ... when you want one command. Use the AI shortcuts when you want the intended workflow.

Runtime support

yolobox auto-detects the first supported runtime it can use.

Platform	Supported runtimes
macOS	Docker Desktop, OrbStack, Colima, Apple container (macOS Tahoe+)
Linux	Docker, Podman

Force a runtime explicitly:

yolobox claude --runtime docker
yolobox claude --runtime podman
yolobox claude --runtime container

Next pages

• Commands: shortcut commands, shell usage, and maintenance commands
• What's in the Box: preinstalled tools and YOLO-mode wrappers
• Project-Level Customization: add packages or a Dockerfile fragment per project
• Configuration: global defaults, project config, copied instructions, and auto-forwarded env vars

Memory requirements

Claude Code needs at least 4 GB of RAM allocated to Docker. Colima defaults to 2 GB, which often leads to OOM kills.

colima stop && colima start --memory 8