# tencentcloud/cubesandbox architecture

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

- Interactive diagram: https://gitdiagram.com/tencentcloud/cubesandbox
- Repository: https://github.com/tencentcloud/cubesandbox
- Video tour (about a minute): https://gitdiagram.com/tencentcloud/cubesandbox/video

## Overview

CubeSandbox provides hardware-isolated, E2B-compatible sandboxes, from API requests through cluster placement to a per-sandbox microVM. Its major capabilities include templates, snapshots and cross-node resume, volumes, and sandbox networking; CubeOps covers separate node management. The map follows documented product boundaries and the sampled route, workflow, storage, and network code. Several internal connections are inferred from module roles and the README rather than inspected call sites, so uncertain wiring is omitted.

Main entry points: [`CubeMaster/pkg/service/sandbox/sandbox_run.go`](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/sandbox/sandbox_run.go) (Sandbox Service), [`CubeMaster/pkg/service/httpservice/cube/routes.go`](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/httpservice/cube/routes.go) (Master HTTP API), [`Cubelet/plugins/workflow/engine.go`](https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/plugins/workflow/engine.go) (Cubelet Workflow), [`CubeMaster/pkg/templatecenter/snapshot_ops.go`](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/templatecenter/snapshot_ops.go) (Snapshot Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client APIs"]
  node_cubeapi["CubeAPI<br/>[routes.rs]"]
  node_masterapi["Master HTTP API<br/>[routes.go]"]
end

subgraph group_control["Sandbox Control"]
  node_master["CubeMaster<br/>[main.go]"]
  node_sandbox["Sandbox Service<br/>[sandbox_run.go]"]
  node_scheduler["Placement Scheduler<br/>[schedule.go]"]
  node_selector["Node Selector<br/>[init.go]"]
end

subgraph group_runtime["Node Runtime"]
  node_cubelet["Cubelet Workflow<br/>[engine.go]"]
  node_network["Sandbox Networking<br/>[controller.go]"]
  node_shim["Container Shim<br/>[srv.rs]"]
  node_vmm["MicroVM Device Manager<br/>[device_manager.rs]"]
  node_volume["Volume Plugins<br/>[plugin.go]"]
  node_networkkernel["CubeNet<br/>[cubevs.go]"]
end

subgraph group_state["Images And State"]
  node_template["Template Center"]
  node_snapshot["Snapshot Management<br/>[snapshot_ops.go]"]
  node_database[("Metadata Database<br/>[db.go]")]
  node_cubecow["CoW Snapshots<br/>[engine.go]"]
  node_storage["Snapshot Storage<br/>[storage_backend.go]"]
  node_tc["Template Center Service<br/>[server.go]"]
end

subgraph group_ops["Cluster Operations"]
  node_ops["CubeOps Node Management<br/>[nodemanagement.go]"]
end

node_client(("SDK or CLI"))

node_client -->|"calls API"| node_cubeapi
node_client -->|"calls API"| node_masterapi
node_cubeapi -.->|"forwards requests"| node_masterapi
node_masterapi -->|"handles sandbox requests"| node_sandbox
node_masterapi -->|"handles template requests"| node_template
node_sandbox -->|"requests placement"| node_scheduler
node_scheduler -->|"selects node"| node_selector
node_sandbox -->|"persists metadata"| node_database
node_sandbox -->|"dispatches sandbox work"| node_cubelet
node_cubelet -->|"manages containers"| node_shim
node_shim -->|"configures VM devices"| node_vmm
node_cubelet -->|"sets up networking"| node_network
node_network -->|"configures dataplane"| node_networkkernel
node_sandbox -->|"requests snapshots"| node_snapshot
node_snapshot -->|"persists snapshot state"| node_database
node_snapshot -->|"stores snapshot data"| node_storage
node_storage -.->|"uses CoW backend"| node_cubecow
node_sandbox -->|"mounts volumes"| node_volume
node_master -.->|"uses node management"| node_ops
node_template -.->|"delegates image work"| node_tc

click node_cubeapi "https://github.com/tencentcloud/cubesandbox/blob/master/CubeAPI/src/routes.rs"
click node_masterapi "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/httpservice/cube/routes.go"
click node_master "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/cmd/cubemaster/app/main.go"
click node_sandbox "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/sandbox/sandbox_run.go"
click node_scheduler "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/scheduler/schedule.go"
click node_selector "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/selector/filter/init.go"
click node_template "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/templatecenter/template_request.go"
click node_snapshot "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/templatecenter/snapshot_ops.go"
click node_database "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/base/db/db.go"
click node_cubelet "https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/plugins/workflow/engine.go"
click node_network "https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/network/runtime/controller.go"
click node_shim "https://github.com/tencentcloud/cubesandbox/blob/master/CubeShim/shim/src/service/srv.rs"
click node_vmm "https://github.com/tencentcloud/cubesandbox/blob/master/hypervisor/vmm/src/device_manager.rs"
click node_cubecow "https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/pkg/cubecow/engine.go"
click node_storage "https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/services/cubebox/storage_backend.go"
click node_volume "https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/volume/plugin/plugin.go"
click node_ops "https://github.com/tencentcloud/cubesandbox/blob/master/CubeOps/internal/nodemanagement/nodemanagement.go"
click node_networkkernel "https://github.com/tencentcloud/cubesandbox/blob/master/CubeNet/cubevs/cubevs.go"
click node_tc "https://github.com/tencentcloud/cubesandbox/blob/master/CubeTemplateCenter/pkg/httpservice/server.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_cubeapi,node_masterapi toneBlue
class node_master,node_sandbox,node_scheduler,node_selector toneAmber
class node_cubelet,node_network,node_shim,node_vmm,node_volume,node_networkkernel toneMint
class node_template,node_snapshot,node_database,node_cubecow,node_storage,node_tc toneRose
class node_ops,node_client toneIndigo
```

## Components

### Client APIs

- [CubeAPI](https://github.com/tencentcloud/cubesandbox/blob/master/CubeAPI/src/routes.rs): `CubeAPI/src/routes.rs`
- [Master HTTP API](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/httpservice/cube/routes.go): `CubeMaster/pkg/service/httpservice/cube/routes.go`

### Sandbox Control

- [CubeMaster](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/cmd/cubemaster/app/main.go): `CubeMaster/cmd/cubemaster/app/main.go`
- [Sandbox Service](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/service/sandbox/sandbox_run.go): `CubeMaster/pkg/service/sandbox/sandbox_run.go`
- [Placement Scheduler](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/scheduler/schedule.go): `CubeMaster/pkg/scheduler/schedule.go`
- [Node Selector](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/selector/filter/init.go): `CubeMaster/pkg/selector/filter/init.go`

### Node Runtime

- [Cubelet Workflow](https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/plugins/workflow/engine.go): `Cubelet/plugins/workflow/engine.go`
- [Sandbox Networking](https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/network/runtime/controller.go): `Cubelet/network/runtime/controller.go`
- [Container Shim](https://github.com/tencentcloud/cubesandbox/blob/master/CubeShim/shim/src/service/srv.rs): `CubeShim/shim/src/service/srv.rs`
- [MicroVM Device Manager](https://github.com/tencentcloud/cubesandbox/blob/master/hypervisor/vmm/src/device_manager.rs): `hypervisor/vmm/src/device_manager.rs`
- [Volume Plugins](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/volume/plugin/plugin.go): `CubeMaster/pkg/volume/plugin/plugin.go`
- [CubeNet](https://github.com/tencentcloud/cubesandbox/blob/master/CubeNet/cubevs/cubevs.go): `CubeNet/cubevs/cubevs.go`

### Images And State

- [Template Center](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/templatecenter/template_request.go): `CubeMaster/pkg/templatecenter/template_request.go`
- [Snapshot Management](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/templatecenter/snapshot_ops.go): `CubeMaster/pkg/templatecenter/snapshot_ops.go`
- [Metadata Database](https://github.com/tencentcloud/cubesandbox/blob/master/CubeMaster/pkg/base/db/db.go): `CubeMaster/pkg/base/db/db.go`
- [CoW Snapshots](https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/pkg/cubecow/engine.go): `Cubelet/pkg/cubecow/engine.go`
- [Snapshot Storage](https://github.com/tencentcloud/cubesandbox/blob/master/Cubelet/services/cubebox/storage_backend.go): `Cubelet/services/cubebox/storage_backend.go`
- [Template Center Service](https://github.com/tencentcloud/cubesandbox/blob/master/CubeTemplateCenter/pkg/httpservice/server.go): `CubeTemplateCenter/pkg/httpservice/server.go`

### Cluster Operations

- [CubeOps Node Management](https://github.com/tencentcloud/cubesandbox/blob/master/CubeOps/internal/nodemanagement/nodemanagement.go): `CubeOps/internal/nodemanagement/nodemanagement.go`

### Other components

- **SDK or CLI**

## Connections

- SDK or CLI → CubeAPI: calls API
- SDK or CLI → Master HTTP API: calls API
- CubeAPI → Master HTTP API: forwards requests
- Master HTTP API → Sandbox Service: handles sandbox requests
- Master HTTP API → Template Center: handles template requests
- Sandbox Service → Placement Scheduler: requests placement
- Placement Scheduler → Node Selector: selects node
- Sandbox Service → Metadata Database: persists metadata
- Sandbox Service → Cubelet Workflow: dispatches sandbox work
- Cubelet Workflow → Container Shim: manages containers
- Container Shim → MicroVM Device Manager: configures VM devices
- Cubelet Workflow → Sandbox Networking: sets up networking
- Sandbox Networking → CubeNet: configures dataplane
- Sandbox Service → Snapshot Management: requests snapshots
- Snapshot Management → Metadata Database: persists snapshot state
- Snapshot Management → Snapshot Storage: stores snapshot data
- Snapshot Storage → CoW Snapshots: uses CoW backend
- Sandbox Service → Volume Plugins: mounts volumes
- CubeMaster → CubeOps Node Management: uses node management
- Template Center → Template Center Service: delegates image work