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:

git_config = true
gh_token = true
ssh_agent = true
docker = true
no_network = true
network = "my_compose_network"
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:

mounts = ["../shared-libs:/libs:ro"]
env = ["DEBUG=1"]
no_network = true
shm_size = "2g"

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

Precedence

CLI flags > project config > global config > defaults

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

Global agent instructions

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

Files copied if they exist on your host:

Tool	Source	Destination
Claude	~/.claude/CLAUDE.md	/home/yolo/.claude/CLAUDE.md
Gemini	~/.gemini/GEMINI.md	/home/yolo/.gemini/GEMINI.md
Codex	~/.codex/AGENTS.md	/home/yolo/.codex/AGENTS.md
Copilot	~/.copilot/agents/	/home/yolo/.copilot/agents/

This copies instruction files, not full configs, credentials, settings, or history.

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

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 CLI token.

Config sync warning

WARNING

Setting claude_config = true or gemini_config = true in config copies your host config on every container start. That can overwrite changes made inside the container, including auth and history. Prefer --claude-config or --gemini-config for one-time syncs.