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, kimi, agy, opencode, copilot, or pi 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.

Shell completions

Homebrew installs bash and zsh completions automatically. With bash, they need Homebrew's bash-completion@2 loaded; with zsh, Homebrew's site-functions directory must be on fpath before compinit.

For script or source installs, load them from your shell profile:

# bash (~/.bashrc)
eval "$(yolobox completion bash)"

# zsh (~/.zshrc, after compinit)
source <(yolobox completion zsh)

Or install the zsh script into a directory on your fpath:

yolobox completion zsh > "${fpath[1]}/_yolobox"

Completions cover subcommands, AI shortcuts, every yolobox flag, --runtime and --platform values, update-agents targets, and the command after yolobox run.

First run

Start from any project:

cd /path/to/your/project
yolobox claude

Other common entry points:

yolobox codex
yolobox gemini
yolobox kimi
yolobox agy
yolobox copilot
yolobox pi
yolobox run make test
yolobox shell

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

You can also set a default harness in config, such as default_harness = "codex", so bare yolobox launches that AI shortcut. Set it to none or leave it unset to keep bare yolobox as the shell shortcut.

Runtime support

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

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

Force a runtime explicitly:

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

Boxes using the same runtime and architecture share persistent home, cache, and output volumes. Rootless Podman uses shared SELinux labels (:z,U) so starting another box preserves the running boxes' access to those volumes. Use --scratch for a run without shared persistent state.

Next pages

• Commands: shortcut commands, shell usage, and maintenance commands
• Recipes: named agent environments, Git remote synchronization, and webapp routing
• 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