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

> Discover the purpose of cube-agent as the MicroVM's init process. Learn how it handles initialization, exposes APIs, and manages container lifecycles within Cube Sandbox.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/main.rs), the main function detects the init case by checking if the process ID is 1:

```rust
// 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.

```rust
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/rpc.rs), the service handles creation requests:

```rust
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/cubelet/versioninfo/collector.go), the collector extracts this information:

```go
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.