Docker Sandbox: Quick Reference

Overview

Docker sandboxing runs your AI coding agents (Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI) inside isolated Docker containers while maintaining access to your project files and credentials.

Key Features:

One container per session
Shared authentication across containers (no re-auth needed)
Automatic container lifecycle management
Full project access via volume mounts

CLI vs TUI Behavior

Feature	CLI	TUI
Enable sandbox	`--sandbox` flag	Checkbox toggle
Custom image	`--sandbox-image <image>`	Not supported
Container cleanup	Automatic on remove	Automatic on remove
Keep container	`--keep-container` flag	Not supported

One-Liner Commands

# Create sandboxed session
aoe add --sandbox .

# Create sandboxed session with custom image
aoe add --sandbox-image myregistry/custom:v1 .

# Create and launch sandboxed session
aoe add --sandbox -l .

# Remove session (auto-cleans container)
aoe remove <session>

# Remove session but keep container
aoe remove <session> --keep-container

Note: In the TUI, the sandbox checkbox only appears when Docker is available on your system.

Default Configuration

[sandbox]
enabled_by_default = false
default_image = "ghcr.io/njbrake/aoe-sandbox:latest"
auto_cleanup = true
cpu_limit = "4"
memory_limit = "8g"
environment = ["ANTHROPIC_API_KEY"]

Note: YOLO mode (skip permission prompts) is now configured under [session] instead of [sandbox], since it works with or without Docker sandboxing. See [session] yolo_mode_default in the configuration guide.

Configuration Options

Option	Default	Description
`enabled_by_default`	`false`	Auto-enable sandbox for new sessions
`default_image`	`ghcr.io/njbrake/aoe-sandbox:latest`	Docker image to use
`auto_cleanup`	`true`	Remove containers when sessions are deleted
`cpu_limit`	(none)	CPU limit (e.g., “4”)
`memory_limit`	(none)	Memory limit (e.g., “8g”)
`environment`	`[]`	Env var names to pass through from host
`environment_values`	`{}`	Env vars with explicit values to inject (see below)
`volume_ignores`	`[]`	Directories to exclude from the project mount via anonymous volumes
`extra_volumes`	`[]`	Additional volume mounts
`mount_ssh`	`false`	Mount `~/.ssh/` read-only into containers
`default_terminal_mode`	`"host"`	Paired terminal location: `"host"` (on host machine) or `"container"` (inside Docker)

Volume Mounts

Automatic Mounts

Host Path	Container Path	Mode	Purpose
Project directory	`/workspace`	RW	Your code
`~/.gitconfig`	`/root/.gitconfig`	RO	Git config
`~/.ssh/`	`/root/.ssh/`	RO	SSH keys
`~/.config/opencode/`	`/root/.config/opencode/`	RO	OpenCode config

Shared Agent Config Directories

AOE shares your host agent credentials with sandboxed containers so agents can authenticate without re-login. This works for all supported agents: Claude Code, OpenCode, Codex, Gemini, Vibe, and Cursor.

Rather than bind-mounting your actual host config directories (which would let container writes modify your host files), AOE creates a shared sandbox directory per agent:

For each agent whose host config directory exists (e.g. ~/.claude/, ~/.codex/, ~/.gemini/, ~/.local/share/opencode/, ~/.vibe/, ~/.cursor/), AOE syncs credential files into a shared sandbox directory.
The sandbox directory is mounted read-write into all containers that use that agent.
Containers can read credentials and write runtime state freely without affecting your host config.
In-container changes (e.g. permission approvals, settings tweaks) persist across sessions since all containers share the same directory.
Sandbox directories are never automatically deleted — not even when you remove all sandboxed sessions. This is intentional: if you later create a new sandbox, your accumulated state (permission approvals, settings) is still there so you don’t have to set things up again.

If an agent’s config directory doesn’t exist on the host (e.g. you haven’t installed that agent locally), AOE still creates the sandbox directory and mounts it. This way the agent can write auth and state inside the container and have it persist across sessions.

What gets synced:

Top-level files from each agent’s config directory (auth tokens, credentials, config files). Subdirectories are skipped by default to keep the sandbox dir small.
Specific subdirectories listed per agent (e.g. Claude Code’s plugins/ and skills/ are copied recursively so extensions work inside the container).
Seed files (write-once) where needed (e.g. Claude Code gets a minimal hasCompletedOnboarding flag to skip the first-run wizard). Seed files are only written if they don’t already exist, so any changes made inside the container are preserved.

