### Example Dockerfile Fragment

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

A sample Dockerfile fragment that switches to the root user to install SDKMAN and then switches back to the default user.

```dockerfile
USER root
RUN curl -fsSL https://get.sdkman.io | bash
USER yolo
```

--------------------------------

### Run Yolobox with Different AI Agents

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Examples of starting Yolobox with various AI agents. Choose the agent that best suits your needs.

```bash
yolobox codex
```

```bash
yolobox gemini
```

```bash
yolobox agy
```

```bash
yolobox copilot
```

```bash
yolobox pi
```

--------------------------------

### Install Yolobox using Install Script

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Use the provided curl script to install Yolobox. This method downloads a release binary or builds from source if unavailable.

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

--------------------------------

### Install Yolobox using Homebrew

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Install Yolobox via Homebrew for easy management and updates.

```bash
brew install finbarr/tap/yolobox
```

--------------------------------

### Start Agent with RTK Compression

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Launches the Codex agent with RTK compression enabled.

```bash
yolobox codex --rtk
```

--------------------------------

### Build Yolobox Docs Site

Source: https://github.com/finbarr/yolobox/blob/master/docs/contributing.md

Navigate to the docs directory, install Node.js dependencies, and build the VitePress documentation site.

```bash
cd docs
npm install
npm run docs:build
```

--------------------------------

### Start Agent with Docker Access

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Launches the Claude agent with Docker access and Git configuration, including a GitHub token.

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

--------------------------------

### Install npm Dependencies with Minimum Release Age

Source: https://github.com/finbarr/yolobox/blob/master/docs/contributing.md

Install npm dependencies, mirroring the release image build behavior by setting a minimum release age of 7 days.

```bash
npm install --min-release-age=7
```

--------------------------------

### Add System Packages via CLI

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Add system packages to the derived image directly from the command line for one-off installations. Packages are comma-separated.

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

--------------------------------

### Run Yolobox Context Helper Script

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox/SKILL.md

Execute the bundled helper script to get context about the yolobox environment. This script should be run from the skill package, not the project checkout.

```bash
`${CODEX_HOME:-$HOME/.codex}/skills/yolobox/scripts/describe-yolobox-context.sh`
```

--------------------------------

### Run Yolobox with Claude

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

This is the default workflow to start an AI coding agent. Replace 'claude' with your desired agent like 'codex', 'gemini', etc.

```bash
cd /path/to/your/project
yolobox claude
```

--------------------------------

### Customization Configuration for Packages and Dockerfile

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Defines project-level image customization, including apt packages to install and a custom Dockerfile for additional build logic.

```toml
[customize]
packages = ["default-jdk", "maven"]
dockerfile = ".yolobox.Dockerfile"

```

--------------------------------

### Start a Shell Session with Yolobox

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Launch an interactive shell within the Yolobox environment for more complex tasks.

```bash
yolobox shell
```

--------------------------------

### Add Dockerfile Fragment for Customization

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Use a Dockerfile fragment to add more complex customizations beyond just installing packages. This fragment is executed after system packages are installed.

```toml
[customize]
dockerfile = ".yolobox.Dockerfile"
```

--------------------------------

### Run Command with Project Packages

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Execute a command after installing specified project packages. Yolobox builds a derived image on the first run, which is reused for subsequent runs until base image or customization inputs change.

```bash
yolobox run mvn --version
```

--------------------------------

### Get Yolobox Context as JSON

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox/SKILL.md

Run the helper script to output the yolobox context in JSON format for programmatic access. This is useful if you need specific fields or the raw manifest.

```bash
`${CODEX_HOME:-$HOME/.codex}/skills/yolobox/scripts/describe-yolobox-context.sh --json`
```

--------------------------------

### Derived Image Customization

Source: https://github.com/finbarr/yolobox/blob/master/docs/flags.md

Customize derived images on-the-fly using `--packages` to install software and `--rebuild-image` to specify the image name, or use `--customize-file` to apply a custom Dockerfile.

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

```bash
yolobox run --customize-file .yolobox.Dockerfile bash
```

```bash
yolobox run --packages default-jdk --rebuild-image java --version
```

--------------------------------

### Add Project-Level Packages

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Specify system packages to install in your project's derived image using a TOML configuration file. This is useful for adding tools like JDK or Maven.

```toml
# .yolobox.toml
[customize]
packages = ["default-jdk", "maven"]
```

--------------------------------

### Query Yolobox Context File with jq

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox/SKILL.md

Directly query the YOLOBOX_CONTEXT_FILE using jq to extract specific information from the yolobox manifest. This assumes the file is accessible and jq is installed.

```bash
`jq . "$YOLOBOX_CONTEXT_FILE"`
```

--------------------------------

