Docker Sandboxing for AI Coding Agents

Why Sandbox AI Agents

When you tell an AI agent to "fix the build," it might run shell commands, modify configuration files, or install dependencies. Most of the time this is fine. But agents can make mistakes, especially when working with unfamiliar codebases or complex build systems.

Without isolation, a misguided rm -rf or an accidental write to /etc affects your host machine. Docker sandboxing limits the blast radius. Each agent runs in its own container with only the files and permissions it needs.

How aoe Docker Integration Works

Agent of Empires manages the full container lifecycle for each session. When you create a sandboxed session, aoe:

1. Starts a Docker container with your configured image
2. Mounts your project directory into the container
3. Forwards authentication (SSH keys, git credentials) so the agent can push and pull
4. Attaches a tmux session inside the container
5. Cleans up the container when the session ends

You interact with the agent the same way you would without Docker. The sandboxing is transparent.

Configuration Options

Custom Docker Images

Use any Docker image as your agent's environment. Need Node.js 20, Python 3.12, and Rust nightly? Build an image with those tools and set it as the default. aoe uses the image you configure for all new sandboxed sessions.

Volume Mounts

Beyond the project directory, you can mount additional directories into the container. Common examples include shared package caches (~/.npm, ~/.cargo/registry) to avoid re-downloading dependencies in every session.

Persistent Authentication

aoe can forward your SSH agent and git credentials into the container so agents can interact with private repositories. This is configured once and applies to all sandboxed sessions.

Configurable Directory Ignores

Control which directories are shared between the sandbox and host. You can configure ignore patterns to prevent large directories like node_modules or target from being synced, keeping the sandbox lightweight.

The Bare Repo Pattern

Docker sandboxing works especially well with git worktrees. The bare repo pattern means each agent gets its own worktree directory mounted into its own container. Multiple agents can work on different branches of the same repo, each fully isolated from the others.

This combination gives you parallel, isolated AI development without any of the agents stepping on each other's changes or corrupting shared state.

Getting Started with Docker Sandbox

Enable Docker sandboxing in the aoe settings TUI. You will need Docker installed and running on your machine. Then create a new session with sandboxing enabled:

aoe add --sandbox my-agent

See the sandbox reference for detailed configuration options.