The Role of cube-agent in the CubeSandbox Architecture: In-VM Guest Agent Deep Dive

cube-agent serves as the in-VM guest agent running as PID 1 (init) inside every MicroVM, acting as the bridge between host-side orchestration components and guest-side containers via a ttrpc over vsock interface.

The cube-agent is the core runtime component that transforms a bare MicroVM into a fully functional container execution environment within the TencentCloud/CubeSandbox project. As the primary in-VM process, it manages container lifecycles, handles I/O forwarding, and exposes metrics while maintaining a lightweight communication channel with the host. Understanding the role of cube-agent in the CubeSandbox architecture is essential for developers working with secure, isolated container sandboxes.

What Is cube-agent?

cube-agent is a statically-linked binary written in Rust that serves as the init process (PID 1) inside every MicroVM created by CubeSandbox. It boots with the guest image, mounts the required filesystems, creates necessary namespaces, and configures networking via vsock and netlink before transitioning into a long-running server mode. According to the source code in agent/README.md (lines 36-44), the agent is packaged into the guest image as /sbin/init, ensuring it gains control immediately upon MicroVM startup.

Core Responsibilities of cube-agent

The agent operates as the control plane inside the guest, translating host-side orchestration commands into OCI-compliant container operations.

System Initialization and Boot Sequence

During the boot phase, cube-agent performs essential first-boot tasks as documented in agent/README.md. It mounts the root filesystem and necessary pseudo-filesystems, establishes network connectivity through the vsock interface, and initializes the environment for subsequent container execution. This initialization sequence ensures the MicroVM transitions from a blank state to a ready container host before accepting remote commands.

ttrpc Server Implementation

The agent exposes a ttrpc (TTRPC) server that listens on a vsock port for incoming connections from the host-side containerd-shim-cube-rs (CubeShim), as detailed in agent/README.md (lines 38-41). The shim connects to this socket to drive container operations, making the agent the sole entry point for host-to-guest orchestration commands. Protocol buffer definitions for this API reside in agent/libs/protocols/, ensuring type-safe communication between the Rust-based agent and Go-based shim.

OCI-Compatible Container Lifecycle

cube-agent implements the complete Open Container Initiative (OCI) lifecycle via the Cube ttrpc API. As shown in agent/src/main.rs (lines 63-70), it handles CreateContainer, StartContainer, ExecProcess, SignalProcess, and RemoveContainer requests. The agent delegates actual container execution to rustjail, the Rust implementation of a container runtime, ensuring OCI-compliant isolation and resource management within the MicroVM boundary.

I/O Forwarding and Stream Management

All container standard streams—stdin, stdout, and stderr—are forwarded over the vsock channel back to the host shim, as noted in agent/README.md (lines 41-42). This proxy capability allows host-side tools like containerd to interact with container processes as if they were running natively on the host, despite being isolated inside the guest MicroVM.

Metrics and Observability

The agent exposes Prometheus-compatible metrics via a vsock exporter, providing visibility into CPU usage, memory consumption, and container health status without requiring network access from the guest (see agent/README.md, lines 42-43). This design maintains the MicroVM's network isolation while still supporting cloud-native observability standards.

Version Reporting and Compatibility Matrix

cube-agent reports its own version and the guest-image version to CubeMaster, enabling the control plane to maintain a cluster-wide version matrix. As implemented in CubeMaster/pkg/nodemeta/versionmatrix.go (lines 263-266), this data allows CubeSandbox to enforce template compatibility and ensure that host-side components communicate with compatible agent versions.

Architecture and Communication Flow

In the CubeSandbox data flow, components interact across the MicroVM boundary through well-defined interfaces:

Host Side                                           Guest Side
----------                                          -----------
containerd-shim-cube-rs (CubeShim)              ┌─────────────────────┐
        │                                       │    cube-agent       │
        │── ttrpc over vsock ───────────────────│    (PID 1)          │
        │                                       │        │            │
        │                                       ▼        ▼            │
        │                                       ┌─────────────────┐   │
        └───────────────────────────────────────│   Containers    │   │
                                                │   (via rustjail)│   │
                                                └─────────────────┘   │

