Sandboxing: Why and How

What You'll Need

⏱ Time: 15 minutes  |  📋 Tasks:

• Docker Desktop installed (or access to a machine where Docker runs)
• Understanding of the agent loop from Lesson 1
• A terminal open

The Seatbelt

Here's a hard truth about autonomous agents: they will make mistakes. Not every time, but often enough that you need to plan for it. The agent might delete a file you needed, run a command that costs money, call an API in a loop until your credit card screams, or follow a rabbit hole of reasoning that wastes hundreds of tokens on nothing useful.

This is not the agent being malicious. It's the agent being wrong. Language models hallucinate. They misinterpret goals. They get trapped in loops. They call the right tool with the wrong argument. When we're sitting next to the agent, we catch these mistakes quickly. When the agent runs without us, we don't see them until we come back.

Sandboxing is what makes autonomy safe. It doesn't prevent mistakes — no tool can do that. It contains them. A sandbox ensures that when the agent messes up, the damage stays inside a controlled zone and doesn't spread to the rest of your system.

What a Sandbox Restricts

A sandbox wraps the agent with boundaries. These boundaries cover four areas:

Different sandboxing approaches enforce these boundaries at different levels. Let's look at the most common one first: Docker.

Walkthrough: Docker Sandbox

Docker is the most common way to sandbox autonomous agents. A Docker container is a lightweight, isolated environment with its own file system, network, and process space. The agent sees only what we put inside — nothing more.

Step 1: Create a Dockerfile

This Dockerfile creates a minimal environment with Python and common agent tools:

FROM python:3.12-slim

# Install agent dependencies
RUN pip install --no-cache-dir requests beautifulsoup4

# Create a working directory the agent can use
WORKDIR /workspace

# Set a non-root user so the agent doesn't run as root
RUN useradd -m agent && chown agent:agent /workspace
USER agent

Step 2: Build the image

docker build -t agent-sandbox .

Step 3: Run with restricted mounts

Mount only the directories the agent needs. Use :ro for read-only mounts if the agent only needs to read:

docker run --rm \
  -v /path/to/input-data:/workspace/input:ro \
  -v /path/to/output:/workspace/output \
  --network none \
  --memory 2g \
  --cpus 2 \
  agent-sandbox

Let's break down what each flag does:

• --rm — Delete the container when it finishes. No lingering state.
• -v — Mount specific directories. :ro means read-only for input data. The output directory is writable so the agent can save results.
• --network none — No network access at all. The agent can't call any APIs, period.
• --memory 2g — Max 2 GB of RAM. The agent can't eat your machine.
• --cpus 2 — Max 2 CPU cores.

Step 4: Run the agent inside

Now we tell the agent harness to use this container. Most harnesses (Opencode, Claude Code CLI) support a --sandbox or --container flag, or a config option that points to the Docker image:

# Example: run an agent task inside the sandbox container
hermes run --sandbox agent-sandbox --task "organize input files by type"

Non-Docker Options

Docker isn't the only way to sandbox. Two alternatives work well for simpler setups:

Option 1: Limited User Account

Create a dedicated user on your machine with restricted permissions. The agent runs as that user and can only read/write files the user owns. This is less isolated than Docker — the agent can still see other processes, consume system resources, and access any file the user can access — but it's quick to set up and doesn't require Docker.

# Linux / macOS
sudo useradd -m agent-worker
sudo -u agent-worker hermes run --task "process data"

Option 2: Temp Directory Workspace

Point the agent to a temporary directory that you create fresh for each task. When the task is done, delete the directory. This is the lightest sandbox: it protects your file system from accidental writes but does nothing to control network access or resource usage.

# Create a fresh workspace
WORKDIR=$(mktemp -d)
cd "$WORKDIR"
hermes run --task "generate report"

# Clean up when done
rm -rf "$WORKDIR"

Compare the Approaches

Deliverable: Sandbox Configuration Checklist

Before you run any autonomous agent, go through this checklist. Copy it, print it, stick it on your wall — whatever works:

Try It

Build the Dockerfile from this lesson and run a container with --network none. Inside the container, try to run curl or ping. Watch it fail — that's the sandbox working.

Then mount a directory with :ro and try to write a file to it from inside the container. See the permissions error? That's containment in action. These exercises make the abstract concept concrete: the sandbox is real, the boundaries hold, and your system is safe.