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

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) — needs Redis at minimum
make builder-run BUILDER_CMD='cd /workspace/CubeMaster && make proto && CI=true CUBE_MASTER_CONFIG_PATH=/workspace/CubeMaster/test/conf.yaml go test -short ./api/... ./pkg/...'

# Cubelet tests (Go)
make builder-run BUILDER_CMD='cd /workspace/Cubelet && make proto && go test -short ./pkg/...'

# 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