Platform-specific authentication:

Linux: Credential files (e.g. .credentials.json) live directly in the agent’s config directory and are synced automatically.
macOS: Some agents store credentials in the macOS Keychain rather than on disk. AOE extracts these at sync time and writes them as files in the sandbox directory so the container can authenticate. For example, Claude Code OAuth tokens are extracted from the Keychain and written as .credentials.json. If no Keychain entry is found (e.g. you authenticate via ANTHROPIC_API_KEY), the sandbox dir still works — just pass your API key via the environment config.

Credential refresh: Host credentials are re-synced every time a session starts (not just on first creation). If you re-authenticate on the host or update credentials, the next session start picks up the changes. Container-specific state (permission approvals, runtime config) is not overwritten during refresh.

Sandbox directory location: Each agent’s shared sandbox directory lives inside that agent’s own config directory:

~/.claude/sandbox/                    # Claude Code (shared by all containers)
~/.codex/sandbox/                     # Codex (shared by all containers)
~/.gemini/sandbox/                    # Gemini (shared by all containers)
~/.local/share/opencode/sandbox/      # OpenCode (shared by all containers)
~/.vibe/sandbox/                      # Vibe (shared by all containers)
~/.cursor/sandbox/                    # Cursor (shared by all containers)

Deleting an agent’s config directory (e.g. rm -rf ~/.codex/) removes everything related to that agent, including the sandbox directory. To reset just the sandbox state for an agent, delete its sandbox/ subdirectory (e.g. rm -rf ~/.claude/sandbox/) — it will be re-created on the next session start.

Upgrading from named volumes: Older versions of AOE stored agent auth in named Docker volumes (e.g. aoe-claude-auth). On upgrade, AOE automatically migrates data from these volumes into the sandbox directories. The old volumes are intentionally not deleted — you can remove them manually once you’ve confirmed everything works:

docker volume rm aoe-claude-auth aoe-opencode-auth aoe-codex-auth aoe-gemini-auth aoe-vibe-auth

Container Naming

Containers are named: aoe-sandbox-{session_id_first_8_chars}

Example: aoe-sandbox-a1b2c3d4

How It Works

Session Creation: When you add a sandboxed session, aoe records the sandbox configuration
Container Start: When you start the session, aoe creates/starts the Docker container with appropriate volume mounts
tmux + docker exec: Host tmux runs docker exec -it <container> <tool> (claude, opencode, vibe, codex, gemini, or cursor)
Cleanup: When you remove the session, the container is automatically deleted

Environment Variables

These terminal-related variables are always passed through for proper UI/theming:

TERM, COLORTERM, FORCE_COLOR, NO_COLOR

Pass additional variables (like API keys) through containers by adding them to config:

[sandbox]
environment = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY"]

These variables are read from your host environment and passed to containers (in addition to the terminal defaults above).

Sandbox-Specific Values (`environment_values`)

Use environment_values to inject env vars with values that AOE manages directly, independent of your host environment. This is useful for giving sandboxes credentials that differ from (or don’t exist on) the host:

[sandbox.environment_values]
GH_TOKEN = "ghp_sandbox_scoped_token"
CUSTOM_API_KEY = "sk-sandbox-only-key"

Values starting with $ are read from a host env var instead of being used literally. This lets you store the actual secret in your shell profile rather than in the AOE config file:

[sandbox.environment_values]
GH_TOKEN = "$AOE_GH_TOKEN"   # reads AOE_GH_TOKEN from host, injects as GH_TOKEN

# In your .bashrc / .zshrc
export AOE_GH_TOKEN="ghp_sandbox_scoped_token"

If the referenced host env var is not set, the entry is silently skipped.

To use a literal value starting with $, double it: $$LITERAL is injected as $LITERAL.

Available Images

AOE provides two official sandbox images:

Image	Description
`ghcr.io/njbrake/aoe-sandbox:latest`	Base image with Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, git, ripgrep, fzf
`ghcr.io/njbrake/aoe-dev-sandbox:latest`	Extended image with additional dev tools

Dev Sandbox Tools

The dev sandbox (aoe-dev-sandbox) includes everything in the base image plus:

