Berry Wiki

Yolobox

Properties2
tagsai, sandboxing
aliasesYolobox

8 min read

Yolobox

Checked: 2026-07-14

Project Summary

Yolobox runs coding agents inside a reusable container with permission prompts disabled. The current project directory is mounted at its normal host path, while the host home directory and unrelated projects stay outside the container unless explicitly exposed.

  • Implementation: Go command-line tool plus a Dockerfile-based image
  • License: MIT
  • Current release: v0.18.4
  • Primary goal: Protect a workstation from accidental agent commands while keeping agent use convenient
  • Runtime choices: Docker or Podman; Apple Container is also supported on macOS Tahoe and later

Problem Solved

Coding agents are most productive when they can run commands without repeated approval. On the host, one wrong command can delete a home directory, read unrelated files, or alter other projects.

Yolobox gives the agent a prepared development container with sudo and persistent tooling, but limits its default host view to the current project. It favors easy “YOLO mode” operation over protection from deliberately hostile code.

How It Works

  1. Detect an available container runtime.
  2. Start the Yolobox image with a persistent home/cache volume.
  3. Mount the current project at the same absolute path inside the container.
  4. Run as a yolo user with passwordless sudo inside the container.
  5. Launch a selected agent through a wrapper that skips or auto-accepts permission prompts.
  6. Add a runtime context file and, for Claude and Codex, managed instructions explaining the sandbox.
  7. Preserve agent sessions, installed tools, and configuration in named volumes across launches.

Projects can add packages or a Dockerfile fragment to create a cached derived image. A fork command can give an agent a separate project copy. Read-only project mode writes outputs to /output for later handling.

Security Boundary

  • Default boundary: The selected container runtime and the host kernel beneath it.
  • Agent power: Root-equivalent inside the container.
  • Host visibility: Current project is mounted read-write by default; home directory and unrelated projects are not mounted.
  • Network: Enabled by default.
  • Persistence: Named container volumes survive between runs.

The official security guide says Yolobox is for accidents, not hostile-agent containment. It does not promise protection from kernel exploits, container escapes, or an agent intentionally attacking the boundary.

Stronger modes include:

  • disabling network and automatic host environment forwarding;
  • making the project read-only and excluding sensitive paths;
  • selecting rootless Podman, which maps container root to an unprivileged host user;
  • moving the entire runtime into a VM for hostile workloads.

Platforms And Agents

Platforms

  • macOS: Docker Desktop, OrbStack, Colima, or Apple Container on Tahoe and later.
  • Linux: Docker or Podman.
  • Architectures: Release binaries exist for macOS and Linux on AMD64 and ARM64.

Agents

First-class shortcuts and image tooling cover:

  • Claude Code
  • Codex
  • Gemini
  • Antigravity
  • OpenCode
  • GitHub Copilot CLI
  • Pi

The README also describes “any AI coding agent” through shell or direct command use. Built-in Yolobox guidance is strongest for Claude and Codex.

Setup And Workflow

Install through Homebrew or the official install script, then launch from a project directory. The installer downloads a release binary when possible and builds from source as fallback.

Common workflow:

  1. Run interactive setup to choose global defaults.
  2. Start an agent shortcut from the project.
  3. Let the agent install tools with sudo; persistent volumes keep them.
  4. Use a project configuration file for packages, extra mounts, environment values, exclusions, read-only mode, and image customization.
  5. Use fork when the agent should work in a separate project copy.
  6. Upgrade Yolobox and update bundled agent tools separately.

Claude Code needs at least 4 GB available to its container runtime; the documentation warns that Colima’s smaller default often causes out-of-memory failures.

Network And Credentials

Network

  • Default: Normal outbound container network access.
  • Off switch: --no-network disables networking.
  • Named network/pod: A session may join a chosen runtime network or Podman pod.
  • Docker bridge: --docker mounts the host Docker socket and joins a shared network.
  • Host bridges: Optional clipboard and URL-opening proxies expose narrow host actions.

Yolobox does not provide a hostname allowlist, request inspection, or destination-aware firewall. Network control is mainly on/off or delegated to the selected runtime. Rootless Podman commonly uses slirp4netns, which reduces host-network exposure while retaining internet access.

Credentials

By default, Yolobox automatically forwards many common AI API and OAuth environment variables when present on the host. The guest receives the real values, not placeholders. --no-env-passthrough disables this automatic behavior.

Other opt-in credential paths include:

  • extracting and forwarding a GitHub CLI token;
  • forwarding the SSH agent socket;
  • copying or syncing agent configuration directories;
  • copying Git configuration;
  • passing explicit environment variables;
  • mounting arbitrary files or directories.

Important effects:

  • Any real secret forwarded into the container is readable by the agent and other container code.
  • Network-enabled code can send it anywhere.
  • Forwarding the Docker socket gives the container broad control over the host Docker daemon and can defeat the intended filesystem boundary.
  • Codex config sync can live-mount host session history read-write.
  • Agent config sync may include credentials or authentication state, depending on the tool.

