CubeSandbox Control Plane Components: Architecture and Core Services

The CubeSandbox control plane consists of five stateless services—CubeAPI, CubeMaster, CubeProxy, WebUI, and Redis—that collectively handle API requests, scheduling, metadata coordination, and user interaction.

The control plane in TencentCloud/CubeSandbox serves as the stateless orchestration layer for managing AI-agent sandboxes. Unlike the data-plane components that run on compute nodes, these CubeSandbox control plane components handle all API requests, scheduling decisions, and metadata coordination through a centralized, resilient architecture.

Core Components of the CubeSandbox Control Plane

CubeAPI (REST Gateway)

Written in Rust using the Axum framework, CubeAPI functions as the high-concurrency REST gateway. It accepts E2B-compatible SDK calls, translates them into internal gRPC messages, and forwards requests to CubeMaster. The source implementation resides in the cube-api directory, providing the primary entry point for external clients.

CubeMaster (Cluster Scheduler)

CubeMaster is the cluster-level scheduler written in Go that orchestrates sandbox lifecycle operations. It receives lifecycle requests from CubeAPI, selects appropriate compute nodes, dispatches work to Cubelet agents, and publishes lifecycle events to Redis. According to the TencentCloud/CubeSandbox source code, the entry point for this service is located at cube-master/cmd/cube-lifecycle-manager/main.go, while configuration handling is managed in cube-master/internal/config/config.go.

CubeProxy (Traffic Router)

CubeProxy operates as an OpenResty-based (nginx + Lua) reverse proxy that routes client traffic to specific sandbox instances. It evaluates host-based or path-based rules to determine the correct destination, ensuring seamless connectivity to running sandboxes. The service initialization can be found in network-agent/cmd/network-agent/main.go.

WebUI (Management Console)

The WebUI provides a browser-based management console accessible on port :12088. This component allows operators to view nodes, templates, sandboxes, and version matrices without requiring CLI access. The static assets and backend implementation are housed in the webui directory.

Redis (Single Source of Truth)

Redis serves as the persistent state store for the entire control plane. It maintains sandbox metadata, lifecycle event streams, routing tables for CubeProxy, and distributed locks for auto-pause/resume functionality. All control plane services remain stateless because Redis holds the authoritative coordination data.

How the Control Plane Services Interact

The architecture follows a stateless design pattern where any service instance can serve any request. When a client creates a sandbox, CubeAPI receives the request and converts it to gRPC. CubeMaster processes the scheduling decision, updates Redis with the sandbox metadata, and dispatches the creation command to the data-plane Cubelet. CubeProxy reads routing tables from Redis to direct traffic to the correct sandbox instance.

Accessing the CubeSandbox Control Plane

Creating a Sandbox via API

Use the E2B-compatible Go client to interact with the CubeAPI endpoint:

package main

import (
    "context"
    "log"

    sandbox "github.com/TencentCloud/CubeSandbox/cubesandbox/client"
)

func main() {
    // Initialise the client – point it at the CubeAPI endpoint.
    cli := sandbox.NewClient("http://<control‑node>:12088")
    // Create a sandbox from a ready template.
    sandboxID, err := cli.CreateSandbox(context.Background(),
        sandbox.CreateOptions{
            TemplateID: "template‑12345",
        })
    if err != nil {
        log.Fatalf("sandbox creation failed: %v", err)
    }
    log.Printf("sandbox created: %s", sandboxID)
}

Listing Sandboxes via WebUI

Query the management console REST endpoint directly using curl:

curl http://<control‑node>:12088/api/v1/sandboxes \
     -H "Authorization: Bearer <your‑token>"

Summary

• The CubeSandbox control plane comprises five stateless services: CubeAPI, CubeMaster, CubeProxy, WebUI, and Redis.
• CubeAPI (Rust/Axum) handles external REST requests and translates them to internal gRPC.
• CubeMaster (Go) schedules sandbox lifecycles and manages cluster state through Redis.
• CubeProxy (OpenResty) routes client traffic to sandbox instances based on Redis-stored routing tables.
• All coordination data lives in Redis, enabling horizontal scaling of control plane instances.
• The WebUI on port 12088 provides browser-based management without CLI dependencies.

Frequently Asked Questions

What is the difference between the CubeSandbox control plane and data plane?

The control plane handles API requests, scheduling, and metadata coordination through stateless services like CubeAPI and CubeMaster. The data plane consists of components running on compute nodes—such as Cubelet, CubeShim, CubeHypervisor, CubeVS, and CubeEgress—that execute the actual sandbox workloads.

Which programming languages are used in the CubeSandbox control plane?

The control plane uses Rust (Axum) for CubeAPI, Go for CubeMaster, and Lua (within OpenResty/nginx) for CubeProxy. The WebUI uses standard web technologies, while Redis serves as the state store.

Where is the state stored if the control plane components are stateless?

All state resides in Redis, which acts as the single source of truth for sandbox metadata, lifecycle events, routing tables, and distributed locks. This design allows any control plane instance to handle any request.

How does CubeProxy know where to route traffic?

CubeProxy reads routing tables from Redis that map host or path rules to specific sandbox instances. When CubeMaster creates or updates a sandbox, it writes the routing information to Redis, which CubeProxy then consumes to direct client traffic correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}