Commands

Default workflow

yolobox is built around AI shortcut commands:

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

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

If you use one tool most of the time, set default_harness = "codex" or another shortcut name in config. Then bare yolobox launches that tool. Set default_harness = "none" or leave it unset to keep bare yolobox as an interactive shell.

Command reference

AI shortcuts

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

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

ACP clients

The base image includes Codex and Claude adapters for Agent Client Protocol clients and editors. Set the client's stdio agent command to yolobox, with arguments for one of these launches:

yolobox run codex-acp
yolobox run claude-agent-acp

Launch from the project directory. The ACP client pipes protocol messages into stdin and reads responses from stdout; diagnostic output stays on stderr. These commands serve ACP sessions rather than opening an interactive agent prompt.

Image pulls and custom-image builds also send their progress to stderr and leave stdin untouched. This keeps the protocol stream clean when using --ensure-latest, --packages, or a .yolobox.Dockerfile. Keep stderr separate from stdout in the client's launch configuration.

Reuse the login stored in the persistent box, or opt into host config and login sync with the existing options:

yolobox run --codex-config codex-acp
yolobox run --claude-config claude-agent-acp
yolobox run --claude-config --no-claude-auth claude-agent-acp

--no-claude-auth syncs Claude settings while preserving the box's independent login. API keys follow the usual environment passthrough settings; use --env or --env-from-host for variables that are not automatically forwarded.

The adapters bundle compatible engines and bypass the interactive CLI wrappers. Their engine versions may differ from yolobox codex or yolobox claude. Select permissions in the ACP client; --no-yolo and NO_YOLO do not control adapter permissions.

General commands

yolobox                     # Run configured default harness, or shell if none
yolobox shell               # 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 upgrade --check     # Show latest release notes without upgrading
yolobox update-agents       # Update AI CLIs and ACP adapters in persistent home
yolobox update-agents codex # Update Codex and its ACP adapter; accepts multiple targets
yolobox reset --force       # Remove yolobox named volumes (all architectures)
yolobox uninstall --force   # Remove yolobox volumes, global config/cache, and binary
yolobox completion bash     # Print a bash completion script (also: zsh)
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

Start an agent that can open host browser URLs

yolobox codex --open-bridge

Start an agent with RTK compression

yolobox codex --rtk

Set a project-specific environment variable

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

Run one command in isolation

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

Name the runtime container

yolobox run --name yolobox-dev sleep 60

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

Trace startup timing

YOLOBOX_TIMING=1 yolobox run true

Inspect the latest release before upgrading

yolobox upgrade --check

The check prints the current version, latest version, and a short summary from the release notes without downloading a binary or pulling the image.

Update bundled AI CLIs

yolobox update-agents
yolobox update-agents claude codex
yolobox update-agents kimi
yolobox update-agents antigravity

update-agents runs inside the persistent yolobox home volume and refreshes Claude Code, Codex, Gemini, Kimi Code, Antigravity, OpenCode, Copilot, and Pi. It uses global/default runtime settings, ignores .yolobox.toml, skips the project mount, and rejects --scratch, because updates made in scratch mode would disappear when the container exits.

The image bundles OpenCode v2 (@opencode/cli). yolobox update-agents opencode also installs v2, removing the old opencode-ai package from the persistent npm prefix first to avoid a launcher conflict. Installs explicitly allow the required postinstall script. Existing user-installed v1 copies remain in place until you update them; pulling a new image alone does not replace persistent tools.

OpenCode v2 keeps the opencode command and existing config locations. Back up your setup before switching: v1 plugins and server API integrations need migration. See the upstream migration guide.

The claude target also updates claude-agent-acp, and the codex target also updates codex-acp. Updating all agents includes both adapters. Use the existing claude and codex targets; adapter command names are not separate update targets.

Reset persistent state

yolobox reset --force
yolobox reset --force --platform linux/amd64

Without --platform, reset removes the yolobox volumes for every architecture. With --platform, it removes only the volumes that runs with that same --platform value use — for example the -amd64-suffixed volumes of x86-emulated sessions, leaving native volumes untouched.

Reset supports Docker, Podman, and Apple container using the configured runtime. It lists existing volumes first, leaves unrelated volumes alone, and succeeds without deleting anything when no matching volumes exist. --force confirms the yolobox reset. Apple container rejects volumes still in use; stop and remove containers using those volumes before retrying. Docker and Podman retain their runtime-specific force-deletion behavior. Listing or deletion failures return a nonzero exit status.

Uninstall

yolobox uninstall --force
yolobox uninstall --force --keep-volumes

Uninstall uses the same volume cleanup as reset, then removes the global config, update cache, and running yolobox binary. It resolves the configured runtime before removing config. If volume listing or deletion fails, uninstall returns an error and keeps the config and binary so you can retry. --keep-volumes skips runtime access and preserves all volumes while removing the local installation.

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 yolobox shell when you are debugging or exploring manually, not as the main path.