Contributing to Cube Sandbox

July 29, 2026 · View on GitHub

Thank you for your interest in contributing to Cube Sandbox! This document provides guidelines and information to help you get started.

Ways to Contribute

Report bugs — Open a GitHub Issue with steps to reproduce.
Request features — Describe your use case and proposed solution in an Issue.
Improve documentation — Fix typos, clarify explanations, or add examples.
Submit code — Fix bugs, implement features, or improve performance.

Community Docs Channels

Besides general documentation fixes, we maintain three community doc channels under docs/guide/:

Troubleshooting — deployment and operations write-ups in docs/guide/troubleshooting/ and docs/zh/guide/troubleshooting/
Use Cases — real-world business or production case studies in docs/guide/usecases/ and docs/zh/guide/usecases/
Integrations — one integration guide per framework or agent in docs/guide/integrations/ and docs/zh/guide/integrations/

⛺️ Requirements for Community Doc PRs

Choose one language — every new or updated article must include either docs/guide/<channel>/<slug>.md or docs/zh/guide/<channel>/<slug>.md.
If you want to provide both languages:
- Use the same filename in both languages — filenames must use English kebab-case, for example langchain.md or e2b-api-401-timeout.md.
- Keep frontmatter aligned — both language versions should use the same frontmatter keys (title, author, date, tags, lang).
Start from the provided template — each channel includes an _template.md file plus an index page with the current article list and instructions.

Getting Started

Prerequisites

Linux with KVM support (x86_64)
Docker
Go 1.21+
Rust 1.75+ (with x86_64-unknown-linux-musl target)
protoc (Protocol Buffers compiler)

Build Environment

Cube Sandbox provides a Docker-based builder image for a consistent build environment:

# Build the builder image
make builder-image

# From mainland China, source apt packages from China-reachable mirrors: the
# Ubuntu apt archive plus the llvm.sh installer and clang-14 packages (the LLVM
# GPG key still comes from apt.llvm.org)
make builder-image MIRROR=cn

# Start an interactive shell inside the builder
make builder-shell

# Build all Go components (CubeMaster, Cubelet, network-agent)
make all

# Build individual components
make cubemaster
make cubelet
make agent
make shim

See the Makefile for the full list of build targets.

Project Structure

Directory	Language	Description
`CubeAPI/`	Rust	E2B-compatible REST API gateway
`CubeMaster/`	Go	Orchestration scheduler and cluster management
`Cubelet/`	Go	Per-node sandbox lifecycle agent
`CubeProxy/`	Go	Reverse proxy for sandbox request routing
`CubeShim/`	Rust	containerd shim bridging to KVM MicroVM
`agent/`	Rust	In-guest daemon running inside each sandbox
`hypervisor/`	Rust	KVM-based MicroVM manager (Cloud Hypervisor fork)
`mvs/` / `CubeNet/`	Go	CubeVS eBPF-based network isolation
`network-agent/`	Go	Network management service
`deploy/`	Shell	Deployment scripts and guest image tooling
`examples/`	Python	SDK examples and end-to-end scenarios
`docs/`	Markdown	VitePress documentation site (EN + ZH)

Submitting a Pull Request

Fork the repository and create a feature branch from main.
Make your changes — keep commits focused and atomic.
Test — make sure existing tests and linters still pass.
Add tests — add focused test coverage when behavior changes.
Document — update relevant docs if your change affects user-facing behavior.
Open the PR — describe the motivation and what the change does. Link related Issues.

Commit Organization

Commits should be logically organized and self-contained:

One component per commit — if a change spans multiple components (e.g., CubeAPI and Cubelet), split it into separate commits for each component.
Keep commits atomic — each commit should represent a single, coherent change that can be understood and reviewed independently.
Separate refactoring from behavior changes — do not mix code cleanup or refactoring with functional changes in the same commit.
Order commits logically — when a PR contains multiple commits, arrange them so that each commit builds on the previous one (e.g., infrastructure changes first, then the feature that depends on them).

Commit Messages

Write clear commit messages that explain why the change was made:

component: short summary of the change

Longer description explaining the motivation, trade-offs, or context.
Closes #123

Signed-off-by: Your Name <your.email@example.com>

Prefix the summary with the component name (e.g., cubeapi:, cubelet:, docs:, shim:).

Developer Certificate of Origin (DCO)

All commits must include a Signed-off-by line to certify the Developer Certificate of Origin (DCO). This indicates that you have the right to submit the contribution under the project's license.

Add it by using the -s flag when committing:

git commit -s -m "component: your commit message"

Or manually append the following line to your commit message:

Signed-off-by: Your Name <your.email@example.com>

Commits without a valid Signed-off-by line will not be accepted.

Code Style

Go — follow standard gofmt formatting and project conventions.
Rust — follow rustfmt and clippy recommendations.
Documentation — use clear, concise language. Both English and Chinese docs should be kept in sync.

Issue & PR Close Policy

Issues and PRs are closed under the following conditions:

Stale after a need-info request — if a maintainer asks for more information or requested changes and the author does not respond for more than 2 weeks, the Issue/PR is closed as stale. It can be reopened once the requested information or changes are provided.
Resolved or superseded — the underlying bug is fixed, the feature is implemented, or the change has been superseded by another PR/approach.
Out of scope / won't fix — closed with a comment explaining why.
Duplicate — closed with a link to the original Issue/PR.

Reporting Security Issues

If you discover a security vulnerability, please report it responsibly via GitHub Security Advisories rather than opening a public Issue.

License

By contributing to Cube Sandbox, you agree that your contributions will be licensed under the Apache License 2.0.

AI-Generated Code Policy

AI agents MUST NOT add Signed-off-by tags. Only humans can legally certify the Developer Certificate of Origin (DCO). The human submitter is responsible for:

Reviewing all AI-generated code
Ensuring compliance with licensing requirements
Adding their own Signed-off-by tag to certify the DCO
Taking full responsibility for the contribution