Configuration

Interactive setup

Run yolobox setup to write global defaults to ~/.config/yolobox/config.toml.

Config files

Global config

Path: ~/.config/yolobox/config.toml

Applies to all projects:

default_harness = "codex"
# platform = "linux/amd64" # run emulated; persistent volumes are kept per architecture
git_config = true
opencode_config = true
kimi_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"]

Project config

Path: .yolobox.toml

Place in your project root for project-specific settings:

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"]

Use env = ["KEY=value"] for per-project environment variables that should be passed directly to the process inside yolobox. Values are not shell-expanded by yolobox, so use container paths such as /home/yolo/.codex-account rather than ~/.codex-account when configuring tool homes:

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

Precedence

CLI flags > project config > global config > defaults

Use container_name or --name only when you need a stable runtime container name for inspection or integration. Fixed names cannot run concurrently; Docker, Podman, or Apple container will reject a second live container with the same name.

Emulated architectures

Set platform (or pass --platform) to run the container under emulation, e.g. linux/amd64 on Apple Silicon. The value is passed to the runtime's run, pull, and custom-image build commands. Apple container does not support it.

Persistent volumes are kept per architecture so native and emulated sessions never share /home/yolo, /var/cache, or /output: the native architecture uses the legacy names (yolobox-home, yolobox-cache, yolobox-output), while any other architecture gets suffixed volumes such as yolobox-home-amd64. yolobox reset --force removes all of them; add --platform to reset just one architecture.

yolobox resolves a single effective platform and uses it for the run, image pulls, custom-image builds, and volume selection, so the architecture that runs always matches the volumes that are mounted. In precedence order:

1. platform / --platform, or a --platform entry in runtime_args. If both are set they must agree, otherwise yolobox errors out.
2. The DOCKER_DEFAULT_PLATFORM environment variable. yolobox passes this on explicitly rather than leaving it to the runtime. It is ignored for Apple container, which cannot act on it and always runs natively.
3. The native host architecture.

The resolved platform and architecture are reported in the context manifest as runtime.platform and runtime.arch.

Default harness

Set default_harness to one AI shortcut name to make bare yolobox launch that tool:

default_harness = "codex"

Valid values are claude, codex, gemini, kimi, agy, antigravity, opencode, copilot, pi, and none. Use none in project config to override a global default harness and keep bare yolobox as an interactive shell. yolobox shell always opens a shell regardless of this setting.

Project file filtering

Use project config when you want a repo to carry its own sandboxed view:

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

• exclude globs are relative to the project root and support **
• copy_as sources can be relative or absolute host paths
• copy_as destinations must stay inside the project and already exist as files
• copy_as takes precedence if it targets the same path as exclude
• both options currently require readonly_project = true or --readonly-project
• both options are incompatible with no_project = true or --no-project
• Apple's container runtime does not support this feature yet

Skipping the automatic project mount

Set no_project = true only in advanced environments where yolobox's current working directory is not visible to the Docker or Podman daemon. In that mode, provide the mount and workdir explicitly:

no_project = true
mounts = ["/host/path/to/project:/workspace"]
runtime_args = ["--workdir=/workspace"]

no_project = true cannot be combined with readonly_project, exclude, or copy_as.

Customization config

Project-level image customization lives under [customize]:

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

Use packages for apt installs. Use dockerfile when you need extra build logic on top of that.

Runtime args format

Each runtime_args entry is a single CLI argument. For flags that take a value, add them as separate entries:

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

Host clipboard

Set clipboard = true or pass --clipboard to bridge text clipboard copy/paste between the container and the host. yolobox starts a short-lived host proxy for the session and exposes clipboard command shims inside the container: pbcopy, pbpaste, xclip, xsel, wl-copy, and wl-paste.

clipboard = true cannot be combined with no_network = true.

Host URL open bridge