### Hide Secrets from Sandboxed View

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Starts the Claude agent with a read-only project, excluding specific files/directories, and mapping a sandbox environment variable.

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

--------------------------------

### Common Yolobox Workflow Commands

Source: https://github.com/finbarr/yolobox/blob/master/README.md

Execute common maintenance and operational commands for Yolobox. These include setup, configuration checks, agent-specific flags, and updates.

```bash
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 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 in the persistent box
```

--------------------------------

### Trace Startup Timing

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Enables detailed timing information for Yolobox startup by setting the YOLOBOX_TIMING environment variable.

```bash
YOLOBOX_TIMING=1 yolobox run true
```

--------------------------------

### Clone and Build yolobox

Source: https://github.com/finbarr/yolobox/blob/master/CONTRIBUTING.md

Clone the repository, navigate to the directory, and build the project.

```bash
git clone https://github.com/finbarr/yolobox.git
cd yolobox
make build
make test
```

--------------------------------

### Run Exact Command

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Use the `run` command when you need to execute one exact command within the same sandbox environment.

```bash
run
```

--------------------------------

### Development Commands for yolobox

Source: https://github.com/finbarr/yolobox/blob/master/CONTRIBUTING.md

Common development commands for building, testing, linting, and creating a Docker image for yolobox.

```bash
make build    # Build binary
make test     # Run tests
make lint     # Run linters
make image    # Build Docker image
```

--------------------------------

### Project File Exclusion and Substitution

Source: https://github.com/finbarr/yolobox/blob/master/docs/flags.md

Use `--exclude` to hide files/directories and `--copy-as` to substitute files within the staged readonly project view. Both require `--readonly-project` and are incompatible with `--no-project`. `--copy-as` takes precedence if both flags target the same path.

```bash
yolobox claude --readonly-project --exclude ".env*" --exclude "secrets/**"
```

```bash
yolobox claude --readonly-project --exclude ".env*" --copy-as ".env.sandbox:.env"
```

--------------------------------

### Default AI Shortcuts

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

These commands launch the matching AI tool within Yolobox. Setting a default harness in the config allows a bare 'yolobox' command to launch a specific tool.

```bash
yolobox claude
yolobox codex
yolobox gemini
yolobox agy
yolobox antigravity
yolobox opencode
yolobox copilot
yolobox pi
```

--------------------------------

### General Yolobox Commands

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Reference for general Yolobox commands, including running default harnesses, shells, commands in sandboxes, and managing fork environments.

```bash
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 all bundled AI CLIs in persistent home
yolobox update-agents codex # Update one AI CLI; accepts multiple targets
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
```

--------------------------------

### Create Parallel Agents with Forks

Source: https://github.com/finbarr/yolobox/blob/master/docs/recipes.md

Use the `yolobox fork` command to create independent agent environments for a project. Name forks descriptively, like developer environments.

```bash
yolobox fork --name bruno codex
yolobox fork --name diane claude
yolobox fork --name mike codex
```

--------------------------------

### Tag and Push a Release

Source: https://github.com/finbarr/yolobox/blob/master/docs/contributing.md

Switch to the master branch, pull the latest changes, verify the working tree is clean, tag the release, and push the tag and master branch to origin.

```bash
git switch master
git pull --ff-only origin master
git status --short --branch
git tag v0.1.2
git push origin master refs/tags/v0.1.2
```

--------------------------------

### Project-Specific Configuration Settings

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Overrides global settings for a specific project. Allows customization of default harness, mounts, environment variables, and container naming.

```toml
default_harness = "none"
mounts = ["../shared-libs:/libs:ro"]
env = ["DEBUG=1"]
readonly_project = true
container_name = "project-yolobox"
exclude = [".env*", "secrets/**"]
copy_as = [".env.sandbox:.env"]
no_network = true
no_env_passthrough = true
shm_size = "2g"

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

```

--------------------------------

### Run Command with Fresh State

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Execute a command using a fresh home and cache state by utilizing the --scratch flag. This ensures an isolated environment for the command.

```bash
yolobox run --scratch sh -lc 'pwd && whoami'
```

--------------------------------

### Setting Default AI Harness

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Specifies the default AI tool to launch when running `yolobox` without a specific tool argument. Use `none` to default to an interactive shell.

```toml
default_harness = "codex"

```

--------------------------------

### Run Tests and Linting for Pull Requests

Source: https://github.com/finbarr/yolobox/blob/master/CONTRIBUTING.md

Ensure code quality by running tests and linters before submitting a pull request.

```bash
make test
make lint
```

--------------------------------

### Rootless Podman Runtime

Source: https://github.com/finbarr/yolobox/blob/master/docs/security.md

This command configures Yolobox to use rootless Podman as its runtime. Rootless Podman maps container root to the host user, reducing the impact of runtime escapes.

```bash
yolobox claude --runtime podman
```

