yolobox

██╗   ██╗ ██████╗ ██╗      ██████╗ ██████╗  ██████╗ ██╗  ██╗
╚██╗ ██╔╝██╔═══██╗██║     ██╔═══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
 ╚████╔╝ ██║   ██║██║     ██║   ██║██████╔╝██║   ██║ ╚███╔╝
  ╚██╔╝  ██║   ██║██║     ██║   ██║██╔══██╗██║   ██║ ██╔██╗
   ██║   ╚██████╔╝███████╗╚██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
   ╚═╝    ╚═════╝ ╚══════╝ ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

Let your AI go full send. Your home directory stays home.

Docs: yolobox.dev

Changelog: CHANGELOG.md

Run Claude Code, Codex, Kimi Code, Gemini, Antigravity, OpenCode, Copilot, Pi, or any AI coding agent in "yolo mode" without nuking your home directory.

The Problem

AI coding agents are incredibly powerful when you let them run commands without asking permission. But one misinterpreted prompt and rm -rf ~ later, you're restoring from backup (yea right, as if you have backups lol).

The Solution

yolobox runs your AI agent inside a container where:

• your project directory is mounted at its real path, such as /Users/you/project
• the agent has full permissions and sudo inside the container
• your home directory is not mounted unless you explicitly opt in
• persistent volumes keep tools, configs, and sessions across runs
• Claude, Codex, and Kimi Code get built-in yolobox guidance so they can understand the sandbox they are running in

The AI can go absolutely wild inside the sandbox. Your actual home directory? Untouchable.

Quick Start

# Install via Homebrew
brew install finbarr/tap/yolobox

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

Homebrew installs bash and zsh completions automatically. For script installs, see shell completions.

Then from any project:

cd /path/to/your/project
yolobox claude    # Let it rip

Other AI shortcuts work the same way:

yolobox codex
yolobox gemini
yolobox kimi
yolobox agy
yolobox antigravity
yolobox opencode
yolobox copilot
yolobox pi

Set default_harness = "codex" to make bare yolobox launch Codex. Use yolobox shell when you want a manual shell, and yolobox run <cmd...> when you want one command in the sandbox.

Full install and runtime details live in Installation & Setup. Command examples live in Commands.

What's in the Box?

The base image comes with AI CLIs, Codex and Claude ACP adapters, Node.js, Python, Go, Bun, build tools, Git, GitHub CLI, ripgrep, fd, fzf, jq, vim, RTK, and the usual practical bits.

Need something else? The agent has sudo.

Inside yolobox, supported AI CLIs are wrapped to skip permission prompts. No confirmations, no guardrails. Just pure unfiltered AI, the way nature intended.

For an ACP client or editor, use yolobox run codex-acp or yolobox run claude-agent-acp as its stdio agent command. The adapters bundle compatible engines and use the client's permission modes; yolobox's CLI YOLO wrappers and --no-yolo do not control them. Existing config sync and authentication options apply. See ACP clients for launch examples.

For the full tool list, YOLO-mode wrapper table, RTK notes, npm package freshness policy, and bundled CLI upgrade behavior, see What's in the Box.

Project Customization

If one project needs extra tools or environment variables, add a small project config instead of forking the whole base image:

# .yolobox.toml
env = ["CODEX_HOME=/home/yolo/.codex-account"]

[customize]
packages = ["default-jdk", "maven"]

Then run normally:

yolobox run mvn --version

Project-level customization can also layer a Dockerfile fragment on top of the base image. The first run builds a derived image; later runs reuse it until the base image or customization inputs change.

Use container paths for env values because they are passed directly to the process inside yolobox. env values are passed to the runtime verbatim; nothing in them is interpreted.

To hand the sandbox a different value than the host uses under the same name — a read-only token instead of your real one — alias it with env_from_host (or --env-from-host KEY=HOST_VAR):

# .yolobox.toml
env_from_host = ["GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN"]

The alias owns that variable: it suppresses automatic passthrough and --gh-token for the same key, and yolobox refuses to start if the host variable is unset, so the token it replaces can never leak in by accident.

See Configuration for project env settings, and Project-Level Customization for package installs, Dockerfile fragments, rebuild behavior, upgrade behavior, and fully custom images.

Common Workflows

yolobox setup                         # Configure global defaults
yolobox config                        # Show resolved config for this project
yolobox claude --docker --gh-token    # Give the agent Docker and GitHub access
yolobox claude --claude-config --no-claude-auth # Share config, keep the box login independent
yolobox copilot --copilot-config        # Share Copilot settings, login, and session history
yolobox codex --rtk                   # Enable RTK command-output compression
yolobox run --no-network make test    # Run one command with no network
yolobox fork --name bruno codex       # Give an agent its own project copy
yolobox upgrade                       # Update binary and pull the latest image
yolobox update-agents                 # Update AI CLIs and ACP adapters in the persistent box

OpenCode installs and updates explicitly allow its required npm postinstall script.

--claude-config incrementally syncs durable Claude settings and live-mounts host ~/.claude/projects read/write so session resume history stays current. --no-claude-auth keeps the box login independent, but does not make that project-history mount read-only. --copilot-config does the same for GitHub Copilot CLI: it syncs durable ~/.copilot settings, agents, skills, and MCP config, forwards the host Copilot login as COPILOT_GITHUB_TOKEN, and live-mounts ~/.copilot/session-state read/write; add --no-copilot-auth to keep the box's Copilot login independent.

Automatic RTK setup applies the supported CLI integrations without prompting, including on first OpenCode startup, and leaves telemetry disabled unless you opt in interactively from inside the box with rtk telemetry enable.

The detailed references are intentionally in the docs site:

• Commands: shortcuts, maintenance commands, fork, and examples
• Configuration: global config, project config, copied instructions, env passthrough, and context manifests
• Flags: every flag, compatibility note, and runtime passthrough detail
• Recipes: parallel agents and webapp routing

Philosophy: It's the AI's Box, Not Yours

yolobox is designed for AI agents, not humans. You launch the AI and let it work.

The agent has sudo inside the container. If it needs a compiler, database, package, or framework, it can install one. Named volumes preserve that setup across sessions, so you do not have to turn the README into a hundred-line package matrix. Point it at your project and let it cook.

Security Model

yolobox is protection from accidents, not a magic anti-container-escape theorem.