OpenSandbox × fast-sandbox Integration Architecture

OpenSandbox × fast-sandbox Integration Architecture An architecture diagram generated by Archify. SDK · CLI · MCP · Python·TS·Go·Java·C#·osb · Architecture component · Client-side SDK · CLI · MCP Python·TS·Go·Java·C#·osb Client-side Server DB · Template · snapshot metadata · Architecture component · SQLite/PG Server DB Template · snapshot metadata SQLite/PG ingress-gateway · Traffic :28888 · Ed25519 routes · opensandbox-system · Control Plane · Deployment ×2 ingress-gateway Traffic :28888 · Ed25519 routes Deployment ×2 opensandbox-server · FastAPI /v1 · runtime routing · opensandbox-system · Control Plane · Deployment opensandbox-server FastAPI /v1 · runtime routing Deployment fsb-controller · FastPath · gRPC :9090 · admit/pause/resume · opensandbox-system · Control Plane · Deployment ×1 fsb-controller · FastPath gRPC :9090 · admit/pause/resume Deployment ×1 Fastlet Pod · HTTP :5758 · netns slots · Nodes · Data Plane (fsb CRs: opensandbox-dataplane) · Pod · pre-warmed Fastlet Pod HTTP :5758 · netns slots Pod · pre-warmed firecracker-runtime · agent · SigV4 S3 · FC api.sock · Nodes · Data Plane (fsb CRs: opensandbox-dataplane) · DaemonSet firecracker-runtime agent · SigV4 S3 · FC api.sock DaemonSet Template Builder · KVM Pod · FastPath-built · Template Pipeline & Artifact Storage · Pod · on demand Template Builder KVM Pod · FastPath-built Pod · on demand XFS StateRoot · reflink CoW · digest cache · Nodes · Data Plane (fsb CRs: opensandbox-dataplane) · hostPath · shared XFS StateRoot reflink CoW · digest cache hostPath · shared P2P block cache · peer :9000 · miss→S3 · Nodes · Data Plane (fsb CRs: opensandbox-dataplane) · node daemon P2P block cache peer :9000 · miss→S3 node daemon S3 Artifact Store · s3://sandbox-images/publish · Template Pipeline & Artifact Storage · MinIO/S3 S3 Artifact Store s3://sandbox-images/publish MinIO/S3 HTTP /v1 · API Key Templates · snapshot metadata ResolveEndpoint gRPC :9090 Signed :5780 routes HTTP :5758 · admit/snapshot UDS · checkpoint publish/pull :8145 GET /dart/ Golden images commit cache Origin GET on miss opensandbox-system · Control Plane Nodes · Data Plane (fsb CRs: opensandbox-dataplane) Template Pipeline & Artifact Storage

Control plane & access

  • • Control plane: Helm Deployments; FastPath co-hosts Reconciler + gRPC :9090
  • • Create persists a Sandbox CRD intent, then Top-K selects a Fastlet
  • • ResolveEndpoint signs Ed25519 route credentials for ingress
  • • Server DB: template catalog + snapshot metadata

Template artifact flow

  • • FastPath reconciles SandboxTemplate CR → privileged builder Pod (KVM)
  • • Golden set: rootfs.ext4 + vmstate + memory + manifest + SHA256SUMS
  • • S3 digest16(manifest) namespace; index (template ID) written last

Storage acceleration & checkpoints

  • • Hot path: XFS reflink clone from node cache; LoadSnapshot restore only
  • • Cold path: agent pulls whole files via P2P cache or direct S3; sha256 + atomic commit
  • • P2P cache-miss → origin S3 (presigned GET); block transfer on :9000 (DNS dart:9000)
  • • Agent fallback: direct SigV4 S3 pull/publish when P2P cache is down
  • • Resume: placement prefers same Fastlet; cross-node pulls checkpoint by digest
  • • Pause: reflink before pause; digest-first ManifestRef+Digest; then release