--------------------------------

### Resume and Discard Forked Environments

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Commands to resume a previously created fork environment or discard it forcefully.

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

--------------------------------

### Run Command with Read-Only Project Mount

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Mount the project directory as read-only and direct outputs to /output. This is useful for running commands that should not modify the project source.

```bash
yolobox run --readonly-project sh -lc 'pwd && ls /output'
```

--------------------------------

### Build Custom Yolobox Image

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Clone the Yolobox repository and build a custom Docker image using the provided Makefile. This allows for complete control over the base image.

```bash
git clone https://github.com/finbarr/yolobox.git
cd yolobox
make image IMAGE=my-yolobox:latest
```

--------------------------------

### Run Claude with Yolobox

Source: https://github.com/finbarr/yolobox/blob/master/README.md

Launch Claude AI within the Yolobox environment from your project directory. This command lets the AI operate freely within the sandbox.

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

--------------------------------

### Launch AI CLIs

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Launch various AI Command Line Interfaces (CLIs) within the yolobox. If 'default_harness' is set, a bare 'yolobox' command will launch the specified tool.

```bash
yolobox codex
yolobox claude
yolobox gemini
yolobox agy
yolobox antigravity
yolobox opencode
yolobox copilot
yolobox pi
```

--------------------------------

### Global Configuration Settings

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Sets default configurations for all Yolobox projects. This includes AI harness, git integration, network settings, and resource allocation.

```toml
default_harness = "codex"
git_config = true
opencode_config = true
pi_config = true
gh_token = true
rtk = true
ssh_agent = true
docker = true
clipboard = true
open_bridge = true
network = "my_compose_network"
# no_network = true # incompatible with network, pod, docker, clipboard, and open_bridge
no_env_passthrough = true
no_yolo = true
cpus = "4"
memory = "8g"
cap_add = ["SYS_PTRACE"]
devices = ["/dev/kvm:/dev/kvm"]
runtime_args = ["--security-opt", "seccomp=unconfined"]

```

--------------------------------

### Run a One-Shot Command

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Execute a single command within the yolobox environment. Useful for quick tasks or testing.

```bash
yolobox run echo hello
```

--------------------------------

### Yolobox Verification Standard Commands

Source: https://github.com/finbarr/yolobox/blob/master/AGENTS.md

Essential commands to run for verifying code changes, including cleaning, building, testing, linting, and checking basic yolobox functionality.

```bash
make clean && make build && make test
make lint
./yolobox version
./yolobox help
./yolobox config
```

--------------------------------

### Bridge Clipboard Copy/Paste

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Enable clipboard synchronization between the host and the yolobox. This allows for seamless copy-pasting of text.

```bash
yolobox codex --clipboard
```

--------------------------------

### Yolobox Docker Image Smoke Tests

Source: https://github.com/finbarr/yolobox/blob/master/AGENTS.md

Commands to rebuild the Docker image and run basic smoke tests to verify container functionality.

```bash
make image
./yolobox run echo hello
./yolobox run whoami
./yolobox run pwd
```

--------------------------------

### Check for Latest Release Before Upgrading

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Checks for the latest Yolobox release and displays release notes summary without performing the upgrade.

```bash
yolobox upgrade --check
```

--------------------------------

### Inspect Yolobox Configuration

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Check the effective merged configuration before making changes. This command displays the current yolobox configuration settings.

```bash
yolobox config
```

--------------------------------

### Run Other AI Agents with Yolobox

Source: https://github.com/finbarr/yolobox/blob/master/README.md

Launch various other AI coding agents like Codex, Gemini, and Copilot using Yolobox. Each command invokes a specific AI agent within the sandbox.

```bash
yolobox codex
yolobox gemini
yolobox agy
yolobox antigravity
yolobox opencode
yolobox copilot
yolobox pi
```

--------------------------------

### Run Command with Dockerfile Fragment via CLI

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Execute a command using a custom Dockerfile fragment specified via the CLI. This allows for dynamic customization without a configuration file.

```bash
yolobox run --customize-file .yolobox.Dockerfile bash
```

--------------------------------

### Run Parallel Agents in Forked Environments

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Launches multiple agents (Codex and Claude) in separate, named fork environments, each with a copy of the project.

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

--------------------------------

### Raw Runtime Argument Passthrough

Source: https://github.com/finbarr/yolobox/blob/master/docs/flags.md

Forward any unsupported flags to the underlying Docker or Podman runtime using `--runtime-arg`. These arguments are passed unchanged. Apple's `container` runtime may ignore unrecognized options.

```bash
yolobox run \
  --runtime-arg "--ulimit" \
  --runtime-arg "nofile=4096:8192" \
  --runtime-arg "--security-opt" \
  --runtime-arg "seccomp=unconfined" \
  claude
```

