← Back to DevBytes
Docker July 20, 2026 10 min read

Docker for AI Agents: Isolation, Resource Limits, and Best Practices

Docker as an Isolation Layer for AI Agents

AI agents—software powered by large language models that can reason, plan, and execute actions—often need to run arbitrary code, access the file system, make network calls, and interact with external tools. Giving an agent unrestricted access to your host machine is a recipe for disaster: a buggy or malicious prompt could delete files, consume all CPU cycles, or leak sensitive data.

Docker provides lightweight, fast-starting, and highly configurable sandboxes that give each agent its own isolated environment. You can restrict CPU, memory, disk I/O, network access, and even the set of Linux capabilities available inside the container. This turns Docker into a safe execution layer for AI agents, whether you’re building a single‑agent prototype or a multi‑tenant platform that runs thousands of agent sessions per hour.

What Makes Docker Suitable for AI Agents

Why Isolation and Resource Limits Matter

When an AI agent runs code generated by an LLM, you are essentially running untrusted, dynamically‑produced instructions. Even with careful prompt engineering, the model may occasionally emit dangerous commands, infinite loops, or memory‑hungry operations. Without isolation:

Resource limits ensure that a runaway agent cannot degrade the experience of other users or bring down your entire platform. They also enable fair billing when you charge by compute usage—you can guarantee an agent never exceeds its allocated slice of CPU and memory.

Setting Up Docker for AI Agents

Prerequisites

Install Docker Engine (version 20.10 or later) and ensure your user has permissions to run docker commands. For production, consider Docker‑compatible runtimes like containerd or cri‑o if you use Kubernetes. The examples assume a Linux host, but the principles apply to Docker Desktop on Windows/macOS as well.

Building a Minimal Agent Image

Start with the smallest base image that fits your agent’s runtime. For a Python agent, python:3.12-slim is a good balance: it includes essential libraries but avoids unnecessary packages that increase the attack surface. Below is a sample Dockerfile that prepares a sandbox for an agent that needs to run shell commands and Python scripts. 


FROM python:3.12-slim

# Create a non-root user with a home directory
RUN useradd --create-home --shell /bin/bash agent

# Install only the tools the agent is allowed to use
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Set up a working directory owned by the agent
WORKDIR /home/agent/workspace
RUN chown -R agent:agent /home/agent/workspace

