# Request Lifecycle in CubeSandbox: A Complete Technical Guide

> Explore the CubeSandbox request lifecycle from API to execution. Understand how CubeMaster and Cubelet interact through nine stages for efficient sandbox management. Detailed technical guide.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: deep-dive
- Published: 2026-07-08

---

**A CubeSandbox request traverses nine distinct stages: from the CubeMaster HTTP API through middleware validation and the Lifecycle Manager, persisted in Redis streams, dispatched via gRPC to the Cubelet for network provisioning and sandbox execution, then returning aggregated results through the reverse pipeline.**

The request lifecycle in CubeSandbox defines how TencentCloud's distributed sandbox platform processes user workloads from initial API call to final execution. When a client submits a job via the Go SDK or a direct HTTP request, the system coordinates multiple microservices—from the CubeMaster entry point to the Cubelet runtime and Network-Agent—to securely isolate and execute containerized code. Understanding this pipeline reveals critical insights for debugging latency issues, optimizing cold-start performance, and ensuring proper resource cleanup in production environments.

## API Ingress and Middleware Processing

Every request begins at the **CubeMaster HTTP service**, implemented in [`CubeMaster/pkg/service/httpservice/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/httpservice/server.go). This component registers public API routes such as `/v1/sandbox/run` and listens for incoming HTTP or gRPC connections from clients.

Before reaching the business logic, requests pass through the **middleware chain** defined in [`CubeMaster/pkg/service/httpservice/middleware/middleware.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/httpservice/middleware/middleware.go). This layer performs several critical functions:

- **Request logging** for audit trails and debugging
- **Authentication and token validation** to verify tenant identity
- **Context enrichment** by injecting request IDs and tenant metadata into the request context

The middleware ensures that only authorized, traceable requests proceed to the lifecycle management layer.

## Lifecycle Management and Job Persistence

After middleware processing, the request routes to the **Cube Lifecycle Manager** ([`cube-lifecycle-manager/internal/httpapi/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/httpapi/server.go)). Here, the manager validates the incoming payload structure and translates it into an internal representation using the **Lifecycle schema** defined in [`cube-lifecycle-manager/internal/lifecycle/schema.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/lifecycle/schema.go).

Once validated, the manager creates a **job description** and persists it to the **Redis stream** ([`cube-lifecycle-manager/internal/redisstream/stream.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/redisstream/stream.go)). This Redis-backed queue decouples the API frontend from the execution backend, providing durability and horizontal scalability. Simultaneously, the **sweeper** component ([`cube-lifecycle-manager/internal/sweeper/sweeper.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/sweeper/sweeper.go)) monitors the stream for stale or orphaned jobs, ensuring the system cleans up resources from failed or timed-out executions.

## gRPC Communication to Cubelet

The Lifecycle Manager selects an appropriate **Cubelet** worker node and dispatches the job via **gRPC**. The Cubelet's server implementation in [`Cubelet/services/server/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/server/server.go) handles these incoming requests, receiving the complete job description and preparing for local execution.

The Cubelet then invokes the **sandbox host handler** in [`Cubelet/services/server/snhost.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/server/snhost.go), which bridges the high-level gRPC calls to the low-level sandbox runtime. This layer manages the transition from the distributed control plane to the actual node-local execution environment.

## Network Provisioning and Isolation

Before launching the user container, the Cubelet must establish network isolation. It communicates with the **Network-Agent** ([`network-agent/internal/service/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/service.go)) to provision networking resources for the sandbox. The Network-Agent performs several low-level operations:

- Creates a **tap device** for the sandbox interface
- Configures **SNAT/DNAT** rules for external connectivity
- Registers security policies in the **CubeVS datapath** (`CubeNet/cubevs/*.go`)

These steps ensure the sandbox has isolated network access while maintaining connectivity to required services, implemented through eBPF/TC handling for high-performance packet processing.

## Sandbox Execution and Runtime

