mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 13:03:46 +00:00
35840facdd
Add ensureServer() to SandboxProvider interface to handle cases where the sandbox-agent server stops or goes to sleep. The SDK now calls this method after 3 consecutive health-check failures, allowing providers to restart the server if needed. Most built-in providers (E2B, Daytona, Vercel, Modal, ComputeSDK) implement this. Docker and Cloudflare manage server lifecycle differently, and Local uses managed child processes. Also update docs for quickstart, architecture, multiplayer, and session persistence; mark persist-* packages as deprecated; and add ensureServer implementations to all applicable providers. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
63 lines
2.5 KiB
Text
63 lines
2.5 KiB
Text
---
|
|
title: "Architecture"
|
|
description: "How the Sandbox Agent server, SDK, and agent processes fit together."
|
|
---
|
|
|
|
Sandbox Agent is a lightweight HTTP server that runs **inside** a sandbox. It:
|
|
|
|
- **Agent management**: Installs, spawns, and stops coding agent processes
|
|
- **Sessions**: Routes prompts to agents and streams events back in real time
|
|
- **Sandbox APIs**: Filesystem, process, and terminal access for the sandbox environment
|
|
|
|
## Components
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
CLIENT["Your App"]
|
|
|
|
subgraph SANDBOX["Sandbox"]
|
|
direction TB
|
|
SERVER["Sandbox Agent Server"]
|
|
AGENT["Agent Process<br/>(Claude, Codex, etc.)"]
|
|
SERVER --> AGENT
|
|
end
|
|
|
|
CLIENT -->|"SDK (HTTP)"| SERVER
|
|
```
|
|
|
|
- **Your app**: Uses the `sandbox-agent` TypeScript SDK to talk to the server over HTTP.
|
|
- **Sandbox**: An isolated runtime (local process, Docker, E2B, Daytona, Vercel, Cloudflare).
|
|
- **Sandbox Agent server**: A single binary inside the sandbox that manages agent lifecycles, routes prompts, streams events, and exposes filesystem/process/terminal APIs.
|
|
- **Agent process**: A coding agent (Claude Code, Codex, etc.) spawned by the server. Each session maps to one agent process.
|
|
|
|
## What `SandboxAgent.start()` does
|
|
|
|
1. **Provision**: The provider creates a sandbox (starts a container, creates a VM, etc.)
|
|
2. **Install**: The Sandbox Agent binary is installed inside the sandbox
|
|
3. **Boot**: The server starts listening on an HTTP port
|
|
4. **Health check**: The SDK waits for `/v1/health` to respond
|
|
5. **Ready**: The SDK returns a connected client
|
|
|
|
For the `local` provider, provisioning is a no-op and the server runs as a local subprocess.
|
|
|
|
### Server recovery
|
|
|
|
If the server process stops, the SDK automatically calls the provider's `ensureServer()` after 3 consecutive health-check failures. Most built-in providers implement this. Custom providers can add `ensureServer(sandboxId)` to their `SandboxProvider` object.
|
|
|
|
## Server HTTP API
|
|
|
|
See the [HTTP API reference](/api-reference) for the full list of server endpoints.
|
|
|
|
## Agent installation
|
|
|
|
Agents are installed lazily on first use. To avoid the cold-start delay, pre-install them:
|
|
|
|
```bash
|
|
sandbox-agent install-agent --all
|
|
```
|
|
|
|
The `rivetdev/sandbox-agent:0.3.2-full` Docker image ships with all agents pre-installed.
|
|
|
|
## Production-ready agent orchestration
|
|
|
|
For production deployments, see [Orchestration Architecture](/orchestration-architecture) for recommended topology, backend requirements, and session persistence patterns.
|