--------------------------------

### Runtime Arguments Format

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Specifies runtime arguments for the container. Each argument is a separate entry, including flags and their values.

```toml
runtime_args = ["--security-opt", "seccomp=unconfined"]

```

--------------------------------

### Run Command with Named Container

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Executes a command in the sandbox and assigns a specific name to the runtime container.

```bash
yolobox run --name yolobox-dev sleep 60
```

--------------------------------

### Run a Specific Command with Yolobox

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Execute a single command within the Yolobox environment, such as running tests.

```bash
yolobox run make test
```

--------------------------------

### Project File Filtering Configuration

Source: https://github.com/finbarr/yolobox/blob/master/docs/configuration.md

Configures which files to exclude from or copy into the project container. Requires `readonly_project = true` and is incompatible with `no_project = true`.

```toml
exclude = [".env*", "secrets/**"]
copy_as = [".env.sandbox:.env"]

```

--------------------------------

### Force Yolobox Runtime

Source: https://github.com/finbarr/yolobox/blob/master/docs/getting-started.md

Explicitly specify the container runtime (e.g., docker, podman) to use with Yolobox.

```bash
yolobox claude --runtime docker
```

```bash
yolobox claude --runtime podman
```

```bash
yolobox claude --runtime container
```

--------------------------------

### Fork Concurrent Sessions

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Use the `fork` command when you require concurrent sessions on the same project folder, ensuring isolation of files and the default Compose project namespace.

```bash
fork
```

--------------------------------

### Default Yolobox Execution

Source: https://github.com/finbarr/yolobox/blob/master/docs/security.md

This is the default command for running Yolobox with the Claude model, providing protection against accidental damage.

```bash
yolobox claude
```

--------------------------------

### Run Single Command in Isolation

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Executes a single command within the sandbox with network and environment variable passthrough disabled, and the project mounted as read-only.

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

--------------------------------

### Bridge URL Opening to Host Browser

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Allow URLs opened within the yolobox to be directed to the host machine's default browser. This is controlled by the --open-bridge flag.

```bash
yolobox codex --open-bridge
```

--------------------------------

### Join Existing Docker Network

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Connect the yolobox to an existing Docker network, such as one created by Docker Compose. This allows the yolobox to communicate with other services on that network.

```bash
yolobox run --network my-compose_default sh -lc 'getent hosts db'
```

--------------------------------

### Manage Git Workflow in a Forked Environment

Source: https://github.com/finbarr/yolobox/blob/master/docs/recipes.md

Commit and push changes from your forked agent environment to synchronize with your Git remote. Treat your remote as the collaboration point.

```bash
git status
git add <files>
git commit -m "Implement feature"
git push -u origin HEAD
```

--------------------------------

### Configure Yolobox to Use Custom Image

Source: https://github.com/finbarr/yolobox/blob/master/docs/customizing.md

Specify a custom Docker image to be used by Yolobox. This is done by setting the 'image' field in the Yolobox configuration file.

```toml
image = "my-yolobox:latest"
```

--------------------------------

### Reduced Attack Surface Configuration

Source: https://github.com/finbarr/yolobox/blob/master/docs/security.md

Use this command for a tighter security box when inspecting or running untrusted code. It disables network access, environment variable passthrough, and sets the project to read-only, excluding sensitive files.

```bash
yolobox claude --no-network --no-env-passthrough --readonly-project --exclude ".env*" --exclude "secrets/**"
```

--------------------------------

### Allow Docker Commands Inside Yolobox

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Enable Docker commands to be executed from within the yolobox environment. This requires the --docker flag.

```bash
yolobox run --docker docker version
```

--------------------------------

### Update Bundled AI CLIs

Source: https://github.com/finbarr/yolobox/blob/master/docs/commands.md

Updates all bundled AI CLIs within the persistent Yolobox home volume. Can update all or specific agents.

```bash
yolobox update-agents
yolobox update-agents claude codex
yolobox update-agents antigravity
```

--------------------------------

### Update All Bundled AI CLIs

Source: https://github.com/finbarr/yolobox/blob/master/skills/yolobox-orchestrator/references/commands.md

Update all AI CLIs bundled within the persistent yolobox home directory. This is a global maintenance command that ignores local project configurations.

```bash
yolobox update-agents
```

--------------------------------

### Skipping Automatic Project Mount

Source: https://github.com/finbarr/yolobox/blob/master/docs/flags.md

Use `--no-project` when the project's working directory is not visible to the Docker/Podman daemon. This disables the default project mount, workdir, and `$YOLOBOX_PROJECT_PATH`, requiring the caller to provide necessary mounts and workdir.

```bash
yolobox run --no-project \
  --mount /host/path/to/project:/workspace \
  --runtime-arg=--workdir=/workspace \
  bash
```