# TTRPC Protocol Protobuf Definitions in CubeSandbox: A Complete Guide

> Explore the main ttrpc protocol Protobuf definitions in CubeSandbox. Understand network management service, agent metrics, health checks, and OCI metadata specifications.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: api-reference
- Published: 2026-07-05

---

**CubeSandbox defines its core inter-process communication contract through five main protobuf files that specify the ttrpc services for network management, agent metrics, health checks, and OCI metadata.**

CubeSandbox uses the **ttrpc** (tiny-RPC) transport for lightweight communication between the Cubelet daemon, the shim, and various agents. All ttrpc services are defined in standard `.proto` files processed by the `containerd/ttrpc` Go library, which generates the corresponding client and server stubs. These protobuf definitions form the public API contract that governs every remote procedure call in the repository.

## Core TTRPC Services Defined in Protobuf

The ttrpc protocol implementation in CubeSandbox centers on four primary service definitions. These files live in distinct directories but work together to provide complete sandbox lifecycle management.

### NetworkAgent Service

The **NetworkAgent** service manages sandbox network state and is defined in `network-agent/api/v1/network_agent.proto`. This service handles network setup, teardown, and reconciliation for sandbox instances.

The service definition includes six RPC methods:

```proto
service NetworkAgent {
  rpc EnsureNetwork(EnsureNetworkRequest) returns (EnsureNetworkResponse);
  rpc ReleaseNetwork(ReleaseNetworkRequest) returns (ReleaseNetworkResponse);
  rpc ReconcileNetwork(ReconcileNetworkRequest) returns (ReconcileNetworkResponse);
  rpc GetNetwork(GetNetworkRequest) returns (GetNetworkResponse);
  rpc Health(HealthRequest) returns (HealthResponse);
  rpc ListNetworks(ListNetworksRequest) returns (ListNetworksResponse);
}

```

Key messages such as `EnsureNetworkRequest` and `NetworkState` describe sandbox network interfaces, routes, ARP neighbors, and port mappings. The `persist_metadata` field appears as a `map<string,string>` across multiple messages to carry opaque key-value data between calls.

### AgentService (Core Agent)

The **AgentService** interface, defined in `agent/libs/protocols/protos/agent.proto`, serves as the primary contract between the shim and Cubelet. This service aggregates container-level statistics, block-IO counters, and lifecycle events.

```proto
service AgentService {
  rpc Stats(StatsRequest) returns (StatsResponse);
  rpc Ping(PingRequest) returns (PingResponse);
  // Additional RPCs for metrics, events, snapshots, etc.
}

```

The generated Go stubs from this file are used by both the `CubeShim` component and Cubelet's internal sandbox manager to report container metrics and health status.

### Health Service

A minimal but critical definition lives in `agent/libs/protocols/protos/health.proto`. The **Health** service provides a standard liveness probe used by the Cubelet watchdog to monitor component status.

```proto
service Health {
  rpc Check(HealthRequest) returns (HealthResponse);
}

```

Both the network agent and the shim expose this endpoint, enabling quick health checks without invoking heavier service methods.

### OCI Metadata Messages

While not a service itself, `agent/libs/protocols/protos/oci.proto` defines the **OCI** message structures that describe container runtime metadata, including annotations and image configuration. These messages are exchanged over ttrpc streams when the shim passes container creation parameters to the Cubelet.

## Key Protobuf Files and Locations

The following files constitute the complete ttrpc protobuf contract for CubeSandbox:

| File Path | Service | Purpose |
|-----------|---------|---------|
| `network-agent/api/v1/network_agent.proto` | **NetworkAgent** | Network lifecycle management |
| `agent/libs/protocols/protos/agent.proto` | **AgentService** | Container metrics and events |
| `agent/libs/protocols/protos/health.proto` | **Health** | Liveness/readiness probes |
| `agent/libs/protocols/protos/oci.proto` | *Messages only* | Runtime metadata exchange |
| `CubeShim/protoc/protos/agent.proto` | **AgentService** | Shim-side generated copy |
| `CubeShim/protoc/protos/network_agent.proto` | **NetworkAgent** | Shim-side generated copy |

The shim maintains its own copies of the protocol definitions in the `CubeShim/protoc/protos/` directory to ensure version compatibility between the shim and Cubelet components.

