yolobox sandboxes AI coding agents without mounting your home directory

yolobox mounts the project and leaves the home directory out

The problem yolobox sets out to solve is narrow and familiar. AI coding agents do useful work when they can run shell commands without stopping for confirmation, but the same freedom makes one badly interpreted prompt able to delete a home directory. yolobox is a container wrapper that gives the agent that freedom inside a boundary.

The mechanics are simple to state. The project directory is mounted into the container at its real host path, so a path like /Users/you/project means the same thing inside and outside. The agent holds full permissions and sudo inside the container. The home directory is not mounted at all unless you explicitly opt in. Tools, configuration files and sessions persist across runs in dedicated volumes, so a second session does not start from an empty filesystem.

The project's own summary of the goal is that the AI can go wild inside the sandbox while the real home directory is untouchable. That framing is what makes yolobox useful for the case it targets, and also what defines its limits: the protection is a mount table, not a policy engine. Everything reachable inside the container is reachable, and anything you deliberately mount or expose becomes reachable again.

Installation is a brew line or a curl pipe, and the first run is one command

Two install paths are given in the README, and both are one line each:

# Install via Homebrew
brew install finbarr/tap/yolobox

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

The Homebrew path installs bash and zsh completions automatically, while the script path sends you to the getting started documentation for shell completions. After installation you move into a project directory and name the agent you want:

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

The same shape works for the other supported tools, with yolobox codex, yolobox gemini, yolobox kimi, yolobox agy, yolobox antigravity, yolobox opencode, yolobox copilot and yolobox pi all listed as shortcuts. Setting default_harness = "codex" makes a bare yolobox launch Codex instead of asking. Two more entry points matter for scripted use: yolobox shell gives a manual shell inside the same sandbox, and yolobox run <cmd...> executes one command in it.

The installation itself is small. The repository is a Go module, github.com/finbarr/yolobox, requiring Go 1.23.0, and the Makefile exposes build, test, lint, image and smoke-test targets, with the binary built from ./cmd/yolobox.

The image is Ubuntu with the toolchains and AI CLIs preinstalled

The sandbox is defined by a Dockerfile in the repository root, and the shape of that file explains why first runs can be slow. It uses multi-stage builds, with a Go source stage on golang:1.25.6, a Bun runtime stage on oven/bun:1.3, and a separate Ubuntu 24.04 stage whose only job is to install the Claude Code CLI from https://claude.ai/install.sh. The final image is Ubuntu 24.04, which means the base layer for the box is the same distribution family as the stage used to install the CLI.

The system packages are laid out to remove the need for a network round trip during a session. The build installs curl, git, sudo, build-essential, make, cmake, Python 3 with pip and venv, jq, rsync, ripgrep, fd, bat, fzf, vim, htop and other utilities, plus Node.js 22 LTS installed from the NodeSource setup script. The README summarises the same list as AI CLIs, Codex and Claude ACP adapters, Node.js, Python, Go, Bun, build tools, Git, the GitHub CLI, ripgrep, fd, fzf, jq, vim and RTK.

Two details in the Dockerfile shape everyday behaviour. The build declares ARG NPM_MIN_RELEASE_AGE_DAYS=7, which points at a freshness policy for npm packages, and it declares cache-busting build arguments for the Claude, Antigravity and Kimi installers, so those installers re-run when the argument changes. The image is published as ghcr.io/finbarr/yolobox:latest according to the Makefile defaults.

Supported CLIs are wrapped to skip permission prompts, ACP clients are not

Inside the sandbox, the supported AI CLIs are wrapped so that permission prompts are skipped. The README is explicit about what that means: no confirmations, no guardrails. Claude Code, Codex and Kimi Code also receive built-in guidance describing the sandbox they are running in, so the agent understands its own environment instead of assuming it has the whole filesystem.

The distinction that matters is between the CLI wrappers and ACP clients. For an ACP client or editor, the README says to use yolobox run codex-acp or yolobox run claude-agent-acp as the stdio agent command. The adapters bundle compatible engines and use the client permission modes, and the sentence that follows is a limitation worth repeating: the yolobox CLI YOLO wrappers and --no-yolo do not control them. Configuration syncing and authentication options that already exist still apply.

So the permission-free behaviour is a property of the wrapped CLIs, not of the container boundary as a whole. A user driving an ACP adapter inherits whatever permission mode that client enforces, which may or may not be unrestricted. One more practical detail: image pull and custom-image build progress goes to stderr, leaving stdout and piped stdin free for the container command, including during ACP startup. That is what lets an editor wire the adapter to the process without parsing progress chatter.

Per-project customization lives in .yolobox.toml, not a forked image

Projects that need extra tools or environment variables are handled with a small configuration file rather than a custom base image. The file lives in the project directory:

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

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

The env array sets variables inside the container, and the customize table lists packages to install. A Dockerfile fragment can also be layered on top of the base image, in which case the first run builds a derived image and later runs reuse it until the base image or the customization inputs change. That reuse behaviour is the reason to prefer a fragment over forking: a fork pins you to your own copy of everything, while a derived image is rebuilt from the current base.

