Sandboxes

Isolated execution via Docker Desktop

A sandboxed agent runs inside a Docker container managed by Docker Desktop's sandbox feature. The container has its own filesystem, network stack, and process namespace. Even if the agent runs rm -rf /, your host is untouched.

cagent starts and manages the container automatically when you pick a sandbox agent. No manual docker run needed.

The -box suffix in Quick Entry

OScar's agent picker groups sandbox variants separately. By default four presets are available:

The suffix is configurable in Settings → General → Sandbox Suffix (default: -box). Change it if your cagent YAML uses a different naming convention.

Under the hood

When cagent runs a sandbox agent it starts a Docker container from a base image that includes common tools (git, curl, node, python, etc.). The agent's shell and filesystem tools execute inside the container, not on your host.

Your current working directory is bind-mounted into the container at /workspace by default — so the agent can read and write your project files while remaining contained.

# What the agent sees
/workspace/        → your project directory (bind mount)
/tmp/              → ephemeral, lost when session ends
~/.config/         → NOT mounted, agent can't read your host config

Auto-approving all tool calls

By default, cagent pauses before destructive tool calls and waits for approval. In sandbox mode you can enable yolo mode to auto-approve everything — safe because the container contains the blast radius.

cagent api agent-box.yaml --listen 127.0.0.1:8080 --yolo

With --yolo, the agent runs fully autonomously. Use this for batch tasks you've already reviewed or for CI-style pipelines where human interruption isn't practical.

Writing your own -box config

A sandbox agent YAML is identical to a normal agent YAML, but you name it with the -box suffix so OScar places it in the Sandboxes group.

# ~/.config/oscar/agents/my-agent-box.yaml
model: claude-sonnet-4-5
system: |
  You are working inside a Docker sandbox.
  You may run shell commands freely.
tools:
  - shell
  - filesystem
sandbox: true

The sandbox: true key tells cagent to wrap execution in a container. See the full option reference at docs.docker.com/ai/sandboxes.

Official Docker documentation

The Docker documentation covers sandbox configuration in depth, including custom base images, volume mounts, resource limits, and network policies.

→ Docker AI Sandboxes reference
→ cagent full configuration reference