Toolbox

Documentation index

Canonical section-level map of every guide. Renaming a heading breaks inbound links — update this map (and run make check-links) when adding or renaming sections.

Guide	Type	Covers
commands.md	reference	Every CLI command, flag, and subcommand
configuration.md	reference	All .toolbox.yaml keys, loading order, TOOLBOX_* env
mounts.md	reference	Credential isolation, mount merge, mounts_root, profiles, startup hooks
shells.md	how-to	Named shells / multiple workspaces
bridge.md	explanation	Host daemon for browser / editor / proximo forwarding
proximo.md	explanation	.test apps + CA trust inside the container
update-notification.md	explanation	In-shell "newer image / CLI available" banner
sdd.md	how-to	Spec-Driven-Development skill packs
troubleshooting.md	how-to	Failure modes: symptom → fix
internals/	explanation	Maintainer-only material

commands.md

• Global flag: --config
• toolbox shell — Profiles · Publishing ports · Loopback bridge · --oauth presets
• toolbox worktree
• toolbox list
• toolbox stop
• toolbox build
• toolbox version
• toolbox init
• toolbox config — config provenance & doctor, config ui
• toolbox mounts
• toolbox shells
• toolbox bridge
• toolbox sdd
• toolbox completion
• --where targeting

configuration.md

• Getting started
• Loading order
• Key reference
• shell
• agent
• managed_statusline
• inherit-host-auth
• Image selection
• browser_bridge (deprecated)
• env: passthrough
• worktree
• TOOLBOX_* environment variables

mounts.md

• Auth isolation under ~/.toolbox/
• SSH host-key trust (git over SSH)
• mounts: merge semantics — Source paths
• mounts_root retarget
• Profiles
• Startup hooks — Per-repo startup hooks
• CA certificate trust
• mounts CLI

shells.md

• Targeting: toolbox shell [name|dir]
• The shells: block
• Env overlays
• Managing entries: toolbox shells
• Bootstrap shorthand: shell --create

bridge.md

• Quick start
• Architecture — Transport · State directory
• Install topology
• Security boundary
• Editor shims
• Mount gating
• Uninstall surface
• Troubleshooting

proximo.md

• Why .test is unreachable from a sibling container
• Enablement is auto-detected (tri-state proximo)
• The two host-side ingredients
• Trust establishment (entrypoint, self-gated on the mount)
• Lifecycle from inside the container (bridge shim)
• Boundaries and caveats

update-notification.md

• What you see
• How it works
• Cache and TTL
• Opt out

sdd.md

• Supported integrations
• CLI usage
• SDD install steps
• SDD .gitignore fence

troubleshooting.md

• Config or port edits don't take effect
• Port already in use on the host
• "unknown mount name" at startup
• Nerd Font placeholders in the prompt
• xdg-open, code, or OAuth login does nothing
• Stale local branches pile up after merges
• A new .test app is unreachable from the container
• "manifest unknown" with a registry mirror

Internals

Maintainer-only material — build mechanics, boot plumbing, privacy lockdown, host-CLI primitives.

internals/image-build.md

• Build layout: parallel fetch stages + frequency-ordered tail
• Host UID mapping
• SSH host-key trust
• Passwordless sudo
• Docker CLI checksum
• Tool version pinning
• rtk arm64 is built from source
• Rust base image tag scheme
• Slim Rust images ship no curl / ca-certificates
• Homebrew
• DO_NOT_TRACK + claude wrapper
• Two Docker version streams
• Tools removal
• Node package weight prune
• Renovate automerge

internals/container-lifecycle.md

• Image selection mechanics
• Codex nested sandbox
• Container teardown

internals/shell-start.md

• Prompt glyph width
• Prompt module toggles
• UTF-8 locale
• Managed statusline
• MCP plugin auto-build
• Playwright browser cache sync
• cf Cloudflare CLI skill auto-install
• Per-repo code-graph skills: graphify and codegraph
• Per-repo playwright-cli skill
• Skill discovery paths diverge between Claude and Codex
• GitLab git credential helper (glab)

internals/privacy.md

• rtk hook auto-wiring + telemetry/tee lockdown
• Claude Code env-var matrix

internals/host-cli.md

• Shared fs primitives