# How to Build CubeSandbox from Source: Complete Build Guide

> Build CubeSandbox from source with this complete guide. Learn how to compile Rust and Go components using Docker via simple make commands. Start your secure container journey today.

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

---

**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:

```bash
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:

```bash
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:

```bash
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:

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

```

This invokes [`scripts/build-kernel.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
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:

```bash
_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:

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

```bash
_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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/api/openapi.yaml). Verify functionality with:

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

```

Expected response:

```json
{ "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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeShim/Cargo.toml)** – Rust configuration for the containerd shim
- **`agent/Makefile`** – Build configuration for the in-guest daemon
- **[`scripts/build-kernel.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`.