---
url: https://findutils.com/guides/yolobox-ai-sandbox-configurator-guide
title: "Yolobox Configurator: Generate AI Sandbox Configs in Seconds"
description: "Build .yolobox.toml configs and CLI commands for running Claude Code, Codex, and Gemini inside isolated containers. Free visual configurator."
category: developer
content_type: guide
locale: en
read_time: 7
status: published
author: "codewitholgun"
published_at: 2026-04-01T12:00:00Z
excerpt: "Yolobox runs AI coding agents inside Docker containers with full sudo access while keeping your home directory safe. This guide shows how to configure it visually with our free configurator instead of memorizing 30+ CLI flags."
tag_ids: ["ai-sandbox", "docker", "developer-tools", "claude-code", "devops"]
tags: ["AI Sandbox", "Docker", "Developer Tools", "Claude Code", "DevOps"]
primary_keyword: "yolobox configurator"
secondary_keywords: ["yolobox toml config", "AI coding agent sandbox", "claude code docker sandbox", "run AI agent in container", "yolobox setup guide", "codex gemini sandbox"]
tool_tag: "yolobox-configurator"
related_tool: "yolobox-configurator"
related_tools: ["yolobox-configurator", "dnpm-configurator", "chmod-calculator"]
updated_at: 2026-04-01T12:00:00Z
---

## What Is Yolobox and Why Should You Use It?

Yolobox is an open-source CLI that runs AI coding agents (Claude Code, OpenAI Codex, Gemini, Copilot) inside isolated Docker containers. The AI gets full sudo access, auto-approval mode, and complete freedom to install packages and write files, while your home directory stays completely inaccessible. Generate your configuration visually with the free [Yolobox Configurator](/developers/yolobox-configurator) instead of memorizing dozens of CLI flags.

AI coding agents work best when they can run without permission prompts. But giving an AI unrestricted access to your entire machine means one bad command like `rm -rf ~` could wipe your home directory. Yolobox solves this by mounting your project at its real path inside a container while keeping everything else sealed off. The tagline says it all: "Let your AI go full send. Your home directory stays home."

## The Problem: AI Agents Need Freedom, You Need Safety

Modern AI coding agents like Claude Code, OpenAI Codex, and Google Gemini work dramatically better in "yolo mode," where they can execute commands without asking for permission on every step. But that freedom comes with real risk.

- **Accidental destruction** -- an AI that misunderstands context can delete files, overwrite configs, or corrupt your environment
- **Dependency sprawl** -- agents install packages globally, polluting your system Python, Node, or Go installations
- **Credential exposure** -- unrestricted agents can read ~/.ssh, ~/.aws, ~/.config, API keys, and tokens
- **System modification** -- agents with sudo can modify system files, install services, and change network settings
- **No rollback** -- damage to your host filesystem is immediate and often irreversible

Running AI agents on bare metal is the 2026 equivalent of running `npm install` without sandboxing. Yolobox gives agents a full Linux environment with sudo access, while your actual machine stays untouched.

## How to Configure Yolobox With the Visual Configurator

### Step 1: Open the Configurator

Open the FindUtils [Yolobox Configurator](/developers/yolobox-configurator) in your browser. No signup, no download, no installation needed. Everything runs client-side in your browser.

### Step 2: Select Your AI Agent

Choose from the supported agents at the top of the configurator:

| Agent | Yolo Mode | Command |
|-------|-----------|---------|
| Claude Code | `--dangerously-skip-permissions` | `yolobox claude` |
| OpenAI Codex | Full access mode | `yolobox codex` |
| Google Gemini | `--yolo` | `yolobox gemini` |
| GitHub Copilot | `--yolo` | `yolobox copilot` |
| OpenCode | No yolo flag | `yolobox opencode` |
| Shell | Interactive bash | `yolobox` |
| Custom | Any command | `yolobox run <cmd>` |

Each agent runs in the container with its appropriate "full send" flags pre-configured. Select "Custom" to run any command you want inside the sandbox.

### Step 3: Configure Host Forwarding

Enable the credentials and sockets your AI agent needs:

- **Git Config** -- copies `~/.gitconfig` so the agent can commit with your identity
- **GitHub Token** -- forwards `GH_TOKEN` so the agent can create PRs, read issues, and push code
- **SSH Agent** -- forwards your SSH agent socket for git operations over SSH
- **Docker Socket** -- mounts the Docker socket if your agent needs to build or run containers
- **Claude/Gemini Config** -- copies agent-specific configuration directories into the container

Only enable what you actually need. Every forwarded credential is a potential attack surface if the agent runs malicious code.

