Architecture Overview

agents-sandbox is a Docker-backed sandbox control plane. Each sandbox is a Docker container with a dedicated network. A local daemon manages sandbox lifecycle via gRPC over a Unix domain socket, with CLI, Go SDK, and Python SDK as client entry points.

System Architecture

Components

Component	Role
Clients	CLI (reference), Go SDK (usage), and Python SDK (usage) — all talk to the daemon via gRPC over a Unix domain socket.
AgentsSandbox Daemon	Single-writer local process that serves gRPC, manages sandbox lifecycle, and coordinates async operations. See Configuration Reference.
Sandbox	A Docker container with a dedicated network, representing an isolated execution environment. See Sandbox Container Lifecycle.
Control Service	Core logic: request validation, state transitions, event ordering, restart recovery. See Sandbox Container Lifecycle.
Persistence Layer	bbolt-backed ID registry and event store for crash recovery. See Daemon State Management.
Docker Daemon	Runtime backend for container, network, and exec operations. See Container Dependency Strategy.

Request Flow

1. Client sends a gRPC request (create, stop, delete, exec, etc.).
2. Service validates input synchronously and returns an accepted handle.
3. Daemon converges asynchronously via Docker Engine API and emits ordered events.
4. Clients optionally wait by subscribing to the event stream. See Protocol Design Principles.

Key Design Decisions

• Accepted != completed — slow operations return after acceptance, not completion. See Protocol Design Principles.
• Exec output redirected to disk — stdout/stderr go to bind-mounted host files, keeping output durable across daemon restarts. See Sandbox Container Lifecycle.
• Historical IDs reserved persistently — prevents accidental ID reuse after restart. See Daemon State Management.
• Single Docker Engine API client — no CLI subprocess shelling. See Container Dependency Strategy.
• Filesystem ingress split by semantics — mounts, copies, and builtin_tools have different security and lifecycle behavior. See Container Dependency Strategy.
• Per-sandbox network isolation — each sandbox gets a dedicated Docker network; no cross-sandbox traffic, no host network, no Docker socket exposure. See Isolation and Security.

External Dependencies

• Docker Engine (container runtime)
• Go (daemon and SDK)
• Python + grpcio (Python SDK)
• Protobuf / gRPC (wire contract, see Development Guide for proto generation)