# e2b-dev/runtime architecture

> Architecture diagram of the GitHub repository e2b-dev/runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e2b-dev/runtime
- Repository: https://github.com/e2b-dev/runtime
- Video tour (about a minute): https://gitdiagram.com/e2b-dev/runtime/video

## Overview

E2B Runtime provides isolated Firecracker sandboxes for AI-agent workloads. The main workflow runs from SDK or browser requests through the control-plane API or edge proxy to node orchestration and the VM’s envd service; the API also manages sandbox state and template builds. Supporting branches include authentication, dashboard APIs, persistent data, and observability. The README documents the service-level flows; sampled source confirms several service entry points and internal components, but does not establish every runtime connection.

Main entry points: [`packages/api/main.go`](https://github.com/e2b-dev/runtime/blob/main/packages/api/main.go) (Control API), [`packages/orchestrator/pkg/server/main.go`](https://github.com/e2b-dev/runtime/blob/main/packages/orchestrator/pkg/server/main.go) (Node orchestrator), [`packages/dashboard-api/main.go`](https://github.com/e2b-dev/runtime/blob/main/packages/dashboard-api/main.go) (Dashboard API), [`packages/envd/main.go`](https://github.com/e2b-dev/runtime/blob/main/packages/envd/main.go) (Guest agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_api["Control API<br/>[main.go]"]
  node_auth["Authentication<br/>[service.go]"]
end

subgraph group_execution["Sandbox execution"]
  node_orchestrator["Node orchestrator<br/>[main.go]"]
  node_api_orch_client["Orchestrator client<br/>[client.go]"]
  node_envd["Guest agent<br/>[main.go]"]
  node_process_api["Process service<br/>[handler.go]"]
  node_processes["Sandbox processes"]
  node_firecracker["Firecracker VM"]
end

subgraph group_templates["Template builds"]
  node_template_manager["Template manager"]
  node_template_storage["Template storage"]
end

subgraph group_edge["Traffic and dashboard"]
  node_dashboard["Dashboard API<br/>[main.go]"]
  node_proxy["Client proxy<br/>[main.go]"]
end

subgraph group_data["State and telemetry"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_object_storage[("Object storage")]
  node_clickhouse[("ClickHouse")]
  node_volumes[("Persistent volumes<br/>[volume_create.go]")]
end

node_sdk(("SDK / CLI"))
node_browser(("Browser"))

node_sdk -->|"REST requests"| node_api
node_api -->|"validates identity"| node_auth
node_api -->|"dispatches lifecycle"| node_api_orch_client
node_api_orch_client -->|"calls over gRPC"| node_orchestrator
node_api -->|"stores control data"| node_postgres
node_api -->|"uses cache"| node_redis
node_api -->|"exports events"| node_clickhouse
node_orchestrator -->|"runs microVMs"| node_firecracker
node_orchestrator -->|"reads and writes snapshots"| node_object_storage
node_orchestrator -->|"exports telemetry"| node_clickhouse
node_firecracker -->|"hosts agent"| node_envd
node_envd -->|"serves process API"| node_process_api
node_process_api -->|"runs commands"| node_processes
node_api -->|"manages builds"| node_template_manager
node_template_manager -.->|"builds from stored templates"| node_template_storage
node_template_storage -->|"fetches template data"| node_object_storage
node_browser -->|"sandbox URL traffic"| node_proxy
node_proxy -->|"routes sandbox traffic"| node_orchestrator
node_orchestrator -->|"forwards traffic"| node_envd
node_dashboard -->|"reads dashboard data"| node_postgres
node_dashboard -->|"authenticates requests"| node_auth
node_dashboard -->|"queries analytics"| node_clickhouse
node_api -.->|"manages volumes"| node_volumes

click node_api "https://github.com/e2b-dev/runtime/blob/main/packages/api/main.go"
click node_auth "https://github.com/e2b-dev/runtime/blob/main/packages/auth/pkg/auth/internal/service/service.go"
click node_template_manager "https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/template-manager/template_manager.go"
click node_dashboard "https://github.com/e2b-dev/runtime/blob/main/packages/dashboard-api/main.go"
click node_proxy "https://github.com/e2b-dev/runtime/blob/main/packages/client-proxy/main.go"
click node_orchestrator "https://github.com/e2b-dev/runtime/blob/main/packages/orchestrator/pkg/server/main.go"
click node_api_orch_client "https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/orchestrator/client.go"
click node_template_storage "https://github.com/e2b-dev/runtime/blob/main/packages/orchestrator/pkg/sandbox/template/storage_template.go"
click node_envd "https://github.com/e2b-dev/runtime/blob/main/packages/envd/main.go"
click node_process_api "https://github.com/e2b-dev/runtime/blob/main/packages/envd/internal/services/process/handler/handler.go"
click node_volumes "https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/handlers/volume_create.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_auth,node_browser toneBlue
class node_orchestrator,node_api_orch_client,node_envd,node_process_api,node_processes,node_firecracker toneAmber
class node_template_manager,node_template_storage toneMint
class node_dashboard,node_proxy toneRose
class node_postgres,node_redis,node_object_storage,node_clickhouse,node_volumes,node_sdk toneIndigo
```

## Components

### Control plane

- [Control API](https://github.com/e2b-dev/runtime/blob/main/packages/api/main.go): `packages/api/main.go`
- [Authentication](https://github.com/e2b-dev/runtime/blob/main/packages/auth/pkg/auth/internal/service/service.go): `packages/auth/pkg/auth/internal/service/service.go`

### Sandbox execution

- [Node orchestrator](https://github.com/e2b-dev/runtime/blob/main/packages/orchestrator/pkg/server/main.go): `packages/orchestrator/pkg/server/main.go`
- [Orchestrator client](https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/orchestrator/client.go): `packages/api/internal/orchestrator/client.go`
- [Guest agent](https://github.com/e2b-dev/runtime/blob/main/packages/envd/main.go): `packages/envd/main.go`
- [Process service](https://github.com/e2b-dev/runtime/blob/main/packages/envd/internal/services/process/handler/handler.go): `packages/envd/internal/services/process/handler/handler.go`
- **Sandbox processes**
- **Firecracker VM**

### Template builds

- [Template manager](https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/template-manager/template_manager.go): `packages/api/internal/template-manager/template_manager.go`
- [Template storage](https://github.com/e2b-dev/runtime/blob/main/packages/orchestrator/pkg/sandbox/template/storage_template.go): `packages/orchestrator/pkg/sandbox/template/storage_template.go`

### Traffic and dashboard

- [Dashboard API](https://github.com/e2b-dev/runtime/blob/main/packages/dashboard-api/main.go): `packages/dashboard-api/main.go`
- [Client proxy](https://github.com/e2b-dev/runtime/blob/main/packages/client-proxy/main.go): `packages/client-proxy/main.go`

### State and telemetry

- **PostgreSQL**
- **Redis**
- **Object storage**
- **ClickHouse**
- [Persistent volumes](https://github.com/e2b-dev/runtime/blob/main/packages/api/internal/handlers/volume_create.go): `packages/api/internal/handlers/volume_create.go`

### Other components

- **SDK / CLI**
- **Browser**

## Connections

- SDK / CLI → Control API: REST requests (evidence: `README.md`)
- Control API → Authentication: validates identity (evidence: `packages/api/main.go`)
- Control API → Orchestrator client: dispatches lifecycle (evidence: `packages/api/internal/orchestrator/client.go`)
- Orchestrator client → Node orchestrator: calls over gRPC (evidence: `README.md`)
- Control API → PostgreSQL: stores control data (evidence: `README.md`)
- Control API → Redis: uses cache (evidence: `README.md`)
- Control API → ClickHouse: exports events (evidence: `README.md`)
- Node orchestrator → Firecracker VM: runs microVMs (evidence: `README.md`)
- Node orchestrator → Object storage: reads and writes snapshots (evidence: `README.md`)
- Node orchestrator → ClickHouse: exports telemetry (evidence: `README.md`)
- Firecracker VM → Guest agent: hosts agent (evidence: `README.md`)
- Guest agent → Process service: serves process API (evidence: `packages/envd/main.go`)
- Process service → Sandbox processes: runs commands (evidence: `packages/envd/internal/services/process/handler/handler.go`)
- Control API → Template manager: manages builds (evidence: `packages/api/main.go`)
- Template manager → Template storage: builds from stored templates
- Template storage → Object storage: fetches template data (evidence: `packages/orchestrator/pkg/sandbox/template/storage_template.go`)
- Browser → Client proxy: sandbox URL traffic (evidence: `README.md`)
- Client proxy → Node orchestrator: routes sandbox traffic (evidence: `README.md`)
- Node orchestrator → Guest agent: forwards traffic (evidence: `README.md`)
- Dashboard API → PostgreSQL: reads dashboard data (evidence: `packages/dashboard-api/main.go`)
- Dashboard API → Authentication: authenticates requests (evidence: `packages/dashboard-api/main.go`)
- Dashboard API → ClickHouse: queries analytics (evidence: `packages/dashboard-api/main.go`)
- Control API → Persistent volumes: manages volumes