One trap is called out explicitly. Env values are passed to the process verbatim and nothing in them is interpreted, and container paths are used for env values because that is where they are applied. So a path written for the host will not resolve inside the box, and a value containing shell-like syntax will not be expanded.

env_from_host swaps a real token for a read-only alias

The most security-relevant feature in the README is env_from_host, which lets a sandbox receive a different value than the host uses under the same name. The example swaps a real GitHub token for a read-only one:

# .yolobox.toml
env_from_host = ["GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN"]

The alias owns that variable. It suppresses the automatic passthrough and the --gh-token flag for the same key, and yolobox refuses to start if the host variable is unset. That last point is the useful one: the failure mode is a refusal to run rather than a silent fallback to the real credential, so the token the alias replaces cannot leak in by accident.

The wider workflow commands show how the rest of the boundary is managed. yolobox setup configures global defaults and yolobox config shows the resolved configuration for a project. yolobox claude --docker --gh-token grants the agent Docker and GitHub access. yolobox fork --name bruno codex gives an agent its own copy of the project, which keeps concurrent agents from editing the same working tree. yolobox run --no-network make test runs a single command with networking removed, and yolobox upgrade updates the binary and pulls the latest image while yolobox update-agents refreshes the AI CLIs and ACP adapters inside the persistent box.

Config sharing and flags widen the boundary again

Several flags trade isolation for continuity, and the README describes each one precisely. yolobox claude --claude-config --no-claude-auth shares Claude configuration while keeping the login in the box independent, and the sync is incremental: durable Claude settings are synchronized and the host ~/.claude/projects directory is live-mounted read/write so session resume history stays current. The caveat is that --no-claude-auth keeps the box login independent but does not make that project history mount read-only.

The Copilot equivalent is similar. yolobox copilot --copilot-config syncs durable ~/.copilot settings, agents, skills and MCP configuration, forwards the host Copilot login as COPILOT_GITHUB_TOKEN, and live-mounts ~/.copilot/session-state read/write, with --no-copilot-auth available to keep the box login separate.

Read together, these flags mean the home directory can re-enter the picture through a narrow, deliberate door. A session history directory mounted read/write is writable by the agent, and the Copilot flag forwards a host credential into the box. RTK setup is applied automatically across the supported CLI integrations without prompting, including on the first OpenCode startup, and telemetry stays disabled unless it is enabled interactively from inside the box with rtk telemetry enable. OpenCode installs and updates explicitly allow the npm postinstall script it requires, which is a privileged operation inside the container that has no equivalent on the host.

The failure modes are structural rather than bugs. The container is not a security boundary against a determined adversary, since the agent holds sudo inside it and the project directory is mounted read/write, which means an agent can rewrite your project source at will. It is a boundary against accidents.

Three flags change the risk profile in ways worth naming. --docker gives the agent Docker access, which is effectively control of the host, and --gh-token adds a GitHub credential to a box whose selling point is isolation. The ACP adapters ignore --no-yolo and the YOLO wrappers, so a user who assumes the flag governs every path will get different behaviour in an editor than in a terminal.

The persistence story has its own cost. Tools, configs and sessions live in persistent volumes, which is convenient across runs and also means state accumulates outside the project directory, including session history mounted from the host. The upgrade path is a rebuild rather than a version pin: yolobox upgrade pulls the latest image, and the npm freshness policy and cache-busting build arguments mean the contents of the box can shift even when your own configuration has not.

Host execution and hand-written Docker are the alternatives

The obvious alternative is to run the agent directly on the host with its normal permission mode, accepting the risk the README opens with. The difference in approach is exactly what yolobox removes: no mount table, no container image, no persistent volume. In exchange you keep the host's existing tooling, your real credentials, and the ability to work with anything already on the machine, and you accept that a bad command reaches all of it.

The second alternative is to write your own container setup: a Dockerfile with the tools you want, a bind mount for the project, and a docker run invocation. The difference there is who decides the boundary. Your image contains only what you added, so it starts faster and holds less, but you own the maintenance of the toolchain, the persistence of the volumes and the agent wrappers that skip the permission prompts. yolobox hands those to you prebuilt, with Node, Python, Go, Bun, Git and the AI CLIs already inside and the permission-skipping behaviour already wired up.

The trade is therefore between a maintained, opinionated image with a wider default toolchain and a hand-rolled container that stays small and transparent. yolobox also keeps the option open: the customization mechanism lets you layer packages and Dockerfile fragments on the base image, and yolobox fork copies a project so parallel agents do not collide.

Editorial conclusion

Adopt yolobox if you want to let an agent run commands freely on a machine where a stray rm -rf ~ would hurt, and you are comfortable with a container image that pulls AI CLIs from the network. Do not adopt it if you need the ACP adapters to honour the sandbox flags, because the README states the CLI YOLO wrappers and --no-yolo do not control them, or if you want the host's ~/.claude or ~/.copilot directories left unmounted. Verify first that yolobox fork, --docker and the read/write project history mounts behave the way your workflow assumes, since those are the paths that widen the boundary again.

Frequently asked questions

Official sources

1. finbarr/yolobox on GitHub
2. Issues
3. License: MIT
4. README
5. Releases