Strengths

  • Wide agent support: Many major coding agents work through direct shortcuts.
  • Low friction: Permission prompts are disabled and common development tools are preinstalled.
  • Useful default filesystem boundary: Home directory, SSH keys, dotfiles, and unrelated projects are hidden.
  • Persistent environment: Tools, sessions, and configuration survive across runs.
  • Cross-platform runtime choice: Works on macOS and Linux with several backends.
  • Agent awareness: Claude and Codex receive managed sandbox guidance and a machine-readable runtime context.
  • Project controls: Read-only mode, exclusions, replacement files, no-project mode, and separate forks.
  • Hardening path: Network-off, environment-off, rootless Podman, and VM recommendations are plainly documented.
  • Custom images: Per-project packages and Dockerfile fragments avoid changing the common base.
  • Supply-chain delay: Packages installed into the published base image avoid npm releases less than seven days old.

Limits And Risks

  • Accident protection only: Default containers are not intended for hostile code.
  • Writable project: The real project can be deleted or corrupted by default.
  • Secrets forwarded by default: Common host API tokens are automatically copied unless disabled.
  • Broad network: No selective egress policy or secret-aware proxy.
  • Container escapes: The host kernel is in scope for runtime/kernel vulnerabilities.
  • Docker socket danger: Enabling Docker access can give near-host-level control.
  • Config exposure: Optional agent/config sync widens access and may include sensitive state.
  • Persistent compromise: Malicious changes inside named volumes can survive later sessions.
  • Runtime differences: Docker, Podman, and Apple Container do not support every feature equally.
  • Apple Container gaps: Project filtering (exclude and copy_as) and derived package/Dockerfile customization are documented as unsupported with that backend.
  • No scoped credential broker: Secrets cannot be limited to one approved API destination.
  • No full resource policy: CPU, memory, shared memory, devices, capabilities, and low-level runtime arguments are configurable, but safe defaults remain the user’s responsibility.
  • Early version: Pre-1.0 project with a short history and a single primary maintainer apparent from the repository.

Activity And Maturity

  • Repository created: 2026-01-09
  • Latest push when checked: 2026-07-07
  • Latest release: v0.18.4 on 2026-06-09
  • Repository signal: 242 commits displayed, about 619 stars, 47 forks, and 1 combined open issue/pull request in GitHub metadata
  • Release history: GitHub displayed 57 releases in roughly five months.
  • Assessment: Actively developed and feature-rich for its age, with unusually direct security documentation. The rapid release rate, pre-1.0 version, backend differences, and accident-focused boundary make it best treated as a convenience tool that needs explicit hardening for sensitive work.

Best Fit

Yolobox fits developers who:

  • want Claude, Codex, Gemini, or another agent to run without permission prompts;
  • mainly fear accidental destructive commands;
  • want the project writable but the rest of the workstation hidden;
  • already use Docker, Podman, OrbStack, Colima, or Apple Container;
  • value persistent tools and sessions;
  • will review which tokens, sockets, configs, and mounts they forward.

It is a weak fit for hostile dependency analysis, untrusted repositories, strict secret non-exposure, selective network egress, multi-tenant use, or anyone needing a VM boundary by default.

Comparison-Relevant Facts

FactYolobox
Primary purposeRun coding agents freely while limiting accidental host damage
Default isolationContainer runtime
VM boundaryNot default; recommended externally for hostile workloads
HostsmacOS and Linux
RuntimesDocker, Podman, Apple Container; macOS alternatives provide Docker-compatible runtime
Agent supportClaude, Codex, Gemini, Antigravity, OpenCode, Copilot, Pi
Project accessReal project mounted read-write by default
Home accessHidden by default
PersistenceNamed home/cache volumes
NetworkEnabled or fully disabled; no hostname allowlist
SecretsReal host environment values auto-forwarded by default
GitHub/SSHOptional GitHub token and SSH-agent forwarding
Work isolationRead-only output mode, path filters, or fork project copy
Agent guidanceManaged Claude/Codex instructions and context manifest
Root in guestPasswordless sudo
LicenseMIT

Hacker News Context

Yolobox appeared in the Clawk thread as a direct “what do you think of this?” link. No reply or detailed comparison was attached to that comment when checked.

The projects solve related but different threat levels:

  • Yolobox: Container-based convenience, many agents, real project mounted directly, broad network, and real tokens forwarded by default. Its own docs frame the boundary as protection from accidents.
  • Clawk: Disposable Linux VM with agent-oriented network and credential controls, aimed at reducing hostile-code and exfiltration risk.

Yolobox can use Apple Container, giving a VM per container on supported Macs. However, its documentation says important project-filtering and custom-image features are unavailable on that backend, and Yolobox still does not add Clawk-style destination filtering or placeholder credentials.

Unknowns

  • Independent audit: No external security audit was found in the reviewed official sources.
  • Maintainer depth: Exact active-maintainer count and long-term governance were not established.
  • Backend parity tests: Full current parity across Docker, Podman, and Apple Container was not independently tested.
  • Secret contents in config sync: Exposure varies by each agent’s file layout and authentication method.
  • Hostile-workload roadmap: No confirmed plan to make a VM boundary or selective egress the default was found.

Sources

Graph View