Sandbox mode runs the entire agent inside a Docker container instead of directly on the host system. All tool operations — shell commands, file reads and writes, network access — happen inside the container, limiting the potential impact of unintended or malicious actions.
Sandbox mode requires Docker to be installed and running on the host system.
Enabling sandbox mode
Pass the --sandbox flag when running an agent:
docker agent run --sandbox agent.yaml
Write your agent config
A normal agent config. No special configuration is needed to support sandboxing:agents:
root:
model: openai/gpt-4o
description: Agent with sandboxed shell access
instruction: You are a helpful assistant with access to a sandboxed shell environment.
toolsets:
- type: shell
- type: filesystem
Run with --sandbox
Pass the flag at runtime:docker agent run --sandbox agent.yaml
How it works
Container launch
docker-agent starts a Docker container when the session begins.
Workspace mount
The current working directory is mounted into the container, giving the agent access to your project files.
Isolated execution
All tool operations (shell commands, file edits, network requests) execute inside the container, not on the host.
Automatic cleanup
When the session ends, the container is automatically stopped and removed.
Shebang shorthand
Add a shebang line to your config file to make it directly executable with sandbox mode:
#!/usr/bin/env docker agent run --sandbox
agents:
root:
model: openai/gpt-4o
description: Agent running in a sandboxed environment
instruction: You are a helpful assistant with access to a sandboxed shell environment.
toolsets:
- type: shell
chmod +x sandbox_agent.yaml
./sandbox_agent.yaml
Limitations:
- The container starts fresh each session — there is no persistence between sessions
- Any files created inside the container (outside the mounted workspace) are lost when the session ends