CubeSandbox Development Skill

CubeSandbox is a monorepo sandbox service (Go + Rust + Web). All component builds run inside a Docker builder container via make targets at the repo root. The builder image provides Go 1.24, Rust 1.89, protoc, and all build dependencies.

Paths in this document are relative to the repo root

Prerequisites

# Docker must be running
docker info > /dev/null 2>&1 || { echo "Docker is not running"; exit 1; }

The builder image is built once (or when toolchains change):

make builder-image

Build

All builds happen inside the cube-sandbox-builder:ubuntu2004 Docker image. Binaries land in _output/bin/.

Build all Go components

make all

This builds: cubemaster, cubelet, cubevsmapdump, network-agent, agent, cubeapi, shim.

Build individual components

Command	Component	Language	Time
make cubemaster	Master scheduler + CLI	Go	~30s
make cubelet	Per-node sandbox agent + CLI	Go + Rust (cubecow SDK)	~90s
make agent	In-guest agent daemon	Rust	~2min
make cubeapi or make cube-api	E2B-compatible REST API	Rust (musl)	~3min
make shim	containerd shim + runtime	Rust	~2min
make network-agent	Network management	Go	~30s
make cubevsmapdump	eBPF map dump tool	Go	~20s
make cube-proxy-sidecar	Proxy sidecar (dev only)	Go	~20s
make cubecow-smoke	CubeCoW smoke test	Go + Rust	~60s
make cube-init / make guest-init	Guest PID1 (cube-init)	Rust (musl)	~30s
make agent-ext4 / make cube-agent-ext4	Independent cube-agent.ext4 (+ version)	Rust + e2fsprogs	~2min
make pmem-assets	cube-init + agent-ext4	—	~2min

Agent-independent pmem outputs:

make cube-init     # → _output/bin/cube-init
make agent-ext4    # → _output/cube-agent/cube-agent.ext4 (+ version)
make pmem-assets   # both of the above

Verify a build

# Check files in `_output/bin/`
file _output/bin/cubemaster

Test

Tests run inside the builder container. Some tests need external services (Redis, KVM) and will fail without them — see Gotchas.

Run component tests

# Agent tests (Rust) — 101+ tests, most pass without KVM
make builder-run BUILDER_CMD='cd /workspace/agent && make test'

# CubeMaster tests (Go) — unit-style cmd and pkg packages
make cubemaster-test

# Cubelet tests (Go) — full self-contained set (all packages except api/ and
# integration/); root/host-capability tests probe and skip themselves
make cubelet-test

# Cubelet mount tests — focused privileged lane for CAP_SYS_ADMIN tests
make cubelet-mount-test

# CubeCoW native tests (Go + CGO, needs cubecow SDK built)
make cubecow-test-native

# Integration tests — require a running CubeSandbox cluster (dev-env or one-click deploy)

Run a single test

# CubeMaster: single package with verbose output
make builder-run BUILDER_CMD='cd /workspace/CubeMaster && CI=true CUBE_MASTER_CONFIG_PATH=/workspace/CubeMaster/test/conf.yaml go test -v -run TestSomething ./pkg/base/...'

# Agent: single test
make builder-run BUILDER_CMD='cd /workspace/agent && cargo test -p cube-agent test_name'

Format and Lint

# Format all components (Go + Rust)
make fmt

# Web UI lint
make web-lint

For a single component:

# Go component
make builder-run BUILDER_CMD='cd /workspace/CubeMaster && make fmt'

# Rust component — fmt automatically runs in builder
make builder-run BUILDER_CMD='cd /workspace/CubeAPI && cargo fmt --check'

Web UI

The web dashboard lives in web/ (Vite + Vue + TypeScript).

make web-install     # Install npm dependencies (~30s)
make web-build       # Build static assets → web/dist/ (~2s)
make web-dev         # Start Vite dev server (localhost:5173)
make web-lint        # Lint check
make web-preview     # Preview built assets

Sync OpenAPI types after CubeAPI changes:

make web-api-sync

Gotchas

1. Tests need Redis/KVM/MicroVM context.

   • CubeMaster/pkg/base/wrapredis tests panic if Redis is not reachable.
   • agent sandbox tests (9 of 110) fail without a running KVM MicroVM.
   • Run with -short or filter to the relevant package when iterating.

2. CubeMaster tests use CUBE_MASTER_CONFIG_PATH. Must be set to test/conf.yaml inside the container (absolute path from /workspace).

3. go covdata not available. The builder's Go toolchain (1.25) removed covdata. Use -coverprofile directly or skip coverage:

   go test -short ./pkg/...    # no coverage flag
   

4. Builder container runs as host UID:GID. The builder-run target mounts the workspace with --user $(UID):$(GID). Files written by the builder (e.g., _output/bin/*) are owned by the host user.

5. All builds are sequential. The Makefile uses builder-run which spawns one Docker container per target. Building make all runs each component sequentially. For parallel builds, use separate terminals or background processes.

6. Agent build runs embedded unit tests before linking. make agent includes cargo test for the logging crate as part of the build. These are pure unit tests and always pass.

7. CubeCoW SDK must be built before cubelet. make cubelet handles this automatically via the cubecow-sdk dependency, but if you build cubelet outside the make flow, run make cubecow-sdk first.

8. KVM required for running sandboxes. Building works without KVM, but actually creating/starting sandboxes needs /dev/kvm with nested virtualization enabled. This container has it (/dev/kvm exists with nested=Y).

Troubleshooting

Symptom	Fix
docker: Cannot connect	Docker daemon not running. sudo systemctl start docker
make: *** [builder-image] Error	Docker build failed. Check network, retry with make builder-image BUILDER_FORCE_REBUILD=1. From China, add MIRROR=cn to source the clang-14 apt packages from a China mirror
error: protoc not installed inside builder	Builder image is outdated. Rebuild: make builder-image BUILDER_FORCE_REBUILD=1
go: no such tool "covdata"	Don't use -coverprofile flag with make test in CubeMaster. Use raw go test instead.
cargo: command not found on host	Rust builds run inside Docker. Use make <target>, not raw cargo.
Build hangs on "Download modules"	Go module download is slow. The builder persists GOPATH at ~/.cache/cube-sandbox-builder/go, so retry is faster.
panic: nil pointer dereference in Redis test	Expected — no Redis in builder. Filter: -run 'Test[^D]' or skip wrapredis package.