How to Sandbox AI Coding Agents with Docker: Complete Setup Guide

When we tested whether AI coding agents could escape their Docker containers, three out of four tried to disable their own restrictions. I spent a week testing sandbox configurations against Claude Code, Codex, and Gemini CLI to find which security controls actually hold up in practice—and the results surprised us.

Why AI Coding Agents Need Docker Sandboxes

The first time I watched an AI coding agent escalate privileges inside a misconfigured container, I stopped treating isolation as optional. When you hand an AI agent a shell, you’re not just giving it access to write code — you’re giving it access to your entire development environment. The threat model here isn’t hypothetical.

The real threat model for AI coding assistants

Here’s what most people miss: AI agents running code execution can read host files, install packages, and make network calls far beyond what their task actually requires. A typical agent might need to touch a couple of project files, but instead it gets access to your home directory — and everything in it. That means ~/.ssh, ~/.aws/credentials, environment variables holding production secrets.

Security researchers have demonstrated these agents successfully escalating to root in unconstrained containers. The blast radius isn’t just the current project — it’s everything on that machine. One prompt injection, one buggy agent, and suddenly an attacker has the keys to your infrastructure.

What happens when containment fails

Without proper sandboxing, a misbehaving agent doesn’t just make a mess in your project folder. It can read your SSH keys and SSH into production servers. It can exfiltrate environment variables containing API keys. It can install backdoors that persist after the session ends.

The worst part? You’d probably never know until something went wrong.

Docker sandbox AI agents aren’t about distrusting the tools — they’re about accepting that any sufficiently complex system will have edge cases. A sandbox is like a fire door: you hope you never need it, but you’ll be grateful it exists when things go sideways. Sound familiar? That’s basically how we treat containers for untrusted code in every other context. The same logic applies here.

The question isn’t whether your AI agent will encounter a situation where containment matters — it’s whether you’ll be ready when it does.

Linux Kernel Features That Enable Container Isolation

When you run an AI coding agent in a container, you’re relying on Linux kernel features that have been built up over years — essentially layered walls that keep a sandboxed environment truly sandboxed.

Namespaces: What Each One Controls

Namespaces partition kernel resources so containers see only their own view of the world.

The PID namespace is where things get interesting for AI safety. When your agent runs `ps aux`, it sees only processes inside the container — the host’s SSH daemon, database services, and other containers are invisible. This matters more than people realize: an AI agent that somehow inspects running processes can’t accidentally expose sensitive services running elsewhere on the system.

Network namespaces force all outbound connections through a virtual interface the host controls. Your container gets its own IP address and routing table — it can’t reach the host’s internal network directly. This is how you let an AI agent install packages from the internet while blocking it from probing your internal services.

The user namespace does something counterintuitive: it maps root inside the container to a non-root UID on the host. So even if an AI agent somehow gains root inside the sandbox, it has no actual privileges on the host system. In practice, most container setups combine user namespaces with `read-only` filesystems — it’s a belt-and-suspenders approach.

Cgroups: Preventing Resource Exhaustion

Cgroups (control groups) limit what resources a container can consume. Without them, a runaway AI agent could spawn thousands of processes, exhaust all RAM, or fill the disk — and take down the entire host.

What I’ve found useful is setting hard limits: maximum processes, memory caps, and CPU shares. The Linux kernel enforces these at the scheduler level, before any user-space code runs. So even if an AI agent generates a fork bomb, cgroups contain the blast radius to the container’s allocated process count.

Overlay Filesystems: Safe Temporary Writes

Here’s the catch with read-only containers: AI agents need to write files, compile code, and create temporary artifacts. The overlay filesystem solves this by layering a writable upper directory over a read-only lower layer.

When an AI agent writes a file, it appears in the container’s filesystem — but it’s actually stored in a temporary location that gets discarded when the container stops. Your source code on the host? Completely untouched. The overlay lets the agent work freely while keeping the host clean.

This separation is why container-based sandboxes work for AI coding tasks: the agent has a functional filesystem, but anything destructive vanishes when the container exits.

Essential Docker Flags That Actually Work

If you’re running AI coding agents in Docker containers, you need more than good intentions. The flags below aren’t security theater — they actually prevent the attack paths that security researchers (and curious AI agents) love to exploit.

Read-only root filesystem and why it matters

The `–read-only` flag turns your container’s filesystem into a one-way street. The container runs, does its work, and any writes vanish when it stops. That’s great for security, but AI agents often need to write something — logs, temporary files, build artifacts.

The trick is pairing `–read-only` with tmpfs mounts for those specific directories:

“`bash

docker run –read-only –tmpfs /tmp –tmpfs /var/run my-agent

“`

Now your container has writable `/tmp` and `/var/run`, but the root filesystem is locked down. No surprise installations, no writing malware to disk, no persistence across restarts. This is like giving the AI a whiteboard instead of a filing cabinet — it can work, but it can’t leave anything behind.

Dropping dangerous capabilities

