Sandbox Mode

Run agents in an isolated Docker container for enhanced security.

Overview

Sandbox mode runs the entire agent inside a Docker container instead of directly on the host system. This provides an additional layer of isolation, limiting the potential impact of unintended or malicious commands.

Usage

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

docker agent run --sandbox agent.yaml

This runs the agent inside a Docker container with the current working directory mounted.

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. When --sandbox is specified, docker-agent launches a Docker container
2. The current working directory is mounted into the container
3. All agent tools (shell, filesystem, etc.) operate inside the container
4. When the session ends, the container is automatically stopped and removed

Combining with Permissions

For defense in depth, combine sandbox mode with permissions:

agents:
  root:
    model: openai/gpt-4o
    description: Secure development agent
    instruction: You are a helpful assistant.
    toolsets:
      - type: shell
      - type: filesystem

permissions:
  allow:
    - "shell:cmd=npm*"
    - "shell:cmd=node*"
    - "shell:cmd=ls*"
  deny:
    - "shell:cmd=sudo*"
    - "shell:cmd=curl*"
    - "shell:cmd=wget*"