Set open_bridge = true or pass --open-bridge to bridge URL opening from the container to the host. yolobox starts a short-lived host proxy for the session and exposes open and xdg-open shims inside the container.

The bridge only accepts http:// and https:// URLs and asks the host OS to open them in the default browser. open_bridge = true cannot be combined with no_network = true.

RTK command compression

Set rtk = true or pass --rtk to enable RTK command-output compression for supported AI shortcuts. yolobox installs the latest RTK release available when the base image is built, then runs RTK init inside the container for Claude, Codex, Gemini, or OpenCode after any host config sync.

yolobox does not auto-update RTK at startup. To get a newer RTK release, rebuild or pull a newer yolobox image. Copilot and Pi are not auto-initialized because RTK does not currently provide a matching non-project config hook for them.

Global agent instructions

The --copy-agent-instructions flag copies your global or user-level instruction files and skills into the container.

Files copied if they exist on your host:

Tool	Source	Destination
Claude	~/.claude/CLAUDE.md	/home/yolo/.claude/CLAUDE.md
Claude skills	~/.claude/skills/	/home/yolo/.claude/skills/
Gemini/Antigravity	~/.gemini/GEMINI.md	/home/yolo/.gemini/GEMINI.md
Codex	~/.codex/AGENTS.md	/home/yolo/.codex/AGENTS.md
Codex skills	~/.codex/skills/	/home/yolo/.codex/skills/
Kimi Code	~/.kimi-code/AGENTS.md	/home/yolo/.kimi-code/AGENTS.md
Kimi Code skills	~/.kimi-code/skills/	/home/yolo/.kimi-code/skills/
Pi	~/.pi/agent/AGENTS.md	/home/yolo/.pi/agent/AGENTS.md
Pi skills	~/.pi/agent/skills/	/home/yolo/.pi/agent/skills/
Copilot	~/.copilot/agents/	/home/yolo/.copilot/agents/

This copies instruction files and skills, not full configs, credentials, settings, or history. For full tool configs, use --claude-config, --codex-config, --gemini-config, --kimi-config, --opencode-config, or --pi-config. Antigravity CLI stores its config under ~/.gemini/antigravity-cli, so --gemini-config covers Antigravity too.

Explicit environment variables

Pass extra environment variables with env = [...] in config or --env KEY=value on the CLI.

env = [
  "DEBUG=1",       # literal value, passed through verbatim
  "MY_API_KEY",    # key only: forwards MY_API_KEY from the host as-is
]

Values are passed to the container runtime verbatim. Nothing in them is interpreted, so a value containing $ (a bcrypt hash, a shell fragment, a jq filter) arrives unchanged. Key-only entries (no =) are passed to the runtime unchanged too, which forwards the variable from the host under the same name.

Renaming host variables

env_from_host = [...] in config and --env-from-host KEY=HOST_VAR on the CLI set the container variable KEY from the host variable HOST_VAR. Use this to give the sandbox a different value than the host uses under the same name:

env_from_host = [
  "GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN",  # container GH_TOKEN = host YOLOBOX_READONLY_GH_TOKEN
]

With that config, a host shell holding a read-write GH_TOKEN and a read-only YOLOBOX_READONLY_GH_TOKEN gives the container only the read-only one, without the token ever being written into .yolobox.toml.

Both sides are plain variable names — write GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN, not GH_TOKEN=$YOLOBOX_READONLY_GH_TOKEN.

An alias owns its container variable, and it fails closed:

• If the host variable is not set, yolobox refuses to start the container. Skipping the entry would let the more privileged variable it replaces reach the container instead.
• The alias suppresses every other source for that key. Automatic passthrough and --gh-token are skipped for an aliased key, so GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN cannot be shadowed by the host's read-write GH_TOKEN.
• Setting the same key in both env and env_from_host is an error. Pick one.

Auto-forwarded environment variables

These are automatically passed into the container if they are set on the host:

• ANTHROPIC_API_KEY
• CLAUDE_CODE_OAUTH_TOKEN
• OPENAI_API_KEY
• COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN
• OPENROUTER_API_KEY
• GEMINI_API_KEY
• AZURE_OPENAI_API_KEY
• CEREBRAS_API_KEY
• DEEPSEEK_API_KEY
• FIREWORKS_API_KEY
• GROQ_API_KEY
• KIMI_API_KEY
• MINIMAX_API_KEY
• MISTRAL_API_KEY
• XAI_API_KEY
• ZAI_API_KEY
• AI_GATEWAY_API_KEY

Set no_env_passthrough = true or pass --no-env-passthrough to disable all automatic host environment passthrough. This suppresses the API/token list above plus TERM, LANG, and detected TZ; explicit env = [...] config and --env KEY=value still pass through, and gh_token = true or --gh-token still forwards a GitHub token when requested.

macOS and GitHub tokens

On macOS, gh stores tokens in Keychain, not environment variables. Use --gh-token or gh_token = true if you want yolobox to extract and forward the GitHub token. When a token is present, yolobox also configures HTTPS Git auth for github.com remotes.

Runtime context manifest

Every yolobox session provides a runtime manifest at /run/yolobox/context.json and sets YOLOBOX_CONTEXT_FILE to that path.

The manifest is intended for agents and scripts running inside the container. It exposes the resolved runtime and launch context in JSON, including an inside_yolobox confirmation, the effective config, container paths, the resolved container platform and architecture, launch command, fork metadata when yolobox fork is active, and the keys of forwarded environment variables without copying their values into the manifest.

The canonical skill packages live under skills/:

• skills/yolobox is the inside-the-box skill that orients the agent to the trusted yolobox sandbox it is running in, then uses this manifest to explain the current sandbox accurately. Its Readonly project mode line reports the launch mode; its Project writable now line is a live filesystem check. yolobox currently installs it for Claude, Codex, and Kimi Code sessions inside the container.
• skills/yolobox-orchestrator is the host-side skill for agents that need to launch or control yolobox itself.

yolobox also injects a managed guidance block into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.kimi-code/AGENTS.md so those agents know to use the yolobox skill when current sandbox assumptions matter.

Config sync warning

WARNING

Setting claude_config = true, codex_config = true, gemini_config = true, kimi_config = true, opencode_config = true, or pi_config = true in config syncs your host config on every container start. Claude, Gemini/Antigravity, OpenCode, and Pi config sync replaces the matching in-container config directory, overwriting changes made inside the container. Antigravity CLI stores its settings under ~/.gemini/antigravity-cli, so gemini_config = true covers it. Kimi Code config sync incrementally merges host config, credentials, skills, and sessions into ~/.kimi-code while leaving the container's bin/, logs/, and updates/ paths alone. Codex config sync incrementally merges durable host files into ~/.codex, skips volatile Codex log, state, cache, and temp files, preserves a valid in-container auth.json when the host copy has no usable auth file, and live-mounts host Codex sessions so resume history stays current without copying it. Prefer --claude-config, --codex-config, --gemini-config, --kimi-config, --opencode-config, or --pi-config for one-time syncs.

Startup timing diagnostics

Set YOLOBOX_TIMING=1 to print host-side and container-entrypoint timing markers:

YOLOBOX_TIMING=1 yolobox run true

This is useful when diagnosing slow config sync, Docker startup, update checks, or runtime argument construction.

yolobox removes a zero-byte /home/yolo/.codex/auth.json during startup. Recent Codex versions fail with EOF while parsing a value when that stale file exists; removing it lets Codex recreate auth normally or show the sign-in flow.

If Codex auth fails with No space left on device, the Docker or Podman storage backing /home/yolo or /tmp is full. Check docker system df or the equivalent for your runtime, then reclaim runtime storage or increase the VM disk size. yolobox warns at container startup when those paths are nearly full, but it does not automatically prune unrelated images, volumes, or build cache.