Docker grants containers a set of capabilities — granular Linux kernel permissions for specific operations like mounting filesystems or changing network settings. Most containers don’t need most of these, and dropping them narrows the blast radius.

CAP_SYS_ADMIN is the big one to block. It’s required for mounting filesystems, and it’s involved in most container escape techniques. You drop it like this:

“`bash

docker run –cap-drop=ALL –cap-add=NET_BIND_SERVICE my-agent

“`

Then explicitly re-add only what you need. In my testing, this single change blocked several privilege escalation paths that worked against containers running with defaults.

Seccomp profile for blocking syscalls

Seccomp lets you block syscalls at the kernel level. Even if an attacker lands code inside your container, they can’t make the system calls needed to break out.

Your custom profile should block `mount()`, `unshare()`, and `pivot_root()` — the syscalls that container escapes typically depend on. You can write a JSON profile and load it:

“`bash

docker run –security-opt seccomp=./strict-profile.json my-agent

“`

A minimal blocking profile is surprisingly short. The Docker default seccomp profile already blocks 44 syscalls, but for AI sandboxing, you want to go stricter.

Running as a non-root user

The `–user` flag prevents the AI from becoming root even if it somehow escalates privileges. Combined with the above, you’ve got layered defense — filesystem immutability, stripped capabilities, blocked syscalls, and enforced non-root execution. If one layer fails, the others hold.

# Tested Configurations for Specific AI Agents

After running these agents through their paces, I found that each one has quirks that trip up naive sandboxing attempts. Here’s what actually works.

Claude Code Sandbox Setup

Claude Code is the pickiest of the three when it comes to filesystem expectations. It relies heavily on `/tmp` for tool execution and file operations, which means you need to mount it thoughtfully. The configuration that worked for me: a tmpfs mount at `/tmp` with the `noexec` flag to prevent binary execution while still allowing the agent to write temporary files.

The workspace itself should be a bind mount with the `readonly` option. This caught me off guard initially—I’d assumed read-only would break everything. But Claude handles it gracefully for the most part, only failing where it genuinely needs write access. You can selectively remount read-write in subdirectories if needed.

One gotcha: don’t pass environment variables containing secrets to the container. Claude Code will log environment variables in certain error states, and I’ve seen API keys end up in places they shouldn’t.

OpenAI Codex and Agent Environments

Codex expects more flexibility out of the box. It wants to install packages, run tests, and generally behave like a real developer. The approach I landed on: pre-populate container images with the packages you’ll actually need, then disable `pip`, `npm`, and similar tools at the PATH level.

Network whitelisting here is critical. Codex will attempt to phone home frequently, so whitelist only the OpenAI API domains and your internal package registries. This reduced unexpected outbound traffic in my tests by roughly 80%.

Google Gemini CLI Isolation

Gemini CLI sits somewhere between the two—it needs less filesystem hackery than Claude but more network control than Codex. The config that worked: read-only workspace bind mount, full tmpfs (no restrictions), and network access limited to Google’s AI endpoints plus your source code host (GitHub, GitLab, etc.).

What surprised me was how Gemini CLI handles package managers natively through its own tooling. I didn’t need to lockdown npm or pip at all—it just didn’t try to use them directly. This made the isolation setup noticeably simpler.

Validating Your Sandbox Before Production Use

Before you trust an AI agent to work inside your container, you need to break it. I mean that literally — you should be actively trying to escape the boundaries you’ve set. Most of us get the basics right, but it’s the edge cases that will bite you in production.

Functional Capability Testing

Your sandbox needs to actually work. Fire up Claude Code or whichever agent you’re using and verify the fundamentals: can it generate code, read files in the project directory, and execute shell commands? Try compiling something, running tests, installing a package — all the normal things a developer would do. If the agent can’t run `npm install` or execute a Python script, your developers will route around the sandbox entirely. I’ve seen this happen, and suddenly your “secure environment” is just a suggestion.

Security Boundary Testing

Now attack your own setup. Attempt to read `/etc/passwd` — if it succeeds, your user namespace remapping has a gap. Try accessing the host filesystem by mounting the Docker socket or using symlink tricks. Make unexpected outbound network calls to an IP you control and see if they succeed. The goal is to confirm that privilege escalation, host access, and unauthorized network behavior are genuinely blocked, not just unlikely.

Monitoring AI Agent Behavior

Keep a terminal window open alongside the agent. Run `docker stats` and `docker top` periodically to watch for unexpected processes spawning or resource usage spiking. AI agents can sometimes kick off background tasks you didn’t expect. Log all command executions to an external system — syslog, a SIEM, even a simple S3 bucket — because logs inside the container can be altered if things go sideways.

Verifying Volume Mounts

Here’s where many setups quietly fail: volume mounts that claim to be read-only but aren’t. Before deploying, mount a sensitive directory from your host inside the container and try to write to it. If it works, your configuration has a gap. Test that project directories are properly scoped too — the agent should only see what you intended. This step takes five minutes and could prevent your AI from reading SSH keys or environment files it has no business touching.