## Implementation Example: Using the Generated TTRPC Client

Below is a minimal Go implementation showing how a Cubelet component creates a ttrpc client for the `NetworkAgent` service and invokes the `GetNetwork` method.

```go
package main

import (
	"context"
	"log"

	"github.com/containerd/ttrpc"
	networkv1 "github.com/tencentcloud/CubeSandbox/network-agent/api/v1"
)

func main() {
	// Create a TTRPC connection to the network-agent UNIX socket.
	conn, err := ttrpc.NewClient(ttrpc.WithAddress("/run/cubesandbox/network-agent.ttrpc"))
	if err != nil {
		log.Fatalf("ttrpc client init: %v", err)
	}
	defer conn.Close()

	// Create a generated client stub.
	cli := networkv1.NewNetworkAgentClient(conn)

	// Add per-call metadata for tracing.
	md := ttrpc.MD{
		"request-id": []string{"1234-abcd"},
	}
	ctx := ttrpc.WithMetadata(context.Background(), md)

	// Call GetNetwork.
	resp, err := cli.GetNetwork(ctx, &networkv1.GetNetworkRequest{
		SandboxId:     "sandbox-001",
		NetworkHandle: "net-hdl-01",
	})
	if err != nil {
		log.Fatalf("GetNetwork RPC failed: %v", err)
	}
	log.Printf("Network state: %+v", resp)
}

```

The shim uses an identical pattern to communicate with the Cubelet's `AgentService`:

```go
shimCli := agent.NewAgentServiceClient(conn)
stats, err := shimCli.Stats(ctx, &agent.StatsRequest{SandboxId: "sandbox-001"})

```

## Summary

- **Five primary protobuf files** define the ttrpc protocol contract in CubeSandbox, located in `network-agent/api/v1/` and `agent/libs/protocols/protos/`.
- **NetworkAgent** handles network lifecycle operations via six RPC methods defined in `network_agent.proto`.
- **AgentService** provides container metrics and event reporting through the interface in `agent/libs/protocols/protos/agent.proto`.
- **Health** service offers simple liveness checks used by multiple components to report status to the Cubelet watchdog.
- **Shim copies** of the protobuf definitions exist in `CubeShim/protoc/protos/` to maintain compatibility between the shim and daemon.
- The `containerd/ttrpc` library generates Go client stubs from these `.proto` files, enabling lightweight UNIX socket communication between components.

## Frequently Asked Questions

### What is the difference between the NetworkAgent and AgentService in CubeSandbox?

**NetworkAgent** specializes in sandbox network configuration, managing interfaces, routes, and port mappings through the `EnsureNetwork` and `ReconcileNetwork` methods. **AgentService** handles container-level operations including statistics collection, event reporting, and lifecycle hooks. While both use ttrpc, they operate on different concerns: NetworkAgent manages virtual network infrastructure, while AgentService monitors container runtime state.

### How does CubeSandbox handle protobuf versioning between the shim and Cubelet?

CubeSandbox maintains **generated copies** of the core protobuf files in `CubeShim/protoc/protos/`, including `agent.proto` and `network_agent.proto`. These copies ensure that the shim and Cubelet compile against identical protocol definitions even when the master copies in `agent/libs/protocols/protos/` evolve. Both sides use the `containerd/ttrpc` code generation tools to produce compatible Go stubs from these definitions.

### Where are the OCI container metadata structures defined in the ttrpc protocol?

The **OCI** message definitions reside in `agent/libs/protocols/protos/oci.proto`. These structures describe container image configuration, annotations, and runtime metadata. While not a ttrpc service themselves, these messages are serialized and exchanged over ttrpc streams when the shim communicates container creation parameters to the Cubelet during sandbox initialization.

### Can I use standard gRPC tools to generate clients for CubeSandbox's ttrpc services?

Yes, because CubeSandbox uses **standard protobuf `.proto` files** with standard syntax, you can use `protoc` with the appropriate ttrpc plugin to generate clients. The `containerd/ttrpc` project provides `protoc-gen-go-ttrpc`, which generates lightweight clients that communicate over UNIX domain sockets rather than HTTP/2. Standard `protoc-gen-go` would generate gRPC-specific code that is not compatible with CubeSandbox's ttrpc transport layer.