The vsock channel provides a lightweight, host-guest communication mechanism that bypasses traditional network stacks. The shim in the host's user space sends ttrpc requests through this channel, which cube-agent translates into system calls and container runtime operations inside the guest.

Building and Deploying cube-agent

The agent is distributed as a statically-linked musl binary to ensure portability across minimal guest images without external dependencies.

# Build the musl-static binary from the agent directory

cd agent && bash build.sh

# The compiled binary location:

# target/$(uname -m)-unknown-linux-musl/release/cube-agent

# Inject into guest image as the init process

cp target/x86_64-unknown-linux-musl/release/cube-agent /path/to/guest-image/sbin/init

The build process, orchestrated by deploy/one-click/build-vm-assets.sh, compiles the agent and embeds it as /sbin/init into the guest rootfs, ensuring it receives process ID 1 upon MicroVM boot.

Key Source Files and Implementation Details

Understanding cube-agent requires familiarity with the following source locations:

• agent/README.md — High-level architecture description, responsibility overview, and build instructions.
• agent/src/main.rs — Entry point that sets up vsock logging, parses command-line arguments, performs initial mounts, and starts the ttrpc server.
• agent/src/rpc.rs — Implementation of the Cube ttrpc service handlers that process requests from the CubeShim.
• agent/libs/protocols/ — Protobuf definitions and generated Rust bindings for the ttrpc API shared between agent and shim.
• Cubelet/pkg/cubelet/versioninfo/collector.go — Host-side component that collects cube-agent version metadata from the guest.
• CubeMaster/pkg/nodemeta/versionmatrix.go — Control plane logic that aggregates agent versions across the cluster to enforce compatibility.
• CubeShim/docs/shimapi/README.md — Documentation detailing how the shim communicates with cube-agent over ttrpc.

Summary

• cube-agent runs as PID 1 inside every CubeSandbox MicroVM, serving as the guest init system and container runtime controller.
• It exposes a ttrpc server over vsock that receives commands from the host-side containerd-shim-cube-rs, acting as the bridge across the virtualization boundary.
• The agent implements full OCI container lifecycle management through rustjail, handling create, start, exec, signal, and remove operations.
• It provides I/O forwarding for container streams and exposes Prometheus metrics via vsock, maintaining guest isolation while enabling observability.
• Version reporting to CubeMaster ensures cluster-wide compatibility through a maintained version matrix.

Frequently Asked Questions

What protocol does cube-agent use to communicate with the host?

cube-agent communicates with the host-side shim using ttrpc (Tokio-based gRPC) transported over vsock (virtual socket). This combination provides a lightweight, low-latency communication channel that does not require network interface configuration inside the guest, maintaining the MicroVM's isolation boundaries while allowing efficient binary protocol communication.

Why does cube-agent run as PID 1 inside the MicroVM?

Running as PID 1 (init) allows cube-agent to assume responsibility for system initialization during the boot sequence, including mounting filesystems, configuring namespaces, and setting up networking before any containers start. As the init process, it also assumes the traditional role of reaping zombie processes within the guest, ensuring proper process lifecycle management in the containerized environment.

How does cube-agent handle container execution internally?

While cube-agent receives high-level container commands via ttrpc, it delegates the actual implementation of OCI runtime specifications to rustjail, a Rust library that handles namespace creation, cgroup management, and system call filtering. This separation of concerns keeps the agent's core focused on API handling and orchestration while rustjail manages the low-level container isolation mechanics.

Where is the cube-agent version information used in the cluster?

The agent reports its version to CubeMaster, which aggregates this data in CubeMaster/pkg/nodemeta/versionmatrix.go to build a cluster-wide compatibility matrix. This version tracking ensures that the control plane only schedules workloads on nodes running compatible cube-agent and guest-image versions, preventing API mismatches between the host-side shim and the guest-side runtime.

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