Sandbox Mode

Run agents in an isolated Docker sandbox VM for enhanced security.

Overview

Sandbox mode runs the entire agent inside a disposable sandbox VM instead of directly on the host system. All shell, filesystem, and process activity happens inside that VM, so a misbehaving agent cannot touch files outside the mounted working directory or reach long-lived host state.

The backend is provided by the docker sandbox CLI plugin (ships with Docker Desktop) or the standalone sbx CLI if it is on PATH.

Usage

Enable sandbox mode with the --sandbox flag on the docker agent run command:

docker agent run --sandbox agent.yaml

docker-agent launches a sandbox VM, copies itself into it, mounts the current working directory, and re-runs the agent from inside.

Flags

# Use a custom template image
docker agent run --sandbox --template myorg/custom-agent-template:latest agent.yaml

# Force the docker sandbox backend even if sbx is on PATH
docker agent run --sandbox --sbx=false agent.yaml

Example

# agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Agent with sandboxed shell
    instruction: You are a helpful assistant.
    toolsets:
      - type: shell

docker agent run --sandbox agent.yaml

How It Works

1. --sandbox tells docker-agent to prefer the sbx CLI (if available and --sbx is true), otherwise it falls back to docker sandbox.
2. A new sandbox VM is created from the image passed via --template.
3. The current working directory is mounted into the VM; the agent binary is copied in.
4. All tools (shell, filesystem, background jobs, etc.) run inside the VM.
5. When the session ends, the sandbox VM is stopped and removed.