How to Build CubeSandbox from Source: Complete Build Guide

To build CubeSandbox from source, run make builder-image followed by make all to compile the Rust and Go components inside a unified Docker builder environment.

CubeSandbox is a high-performance sandbox service developed by TencentCloud that combines Rust, Go, and Docker components into a unified micro-VM platform. Building CubeSandbox from source requires a Linux host with KVM support and uses a containerized builder to ensure consistent compilation across all subsystems. This guide walks through the complete build process using the top-level Makefile and official builder image.

Prerequisites

Before building CubeSandbox from source, ensure your environment meets these requirements:

• Linux host with KVM support (x86_64 architecture)
• Docker installed and accessible (preferably without sudo)
• Go 1.21+ – verified via go.mod in each Go module
• Rust 1.75+ with the x86_64-unknown-linux-musl target for static binaries
• protoc (Protocol Buffers compiler)
• ~5 GB of free disk space for the builder image and intermediate artifacts

Build the Docker Builder Image

CubeSandbox uses a unified builder image to provide consistent toolchains across all components. The image is defined in docker/Dockerfile.builder and includes Go, Rust, Protobuf, and KVM tooling.

Execute the following command to build the builder image:

make builder-image

This rule executes docker build using the Dockerfile and tags the image as cube-sandbox-builder:ubuntu2004 by default. The builder caches the $HOME/.cache directory to support incremental builds across sessions.

Build Core Components

Once the builder image exists, compile the core binaries using the all target. This is the standard approach for building CubeSandbox from source:

make all

The all target compiles the following subsystems:

• cubemaster – Builds cubemaster and cubemastercli (Go)
• cubelet – Builds cubelet and cubecli (Go)
• network-agent – Builds the network-agent service (Go)
• cubevsmapdump – Builds the CubeVS eBPF map-dump utility (Go)

Each target invokes builder-run internally, which launches a container with environment variables CUBE_VERSION, CUBE_COMMIT, and CUBE_BUILD_TIME set from your git state. All resulting binaries are placed in _output/bin.

Interactive Build Shell

For debugging or custom compilation steps, enter an interactive shell inside the builder:

make builder-shell

This mounts the repository at /workspace and persists the BUILDER_HOME directory (~/.cache/cube-sandbox-builder) across sessions, preserving compiled artifacts and Go module caches.

Build Individual Subsystems

For selective compilation, use these specific make targets defined in the top-level Makefile:

Target	Component	Output
make cubecow-sdk	Snapshot/CoW library	libcubecow.a (used by Cubelet)
make cubeapi	REST API gateway	cube-api
make shim	Containerd integration	containerd-shim-cube-rs and cube-runtime
make agent	In-guest daemon	cube-agent
make guest-kernel	Linux guest kernel	vmlinux or Image

The guest-kernel target requires a kernel source path:

make guest-kernel KERNEL_SRC=/path/to/linux

This invokes scripts/build-kernel.sh to compile the kernel inside the builder environment.

Verify the Build

After compilation completes, verify the binaries exist in the output directory:

ls _output/bin

Expected output includes:

agent          cube-api       cubelet       cubemaster    cubemastercli
cubecli        cube-proxy-sidecar   network-agent   shim

Confirm successful compilation by checking the embedded version information:

_output/bin/cube-api --version

The version string is derived from git describe as defined in the Makefile build rules.

Create a Release Tarball

For manual deployment, package the built binaries into a distributable archive:

make manual-release

This creates a timestamped cube-manual-update-*.tar.gz in _output/release, accompanied by a SHA-256 checksum and deployment script (deploy-manual.sh). See the manual-release rule at line 72 of the Makefile for exact packaging logic.

Run a Binary

Test your build by starting the CubeAPI server:

_output/bin/cube-api --listen 0.0.0.0:8080 --log-level info

The server exposes E2B-compatible REST endpoints defined in web/api/openapi.yaml. Verify functionality with:

curl http://localhost:8080/v1/ping

Expected response:

{ "message": "pong" }

Key Build Files Reference

Understanding these source files helps when modifying the build process:

• Makefile – Central orchestrator defining all targets and environment variables
• docker/Dockerfile.builder – Creates the unified builder image with toolchains
• CubeAPI/Cargo.toml – Rust crate metadata for the API gateway
• CubeMaster/Makefile – Build rules for the CubeMaster daemon and CLI
• Cubelet/Makefile – Build rules for the Cubelet agent
• CubeShim/Cargo.toml – Rust configuration for the containerd shim
• agent/Makefile – Build configuration for the in-guest daemon
• scripts/build-kernel.sh – Helper script for kernel compilation

Summary

• Use make builder-image first to create the cube-sandbox-builder:ubuntu2004 Docker image containing all required toolchains
• Run make all to compile the four core Go components (CubeMaster, Cubelet, network-agent, CubeVS)
• Build Rust components separately using make cubeapi, make shim, or make agent for specific subsystems
• Find all binaries in _output/bin after successful compilation
• Package with make manual-release for deployment-ready tarballs with checksums

Frequently Asked Questions

What are the system requirements to build CubeSandbox from source?

You need a Linux host with x86_64 architecture and KVM support, Docker installed and accessible, plus approximately 5 GB of disk space. The build requires Go 1.21 or later, Rust 1.75 or later with the musl target, and the Protocol Buffers compiler.

Why does CubeSandbox require the musl target for Rust?

The musl target (x86_64-unknown-linux-musl) enables fully static linking for Rust binaries like cube-api and cube-agent. This eliminates runtime dependencies on glibc versions, making the sandbox components portable across different Linux distributions without dynamic library conflicts.

How do I build only a specific component like CubeAPI or the Agent?

Use the specific make targets: make cubeapi for the REST gateway, make agent for the in-guest daemon, or make shim for the containerd runtime. Each target ensures the builder image exists before running the appropriate cargo or go build commands inside the containerized environment.

Where are the compiled binaries stored after running make?

All compiled binaries are placed in the _output/bin directory relative to the repository root. This includes executables like cubemaster, cubelet, cube-api, and containerd-shim-cube-rs, which are ready to run directly or package using make manual-release.

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