Docker Sandbox

When enabled, the bash tool executes commands inside an isolated Docker container. This adds a physical isolation layer on top of the tier system.

Configuration

[agent.sandbox]
enabled = true
mode = "docker"
image = "ubuntu:24.04"
memory_mb = 512
timeout_secs = 120
mount_workspace = true

What Gets Sandboxed

Only the bash tool uses the sandbox. Other tools (read, write, edit, glob, grep) operate directly on the filesystem since they have their own safety mechanisms.

When sandbox.enabled = true and a bash command is approved:

1. Ryvos creates a new Docker container from the configured image
2. The workspace is bind-mounted (read-only if configured)
3. The command runs inside the container
4. stdout/stderr is captured
5. The container is destroyed after execution

Isolation Properties

• Memory — Hard limit via Docker cgroups. OOM kills are reported as tool errors.
• Network — No network access by default. The container runs with --network=none.
• Filesystem — Container filesystem is ephemeral. Only the workspace mount persists.
• Timeout — Commands that exceed the timeout are killed and reported as errors.
• Processes — Standard Docker PID isolation.

Requirements

• Docker must be installed and the current user must be in the docker group
• Ryvos uses the bollard crate (Rust Docker client) — no shelling out

When to Enable

Enable sandboxing when:

• Running Ryvos in daemon mode (unattended)
• Working with untrusted input sources (Telegram, Discord, Slack)
• Using Ryvos on a production machine
• Executing commands from MCP servers you don't fully trust

Skip sandboxing when:

• Local development with interactive REPL
• You need commands to modify the host filesystem
• Docker is not available