### Step 4: Set Security and Isolation Options

The configurator provides four security toggles:

- **Mindful Mode (no-yolo)** -- disables auto-approval, requiring manual confirmation for every command. Useful when testing untrusted codebases
- **Read-Only Project** -- mounts your project as read-only. The agent writes to `/output` instead. Good for code review and analysis tasks
- **Disable Network** -- cuts all network access inside the container. Use this for fully offline builds or when processing sensitive code
- **Scratch Session** -- creates a fresh home directory and cache for every session. Nothing persists between runs

### Step 5: Set Resource Limits

Constrain what the container can consume:

- **CPUs** -- limit to specific core count (e.g., "4" or "3.5")
- **Memory** -- hard memory limit (e.g., "8g" for 8 gigabytes)
- **Shared Memory** -- /dev/shm size, important for Chrome/Puppeteer workloads
- **GPUs** -- pass through GPU devices (e.g., "all" or "device=0")

Setting resource limits prevents a runaway AI from consuming your entire machine's resources during compilation or testing.

### Step 6: Add Packages and Mounts

The Advanced Configuration section lets you:

- **APT Packages** -- add system packages the agent needs (python3-pip, postgresql-client, ffmpeg, etc.). Click suggestions or type custom package names
- **Extra Mounts** -- mount additional host directories into the container (format: `/host/path:/container/path:rw`)
- **Environment Variables** -- pass custom env vars (format: `KEY=value`)
- **Exclude Patterns** -- hide files from the container using glob patterns (e.g., `*.secret`, `.env*`)
- **Linux Capabilities** -- add specific capabilities like SYS_PTRACE for debugging or NET_ADMIN for network tools

### Step 7: Copy Your Output

The right panel shows three output tabs:

1. **CLI Command** -- a ready-to-paste `yolobox` command with all your flags
2. **.yolobox.toml** -- project-level config file to commit to your repo
3. **Global Config** -- `~/.config/yolobox/config.toml` for machine-wide settings

Click "Copy" on any tab and paste directly into your terminal or file.

## Understanding the Two Config Files

Yolobox uses two configuration files that work together:

| File | Location | Scope | Use For |
|------|----------|-------|---------|
| `.yolobox.toml` | Project root | Per-project | Packages, mounts, env vars, network, Dockerfile fragments |
| `config.toml` | `~/.config/yolobox/` | Machine-wide | Git config, tokens, SSH, Docker, resource limits, capabilities |

Project config overrides global config. Both are optional -- CLI flags override everything.

### When to Use .yolobox.toml vs CLI Flags

Commit `.yolobox.toml` to your repo when:
- Team members need the same container setup
- The project requires specific system packages (e.g., ffmpeg for media processing)
- You need custom mounts or environment variables
- The project has a Dockerfile fragment for additional setup

Use CLI flags when:
- Trying a one-off configuration
- Overriding project settings temporarily
- Running a quick sandbox session

## Security Model: What Yolobox Protects (and What It Doesn't)

Yolobox provides container-level isolation. This is not a VM -- it is a process namespace boundary with filesystem restrictions.

### What it protects against:
- Accidental `rm -rf ~` or similar destructive commands
- Agent installing packages or services on your host
- Agent reading your SSH keys, AWS credentials, or browser cookies
- Agent modifying system configuration files
- Dependency sprawl from agent-installed global packages

### What it does NOT protect against:
- A determined adversary with kernel exploits could potentially escape the container
- If you forward your Docker socket, the agent has host-level Docker access
- If you forward SSH agent or GH token, the agent can use those credentials
- Container networking is shared with the host by default (unless `--no-network` is set)

For maximum security, the yolobox project recommends rootless Podman (select "podman" as runtime in the configurator) or VM-level isolation for processing truly untrusted code.

## Yolobox Configurator: Free vs Manual Configuration

| Feature | FindUtils Configurator (Free) | Manual CLI Flags | Manual TOML |
|---------|-------------------------------|------------------|-------------|
| Price | Free, no signup | Free | Free |
| Learning curve | Visual, self-documenting | Memorize 30+ flags | Learn TOML syntax |
| Error-prone | Impossible to typo a flag | Easy to mistype | TOML syntax errors |
| All 3 outputs | CLI + project TOML + global TOML | One at a time | One file |
| Package suggestions | Click to add common packages | Google the apt name | Google the apt name |
| Capability reference | Built-in suggestion list | Man pages | Man pages |
| Shareable | Copy and paste any output | N/A | N/A |

The FindUtils [Yolobox Configurator](/developers/yolobox-configurator) generates all three configuration formats simultaneously so you never have to cross-reference documentation.

