Commands

Default workflow

yolobox is built around AI shortcut commands:

yolobox claude
yolobox codex
yolobox gemini
yolobox opencode
yolobox copilot

That is the intended path. You point the agent at a project and let it work inside the sandbox.

Command reference

AI shortcuts

yolobox claude
yolobox codex
yolobox gemini
yolobox opencode
yolobox copilot

These launch the matching tool inside yolobox and apply the tool-specific YOLO-mode wrapper when one exists.

General commands

yolobox                     # Open an interactive shell
yolobox run <cmd...>        # Run a single command in the sandbox
yolobox fork --name <env> <cmd...> # Run in a named copied folder with a Compose namespace
yolobox fork resume <env> [cmd...] # Reopen an existing copied folder
yolobox fork discard <env> --force # Delete a copied folder
yolobox setup               # Write global defaults to ~/.config/yolobox/config.toml
yolobox config              # Print the resolved config for the current project
yolobox upgrade             # Update the binary and pull the latest base image
yolobox reset --force       # Remove yolobox named volumes
yolobox uninstall --force   # Remove yolobox binary, image, and volumes
yolobox version             # Print version and platform
yolobox help                # Show CLI help

Common examples

Start an agent with Docker access

yolobox claude --docker --git-config --gh-token

Run one command in isolation

yolobox run --no-network --readonly-project python3 untrusted_script.py

Run parallel agents on one project

yolobox fork --name bruno codex
yolobox fork --name diane claude

Fork mode gives each agent its own complete copy of the current project folder, like another developer working on their own machine. Instead of many agents competing on one machine and one folder, you get many named agent environments, each with its own folder and Docker Compose namespace. If the folder contains a Git checkout, use your Git remote as the sync point, just like you would with teammates.

The copy lives at ../.yolobox-forks/<folder>/<env> and is mounted inside the container at the original source path. Yolobox also sets a unique COMPOSE_PROJECT_NAME, so default Docker Compose containers, networks, and named volumes are namespaced by fork.

When the fork exits, yolobox runs best-effort Compose cleanup if it finds a Compose file. The copied folder is preserved until you explicitly discard it:

yolobox fork resume bruno codex
yolobox fork discard bruno --force

See Recipes for common fork workflows, including webapp routing.

Hide secrets from the sandboxed view

yolobox claude --readonly-project --exclude ".env*" --exclude "secrets/**" --copy-as ".env.sandbox:.env"

Build with extra packages for one project

yolobox run --packages default-jdk,maven mvn --version

Inspect the resolved configuration

yolobox config

Reset persistent state

yolobox reset --force

Mental model

Use shortcut commands when you want an AI agent session.

Use run when you want one exact command in the same sandbox model.

Use fork when you want concurrent sessions on the same project folder without sharing files or the default Compose project namespace.

Use the bare yolobox shell when you are debugging or exploring manually, not as the main path.