OpenParable
Skip to content
← Back to skills

Run Dev

Development
run-dev

Run Dev is an Agent Skill for development published in the TencentCloud/CubeSandbox repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Build, test, format, and develop CubeSandbox components. Use when asked to build, compile, run tests, format code, or do development work on this project.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/TencentCloud/CubeSandbox/blob/HEAD/.claude/skills/run-dev/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/run-dev, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CommandComponentLanguageTime
make cubemasterMaster scheduler + CLIGo~30s
make cubeletPer-node sandbox agent + CLIGo + Rust (cubecow SDK)~90s
make agentIn-guest agent daemonRust~2min
make cubeapi or make cube-apiE2B-compatible REST APIRust (musl)~3min
make shimcontainerd shim + runtimeRust~2min
make network-agentNetwork managementGo~30s
make cubevsmapdumpeBPF map dump toolGo~20s
make cube-proxy-sidecarProxy sidecar (dev only)Go~20s
make cubecow-smokeCubeCoW smoke testGo + Rust~60s

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

SymptomFix
docker: Cannot connectDocker daemon not running. sudo systemctl start docker
make: *** [builder-image] ErrorDocker build failed. Check network, retry with make builder-image BUILDER_FORCE_REBUILD=1. From China, add MIRROR=cn to fetch the llvm.sh installer and clang-14 apt packages from a China mirror (the LLVM GPG key still comes from apt.llvm.org)
error: protoc not installed inside builderBuilder 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 hostRust 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 testExpected — no Redis in builder. Filter: -run 'Test[^D]' or skip wrapredis package.