## Real-World Use Cases

### 1. Full-Stack Feature Development

Give Claude Code complete freedom to scaffold features, install dependencies, run tests, and commit code -- all inside the sandbox.

Configuration: Git config ON, GitHub token ON, SSH agent ON. No resource limits. Network enabled.

### 2. Untrusted Codebase Review

An AI agent reviews a third-party codebase you cloned. Read-only project mount prevents any modifications. Network disabled prevents data exfiltration.

Configuration: Read-only project ON, no network ON, mindful mode ON. No credentials forwarded.

### 3. ML/AI Training Workflows

Pass through GPUs for the agent to run training jobs. Add python3-pip and CUDA packages.

Configuration: GPUs = "all", packages = ["python3-pip", "python3-venv"], memory = "16g", cpus = "8".

### 4. Team Standardization

Commit `.yolobox.toml` to the repo so every developer gets the same sandbox environment. Include required system packages, custom mounts for shared data, and project-specific env vars.

## Common Mistakes When Configuring Yolobox

### Mistake 1: Forwarding Everything

Enabling every toggle (git, SSH, Docker, GH token) when the agent only needs to read code. Only forward credentials the agent actually needs for the task.

### Mistake 2: Forgetting --no-network for Sensitive Code

If you are reviewing proprietary or sensitive code, always disable network access. An AI agent with network access could theoretically exfiltrate code to its API endpoint.

### Mistake 3: Using Docker Runtime Without Rootless Mode

Default Docker runs containers as root on the host kernel. For better isolation, select "podman" runtime in the configurator and install rootless Podman.

### Mistake 4: Not Setting Resource Limits

An AI agent running `make -j$(nproc)` inside a container with no CPU limit will consume every core on your machine. Always set reasonable CPU and memory limits.

### Mistake 5: Ignoring the Scratch Flag for Throwaway Tasks

If you are doing a one-off code review or experiment, use the Scratch Session toggle. This prevents the container from accumulating state across sessions.

## Tools Used in This Guide

- **[Yolobox Configurator](/developers/yolobox-configurator)** -- generate .yolobox.toml configs and CLI commands visually
- **[dnpm Configurator](/developers/dnpm-configurator)** -- generate secure Docker-wrapped npm configurations
- **[Chmod Calculator](/developers/chmod-calculator)** -- calculate Unix file permissions for container mounts

## FAQ

**Q: Is the Yolobox Configurator free to use?**
A: Yes. The FindUtils Yolobox Configurator is completely free with no signup, no usage limits, and no ads. All configuration generation happens in your browser -- nothing is uploaded to any server.

**Q: What is yolobox?**
A: Yolobox is an open-source CLI tool by Finbarr Taylor that runs AI coding agents (Claude Code, OpenAI Codex, Gemini, Copilot) inside isolated Docker containers. The AI gets full sudo access while your home directory stays completely inaccessible.

**Q: Which AI agents does yolobox support?**
A: Yolobox supports Claude Code (with --dangerously-skip-permissions), OpenAI Codex, Google Gemini CLI, GitHub Copilot, and OpenCode. You can also run any custom command inside the container using `yolobox run <command>`.

**Q: Is yolobox safe for running AI agents?**
A: Yolobox provides container-level isolation that protects against accidental filesystem damage. Your home directory is unmounted by default. For maximum security, use rootless Podman as the container runtime or VM-level isolation for processing untrusted code.

**Q: Where do I put the .yolobox.toml file?**
A: Place `.yolobox.toml` in your project root directory. It configures project-specific settings like extra packages, mounts, environment variables, and network isolation. Global settings go in `~/.config/yolobox/config.toml`. The FindUtils configurator generates both files.

**Q: Do I need Docker installed to use yolobox?**
A: Yes. Yolobox requires a container runtime. Docker is the default, but it also supports Podman (recommended for better security) and Apple's container runtime. The configurator lets you select your preferred runtime.

**Q: Can I commit .yolobox.toml to my repository?**
A: Yes, and you should. Committing `.yolobox.toml` ensures every developer on your team gets the same sandboxed AI environment with the same packages, mounts, and security settings.

## Next Steps

- **[Generate your config now](/developers/yolobox-configurator)** -- open the visual configurator and build your setup
- **[Secure your npm workflow too](/developers/dnpm-configurator)** -- if you use npm, add container-level protection for package installs
- **[Read the dnpm guide](/guides/dnpm-secure-docker-npm-wrapper-guide)** -- learn about 12-layer npm sandboxing with Docker
- **[Calculate file permissions](/developers/chmod-calculator)** -- get Unix permissions right for container mount points