Rust (rustup, cargo, rustc)
uv (fast Python package manager)
Node.js LTS (via nvm, with npm and npx)
GitHub CLI (gh)

To use the dev sandbox:

# Per-session
aoe add --sandbox-image ghcr.io/njbrake/aoe-dev-sandbox:latest .

# Or set as default in ~/.agent-of-empires/config.toml
[sandbox]
default_image = "ghcr.io/njbrake/aoe-dev-sandbox:latest"

Custom Docker Images

The default sandbox image includes Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, git, and basic development tools. For projects requiring additional dependencies beyond what the dev sandbox provides, you can extend either base image.

Step 1: Create a Dockerfile

Create a Dockerfile in your project (or a shared location):

FROM ghcr.io/njbrake/aoe-sandbox:latest

# Example: Add Python for a data science project
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip3 install --break-system-packages \
    pandas \
    numpy \
    requests

Step 2: Build Your Image

# Build locally
docker build -t my-sandbox:latest .

# Or build and push to a registry
docker build -t ghcr.io/yourusername/my-sandbox:latest .
docker push ghcr.io/yourusername/my-sandbox:latest

Step 3: Configure AOE to Use Your Image

Option A: Set as default for all sessions

Add to ~/.agent-of-empires/config.toml:

[sandbox]
default_image = "my-sandbox:latest"
# Or with registry:
# default_image = "ghcr.io/yourusername/my-sandbox:latest"

Option B: Use per-session via CLI

aoe add --sandbox-image my-sandbox:latest .

Worktrees and Sandboxing

When using git worktrees with sandboxing, there’s an important consideration: worktrees have a .git file that points back to the main repository’s git directory. If this reference points outside the sandboxed directory, git operations inside the container may fail.

The Problem

With the default worktree template (../{repo-name}-worktrees/{branch}):

/projects/
  my-repo/
    .git/                    # Main repo's git directory
    src/
  my-repo-worktrees/
    feature-branch/
      .git                   # FILE pointing to /projects/my-repo/.git/...
      src/

When sandboxing feature-branch/, the container can’t access /projects/my-repo/.git/.

The Solution: Bare Repo Pattern

Use the linked worktree bare repo pattern to keep everything in one directory:

/projects/my-repo/
  .bare/                     # Bare git repository
  .git                       # FILE: "gitdir: ./.bare"
  main/                      # Worktree (main branch)
  feature/                   # Worktree (feature branch)

Now when sandboxing feature/, the container has access to the sibling .bare/ directory.

AOE automatically detects bare repo setups and uses ./{branch} as the default worktree path template, keeping new worktrees as siblings.

Quick Setup

# Convert existing repo to bare repo pattern
cd my-project
mv .git .bare
echo "gitdir: ./.bare" > .git

# Or clone fresh as bare
git clone --bare git@github.com:user/repo.git my-project/.bare
cd my-project
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin
git worktree add main main

See the Workflow Guide for detailed bare repo setup instructions.

Troubleshooting

Container killed due to memory (OOM)

Symptoms: Your sandboxed session exits unexpectedly, the container disappears, or you see “Killed” in the output. Running docker inspect <container> shows OOMKilled: true.

Cause: On macOS (and Windows), Docker runs inside a Linux VM with a fixed memory ceiling. Docker Desktop defaults to 2 GB for the entire VM. If a container tries to use more memory than the VM has available, the Linux OOM killer terminates it. This commonly happens with AI coding agents that load large language model contexts or process big codebases.

Fix:

Increase Docker Desktop VM memory: Open Docker Desktop, go to Settings > Resources > Advanced, increase the Memory slider (8 GB+ recommended for AI coding agents), then click Apply & Restart.
Set a per-container memory limit in your AOE config (~/.agent-of-empires/config.toml) so containers have an explicit allocation rather than competing for the VM’s total memory:
```
[sandbox]
memory_limit = "8g"
```
The per-container limit must be less than or equal to the Docker Desktop VM memory. If you set memory_limit = "8g" but your VM only has 4 GB, the container will still be OOM-killed.
Verify the fix: Start a new session and check the container’s limit:
```
docker stats --no-stream
```
The MEM LIMIT column should reflect your configured value.

Note: On Linux, Docker runs natively without a VM, so the memory ceiling is your host’s physical RAM. You typically only need memory_limit on Linux to prevent a single container from consuming all system memory.