Purpose of cube-agent Inside the MicroVM: Architecture and Role Explained

cube-agent runs as PID 1 (the init process) inside every Cube Sandbox MicroVM, serving as the guest agent that handles boot-time initialization, exposes a ttrpc API over vsock, and orchestrates OCI-compliant container lifecycles by delegating to the embedded rustjail runtime.

In the TencentCloud CubeSandbox repository, cube-agent serves as the fundamental bridge between the host-side containerd shim and workloads executing inside the MicroVM. Understanding the purpose of cube-agent inside the MicroVM is essential for debugging container lifecycle issues and optimizing serverless workload performance.

Architecture Overview: Where cube-agent Fits Inside the MicroVM

The agent sits at the center of the Cube Sandbox communication model:

Host
└─ containerd-shim-cube-rs ──► ttrpc over vsock ──► cube-agent (PID 1) ──► container workload

• The host-side shim forwards containerd runtime calls to cube-agent over a vsock channel.
• cube-agent runs inside the guest VM, acting as the bridge between the host shim and the containers that actually execute inside the MicroVM.
• CubeMaster gathers the agent version (and other component versions) to build a cluster-wide compatibility matrix and to enforce template version bindings.

Core Responsibilities of cube-agent

Boot-Time Initialization as PID 1

When a MicroVM boots, cube-agent is started automatically from the guest image at /sbin/init. In agent/src/main.rs, the main function detects the init case by checking if the process ID is 1:

// inside agent/src/main.rs
let init_mode = unistd::getpid() == Pid::from_raw(1);
if init_mode {
    // … mount proc, run rc.local, then call init_agent_as_init()
    init_agent_as_init(&logger, AGENT_CONFIG.read().await.unified_cgroup_hierarchy)?;
}

According to the agent README, this initialization includes mounting required filesystems, setting up namespaces, configuring the network, and performing standard init duties such as running /etc/rc.local.

ttrpc Server Over Vsock

cube-agent opens a vsock listener and serves the Cube-specific ttrpc protocol defined in libs/protocols/protos/. The shim (containerd-shim-cube-rs) connects to this endpoint to drive container operations.

// agent/src/main.rs – create_logger_task() sets up the vsock listener
let listenfd = socket::socket(AddressFamily::Vsock, SockType::Stream, SockFlag::SOCK_CLOEXEC, None)?;
let addr = SockAddr::new_vsock(libc::VMADDR_CID_ANY, vsock_port);
socket::bind(listenfd, &addr)?;
socket::listen(listenfd, 1)?;

OCI-Compliant Container Lifecycle Management

The agent implements the full OCI-compliant lifecycle (CreateContainer, StartContainer, ExecProcess, SignalProcess, RemoveContainer) by delegating to the embedded rustjail runtime. All container I/O (stdin/stdout/stderr) is proxied back to the shim over vsock.

In agent/src/rpc.rs, the service handles creation requests:

// agent/src/rpc.rs (simplified)
#[ttrpc::async_trait]
impl AgentService for Agent {
    async fn create_container(&self, req: CreateContainerRequest) -> Result<CreateContainerResponse> {
        // delegate to rustjail which performs the OCI container setup
        sandbox.create_container(req).await
    }
}

Metrics and Health Reporting

cube-agent exports Prometheus-compatible metrics (CPU, memory, container health) via a vsock exporter, enabling observability across the MicroVM fleet.

Version Reporting to CubeMaster

The baked-in agent version is read from the guest manifest (guest_image.agent_version) and reported to CubeMaster as part of the node's component version matrix. In Cubelet/pkg/cubelet/versioninfo/collector.go, the collector extracts this information:

// Cubelet version collector – gathers the baked‑in version
if man.GuestImage.AgentVersion != "" {
    out = append(out, ComponentVersion{
        Component: ComponentCubeAgent,
        Version:   man.GuestImage.AgentVersion,
        Source:    SourceManifest,
    })
}

CubeMaster stores this value in node_component_version and uses it for compatibility checks in CubeMaster/pkg/templatecenter/compat.go.

Key Source Files

The following files define the implementation and integration of cube-agent:

• agent/src/main.rs: Entry point, init detection, and vsock server setup
• agent/README.md: High-level role description and build instructions
• libs/protocols/protos/: Shared protobuf API for host-shim ↔ agent communication
• CubeShim/README.md: Documentation showing how the shim forwards calls to cube-agent
• Cubelet/pkg/cubelet/versioninfo/collector.go: Extracts the baked-in agent version from the guest manifest
• deploy/one-click/build-vm-assets.sh: Copies cube-agent into the guest image as /sbin/init (lines 378-398)
• CubeMaster/pkg/templatecenter/compat.go: Uses the reported cube-agent version for template compatibility checks

Summary

• cube-agent runs as PID 1 inside every Cube Sandbox MicroVM, serving as the init process.
• It exposes a ttrpc server over vsock to receive commands from the host-side containerd shim.
• The agent manages the full OCI container lifecycle by delegating to the rustjail runtime.
• It reports version and health metrics to CubeMaster for cluster-wide compatibility monitoring.
• The binary is injected into the guest image at /sbin/init during the build process defined in deploy/one-click/build-vm-assets.sh.

Frequently Asked Questions

What is the purpose of cube-agent inside the MicroVM?

cube-agent serves as the init process (PID 1) and guest agent that handles boot-time initialization, exposes a ttrpc API over vsock for host communication, and manages container lifecycles using the rustjail runtime. It acts as the bridge between the host-side containerd shim and the actual workloads running inside the MicroVM.

How does cube-agent communicate with the host?

cube-agent communicates with the host via ttrpc over vsock. It opens a vsock listener inside the MicroVM that accepts connections from the containerd-shim-cube-rs running on the host, allowing secure, low-latency RPC calls for container operations.

Why does cube-agent need to run as PID 1?

Running as PID 1 allows cube-agent to perform essential init duties required for Linux system initialization, including mounting filesystems, configuring network namespaces, and executing /etc/rc.local. This design eliminates the need for a separate init system, keeping the MicroVM lightweight while still providing a full container runtime environment.

Where does CubeMaster get the cube-agent version?

CubeMaster retrieves the cube-agent version from the guest manifest (guest_image.agent_version) via the Cubelet's version collector. This metadata is reported during node registration and stored in node_component_version for template compatibility enforcement.

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