# Copy any startup scripts or tool wrappers
COPY allowed_scripts/ /home/agent/allowed_scripts/
RUN chmod +x /home/agent/allowed_scripts/*

# Switch to non-root user
USER agent

# Start a simple shell by default; the agent orchestrator will override the command
CMD ["/bin/bash"]

This image deliberately avoids installing compilers, package managers, or admin tools that an agent might abuse. By running as agent, even if the agent executes a destructive command, it can only affect files within its own workspace or the explicitly mounted volumes.

Running an Agent Container with Resource Limits

When launching a container for an agent session, you can attach precise limits via docker run flags. The example below starts a container that: 


docker run -d --rm \
  --name agent-session-123 \
  --cpus="0.5" \
  --memory="256m" \
  --memory-swap="256m" \
  --pids-limit=20 \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --tmpfs /home/agent/workspace:rw,noexec,size=128m \
  --mount type=bind,source=/host/agent-data/123,destination=/home/agent/workspace/data,readonly \
  --cap-drop=ALL \
  --cap-add=DAC_OVERRIDE \
  --network=isolated-agent-net \
  my-agent-image:latest \
  /bin/bash -c "./start-agent.sh"

Explanation of key flags:

Using Docker Compose for Multi-Agent Orchestration

When you need to run multiple agents that communicate (for example, a planner agent and a code‑executor agent), Docker Compose simplifies configuration. Below is a docker-compose.yml that defines two services with distinct resource profiles and a shared isolated network. 


version: "3.9"
services:
  planner-agent:
    image: planner-agent:latest
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=32m
    deploy:
      resources:
        limits:
          cpus: '0.3'
          memory: 128M
    cap_drop:
      - ALL
    cap_add:
      - DAC_OVERRIDE
    networks:
      - agent-net

  executor-agent:
    image: executor-agent:latest
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=64m
      - /workspace:rw,noexec,size=256m
    deploy:
      resources:
        limits:
          cpus: '0.7'
          memory: 512M
    cap_drop:
      - ALL
    cap_add:
      - DAC_OVERRIDE
      - NET_BIND_SERVICE   # only if the executor needs to bind a port
    networks:
      - agent-net

networks:
  agent-net:
    driver: bridge
    internal: true   # prevents containers from reaching the internet
    # To allow controlled outbound, remove internal:true and attach a proxy.

With docker compose up, both agents start in a private network that cannot access the internet. The executor gets more CPU and memory because it runs the actual code, while the planner is intentionally starved to limit its impact.

Programmatic Container Management with Docker SDK

Most AI agent platforms need to create and destroy containers on‑the‑fly from code. The official Docker SDK for Python (docker package) makes this straightforward. First install it: 

pip install docker

Then use it to spin up an agent session with the same resource limits: 


import docker
import uuid

client = docker.from_env()

def run_agent_session(agent_image, workspace_host_dir, input_data_path):
    session_id = str(uuid.uuid4())
    container_name = f"agent-{session_id}"

    # Define resource constraints
    cpu_limit = 0.5          # 0.5 cores
    mem_limit = "256m"
    memswap_limit = "256m"
    pids_limit = 20

    # Mounts: read-only input data, tmpfs for scratch space
    mounts = [
        docker.types.Mount(
            type="bind",
            source=input_data_path,
            target="/home/agent/input",
            read_only=True
        ),
        # tmpfs mounts are defined in container configuration separately
    ]

    container = client.containers.run(
        image=agent_image,
        name=container_name,
        detach=True,
        auto_remove=True,            # --rm equivalent
        read_only=True,
        cap_drop=["ALL"],
        cap_add=["DAC_OVERRIDE"],
        cpu_count=cpu_limit,         # docker-py uses cpu_count for --cpus
        mem_limit=mem_limit,
        memswap_limit=memswap_limit,
        pids_limit=pids_limit,
        mounts=mounts,
        tmpfs={
            "/tmp": "rw,noexec,nosuid,size=64m",
            "/home/agent/workspace": "rw,noexec,size=128m"
        },
        network="isolated-agent-net",
        command=["/bin/bash", "-c", "/home/agent/start.sh"]
    )

    return container.id, container_name

# Stop and clean up after the session completes
def terminate_session(container_id):
    container = client.containers.get(container_id)
    container.stop(timeout=10)   # graceful stop with SIGTERM, then SIGKILL
    # auto_remove handles deletion, but you can also call container.remove(force=True)

This approach integrates cleanly into any Python‑based orchestrator. You can monitor the container’s logs via container.logs(), and even stream them in real‑time. Always set auto_remove=True to prevent container corpses from piling up.

Best Practices for Secure and Efficient Agent Sandboxing

1. Use Minimal Base Images

Avoid full‑fat OS images like ubuntu:latest. Prefer python:3.12-slim or alpine‑based images. Smaller images reduce the attack surface, start faster, and use less disk space. Remove package caches (/var/lib/apt/lists/*) after installation.

2. Always Run as Non‑Root

Create a dedicated user inside the image and switch to it with USER. Even if the agent breaks out of its application, it cannot modify system binaries or access host‑mounted sensitive paths unless explicitly allowed.

3. Set Resource Limits on Every Container

Never run an agent container without --cpus, --memory, and --pids-limit. Use swap limits to prevent thrashing. Test what happens when limits are hit—does your orchestration layer detect OOM kills and retry gracefully?

4. Make the Root Filesystem Read‑Only

Enable --read-only and provide writable scratch space only through tmpfs or carefully chosen volume mounts. This prevents agents from installing malware or modifying system configuration. For applications that need to write to a specific directory (e.g., a cache), mount a dedicated tmpfs with noexec to block binary execution.

5. Drop Capabilities Aggressively

Start with --cap-drop=ALL and add back only what’s truly needed. Common candidates to keep: DAC_OVERRIDE (for file access in user‑owned directories), NET_BIND_SERVICE (only if the agent must bind to a low port). Never give SYS_ADMIN, SYS_PTRACE, or NET_RAW unless you have a very specific, audited reason.

6. Apply Seccomp and AppArmor Profiles

Docker’s default seccomp profile already blocks many dangerous system calls, but you can create a custom profile to further restrict clone, mount, or ptrace. Similarly, an AppArmor profile can confine the container’s file access patterns. This adds a kernel‑level safety net even if Docker’s other controls are misconfigured.

7. Isolate Networking

Attach agent containers to an internal network if they don’t need internet access. When outbound calls are necessary, route them through an egress proxy that filters destinations and logs requests. Never expose agent containers to the host network or to sensitive internal services without strict firewall rules.

8. Mount Volumes with Extreme Care

Only bind‑mount the exact files or directories the agent requires. Prefer read‑only mounts for input data. If an agent needs to persist output, write it to an object store (S3, etc.) through a controlled API rather than mounting a persistent host volume directly.

9. Clean Up Containers Immediately

Use --rm and auto_remove=True so containers are destroyed as soon as they stop. Implement a garbage‑collection routine that kills containers that exceed a maximum runtime (timeout). A hung agent should never linger and consume resources indefinitely.

10. Implement Health Checks and Logging

Embed a HEALTHCHECK instruction in your images that verifies the agent’s core process is responsive. Stream container logs to your monitoring stack to detect anomalies like repeated restarts, memory‑limit breaches, or suspicious syscall patterns.

11. Use Docker Content Trust and Image Scanning

Sign your images and verify signatures at pull time. Regularly scan images for known vulnerabilities with tools like Trivy or Docker Scout. An agent sandbox is only as secure as the software inside it—an outdated library can be exploited even within a restricted container.

12. Test Your Limits Under Load

Run chaos‑engineering experiments: simulate a fork bomb, a memory leak, and a CPU‑burning agent. Confirm that limits kick in as expected, that your orchestrator receives the exit code (137 for OOM, for example), and that no other containers are affected. Tune the limits based on real‑world agent workloads.

Conclusion

Docker gives you a powerful, fine‑grained sandbox that is perfectly suited for running AI agents safely at scale. By combining resource limits, read‑only filesystems, non‑root users, capability dropping, and network isolation, you create an environment where agents can execute code and access tools without endangering your infrastructure. The practices outlined here—minimal images, strict limits, immediate cleanup, and continuous monitoring—are not just optional hardening; they are essential for any production system that allows LLM‑driven code execution. Start with a simple Dockerfile, layer on the security flags, and then automate the lifecycle with the Docker SDK. You’ll build a platform that is both powerful and resilient, ready to handle whatever instructions your AI agents come up with next.

— Ad —

Google AdSense will appear here after approval

← Back to all articles