yolobox

Every yolobox session generates a runtime manifest at /run/yolobox/context.json and sets the environment variable YOLOBOX_CONTEXT_FILE to this path.

This manifest is designed for agents or scripts running inside the container to understand their environment. It includes:

• inside_yolobox: A boolean confirmation.
• Effective configuration and container paths.
• Resolved container platform and architecture.
• The launch command.
• Fork metadata (when yolobox fork is active).
• Keys of forwarded environment variables (values are not copied for security).

Two canonical skill packages utilize this information:

1. skills/yolobox: An inside-the-box skill that uses the manifest to orient the agent to the sandbox, reporting launch modes and filesystem writability.
2. skills/yolobox-orchestrator: A host-side skill for agents that need to launch or control yolobox itself.

Every Yolobox session generates a context manifest located at /run/yolobox/context.json and exports the YOLOBOX_CONTEXT_FILE environment variable.

If an AI agent running inside the box needs to understand its environment or the current task, it should be directed to read this manifest or use the yolobox command to orient itself.

Concurrency

Each concurrent yolobox run receives its own unique manifest. However, they share persistent state unless --scratch is used. Shared state includes:

• /home/yolo
• /var/cache
• The mounted project tree

Nested Yolobox

When running yolobox inside another yolobox session, any temporary mount sources must reside under an existing host-visible bind mount (such as the project path). The inner container's /tmp directory is not visible to the outer Docker daemon.

To use project-level customization (derived images), your environment must have a runtime capable of building images. Supported runtimes include:

• Docker
• Podman

Note: Apple's container runtime can run yolobox but cannot build custom images.

These three mechanisms target different layers of the yolobox environment:

1. --ensure-latest (Per-run, image-only): Force-pulls the configured base image (default ghcr.io/finbarr/yolobox:latest) from its registry for the current run, then rebuilds any derived custom image on top. It does not update the yolobox binary.
2. --rebuild-image (Per-run, customization-only): Rebuilds only the derived custom image (created via --packages or --customize-file). It does not refresh the base image and has no effect if no customization is present.
3. yolobox upgrade (Full update): Updates the yolobox binary itself and pulls the latest base image. This is the recommended path for a complete update.

The default_harness setting allows you to launch a specific AI tool by running a bare yolobox command.

Valid values: claude, codex, gemini, kimi, agy, antigravity, opencode, copilot, pi, or none.

Setting default_harness = "none" in a project config will override a global default and keep the bare yolobox command as an interactive shell. Note that yolobox shell always opens a shell regardless of this setting.

default_harness = "codex"

You can run containers under emulation (e.g., linux/amd64 on Apple Silicon) by setting the platform key in config or using the --platform CLI flag.

Important details:

• Persistent volumes are kept per architecture. Native and emulated sessions do not share /home/yolo, /var/cache, or /output.
• Native architectures use names like yolobox-home, while emulated ones use suffixes like yolobox-home-amd64.
• Apple container runtime does not support emulation.
• Precedence for platform: --platform flag > DOCKER_DEFAULT_PLATFORM env var > native host architecture.

The fork command allows you to run multiple AI agents on the same project simultaneously without them competing for files or Docker Compose namespaces.

When you fork, yolobox creates a complete copy of the current project folder at ../.yolobox-forks/<folder>/<env>. Each fork gets its own unique COMPOSE_PROJECT_NAME, ensuring that Docker containers, networks, and volumes are namespaced by the fork name.

Workflow:

1. Create a fork: yolobox fork --name <env> <cmd...>
2. Resume a fork: yolobox fork resume <env> [cmd...]
3. Discard a fork: yolobox fork discard <env> --force (This deletes the copied folder).

# Create two parallel environments
yolobox fork --name bruno codex
yolobox fork --name diane claude

# Reopen an existing environment
yolobox fork resume bruno codex

# Delete an environment
yolobox fork discard bruno --force

yolobox uses container isolation as its primary safety boundary. When running a command, yolobox starts a container with your project directory mounted at its real path. The AI agent runs as user yolo with sudo access inside the container, but its reach is limited to what the container can see.

Trust Boundary

The container runtime is the trust boundary. yolobox protects against accidental damage, such as:

• Deleting your home directory (~).
• Reading your SSH keys or workstation credentials.
• Accessing unrelated projects on your host.

It does not protect against:

• Kernel exploits or container escape vulnerabilities.
• A deliberately hostile agent attempting to break isolation.
• The project directory itself (which is mounted read-write by default).
• Network access (unless explicitly disabled).

You can install yolobox using Homebrew or by running the official installation script.

Homebrew

brew install finbarr/tap/yolobox

Installation Script

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