With networking established, the **sandbox runtime** launches the user container inside a lightweight **Kata/QEMU** sandbox. The runtime implementation coordinates with the SDK layer ([`sdk/go/sandbox.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/sandbox.go)) to initialize the execution environment according to the specified resources (CPU, memory).

During execution, the Cubelet captures **logs, metrics, and I/O streams** from the sandbox. These streams flow back through the gRPC connection to the Lifecycle Manager, which can forward them to the client via HTTP streaming or the SDK's streaming API, allowing real-time monitoring of long-running tasks.

## Result Aggregation and Resource Cleanup

When the sandbox completes—whether successfully, with an error, or via timeout—the Cubelet reports the final **status** and any **output artifacts** back to the Lifecycle Manager. The manager writes these results into Redis and constructs the JSON response payload for the original HTTP request.

The **sweeper** and **Network-Agent** then perform parallel cleanup operations: releasing tap devices, deallocating IP addresses, removing temporary files, and deleting Redis stream entries. This prevents resource leaks and maintains cluster hygiene for subsequent requests.

## Code Example: Initiating the Lifecycle

Below is a minimal Go SDK implementation that triggers the complete request lifecycle described above. The SDK abstracts the internal HTTP and gRPC calls, providing a simple interface to the distributed pipeline:

```go
package main

import (
	"context"
	"log"
	"github.com/tencentcloud/cubesandbox/sdk/go"
)

func main() {
	// Create a client pointing to the CubeMaster endpoint
	client, err := cubesandbox.NewClient(&cubesandbox.Config{
		Endpoint: "https://cubesandbox.example.com",
	})
	if err != nil {
		log.Fatalf("client init: %v", err)
	}

	// Define the sandbox specification
	spec := &cubesandbox.Spec{
		Image:   "ubuntu:22.04",
		Command: []string{"/bin/bash", "-c", "echo hello && sleep 5"},
		Resources: &cubesandbox.Resources{
			CPU:    1,
			Memory: 512, // MB
		},
	}

	// Execute the sandbox and stream logs
	stream, err := client.RunSandbox(context.Background(), spec)
	if err != nil {
		log.Fatalf("run sandbox: %v", err)
	}
	for {
		msg, err := stream.Recv()
		if err != nil {
			break // EOF indicates sandbox completion
		}
		log.Printf("[sandbox] %s", msg.Output)
	}
}

```

## Summary

The request lifecycle in CubeSandbox follows a rigorous pipeline designed for security, scalability, and observability:

- **CubeMaster** ([`CubeMaster/pkg/service/httpservice/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/httpservice/server.go)) serves as the HTTP entry point and authentication layer
- **Middleware** processes add logging, auth, and context injection before routing to the Lifecycle Manager
- **Lifecycle Manager** validates requests, converts them to internal schemas, and persists jobs to Redis streams
- **Cubelet** receives jobs via gRPC, coordinates with the Network-Agent for isolated networking, and executes the sandbox runtime
- **Network-Agent** provisions tap devices and configures eBPF-based traffic policies through CubeVS
- **Cleanup components** including the sweeper ensure resource reclamation after execution

## Frequently Asked Questions

### What is the role of the CubeMaster in the request lifecycle?

The CubeMaster acts as the primary HTTP/gRPC gateway for all CubeSandbox requests. Implemented in [`CubeMaster/pkg/service/httpservice/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/httpservice/server.go), it registers public API routes, validates incoming connections, and routes authenticated requests to the Lifecycle Manager. The middleware layer in [`CubeMaster/pkg/service/httpservice/middleware/middleware.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/service/httpservice/middleware/middleware.go) handles request logging, token validation, and context enrichment before the request enters the core orchestration pipeline.

### How does CubeSandbox handle network isolation during the request lifecycle?

Network isolation occurs at the Cubelet stage through coordination with the Network-Agent. When the Cubelet receives a job via gRPC ([`Cubelet/services/server/server.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/services/server/server.go)), it requests network provisioning from the Network-Agent ([`network-agent/internal/service/service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/service.go)). The agent creates isolated tap devices and configures SNAT/DNAT rules, while the CubeVS datapath (`CubeNet/cubevs/*.go`) enforces traffic policies using eBPF/TC filters to ensure sandbox traffic cannot interfere with other workloads.

### What happens if a sandbox job fails during execution?

If a sandbox fails, the Cubelet captures the error status and any stderr output, then reports this information back to the Lifecycle Manager via the existing gRPC connection. The manager writes the failure state to the Redis stream ([`cube-lifecycle-manager/internal/redisstream/stream.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/redisstream/stream.go)) and includes error details in the JSON response to the client. The sweeper component ([`cube-lifecycle-manager/internal/sweeper/sweeper.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/sweeper/sweeper.go)) monitors for failed jobs and triggers cleanup of associated network resources and temporary files to prevent resource exhaustion.

### How does the sweeper component manage resource cleanup?

The sweeper runs as a background process within the Lifecycle Manager ([`cube-lifecycle-manager/internal/sweeper/sweeper.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-lifecycle-manager/internal/sweeper/sweeper.go)). It periodically scans the Redis stream for stale jobs—those that have exceeded their timeout limits or failed without proper cleanup. Upon detecting orphaned resources, the sweeper coordinates with the Network-Agent to release IP allocations and tap devices, removes temporary execution files from Cubelet nodes, and deletes the corresponding Redis entries to maintain cluster efficiency.