How to Report Bugs in CubeSandbox: A Complete Guide for Contributors

Open a GitHub Issue in the TencentCloud/CubeSandbox repository with steps to reproduce, environment details, and the specific component suspected.

CubeSandbox is a multi-component AI-agent platform that combines a stateless control plane with a highly isolated data plane. When you encounter unexpected behavior, knowing how to report bugs in CubeSandbox correctly ensures maintainers can reproduce and resolve issues efficiently. The repository provides clear documentation on the preferred workflow through its README and CONTRIBUTING guides.

Official Channel: GitHub Issues

According to the source code, the README.md explicitly directs contributors to "Submit an issue on GitHub Issues" [lines 73-74]. The CONTRIBUTING.md file expands on this requirement, mandating that every bug report include detailed steps to reproduce the problem [lines 7-9].

Understanding Component Architecture

The architecture overview in docs/architecture/overview.md [lines 18-33] describes how requests flow through the system. Identifying which component triggers the bug helps maintainers triage faster:

Component	Role	Source Location
CubeAPI	High-concurrency REST gateway (Rust)	CubeAPI/
CubeMaster	Cluster orchestrator (Go)	CubeMaster/
CubeProxy	Reverse proxy & request router (Go)	CubeProxy/
Cubelet	Node-local sandbox scheduler (Go)	Cubelet/
CubeShim	containerd Shim v2 implementation (Rust)	CubeShim/
CubeHypervisor	KVM-based MicroVM manager (Rust)	hypervisor/
CubeVS	eBPF-based network isolation	CubeVS/
CubeEgress	L7 egress security proxy (OpenResty)	CubeEgress/

Required Information for Bug Reports

To report bugs in CubeSandbox effectively, include these six elements:

1. Title – Concise summary (e.g., "CubeProxy returns 500 on /sandbox/<id>/status")
2. Environment – OS, kernel version, Docker version, KVM support, and exact CubeSandbox release (git rev-parse HEAD)
3. Component – Indicate which subsystem you suspect (CubeAPI, CubeMaster, CubeProxy, Cubelet, etc.)
4. Steps to Reproduce – Minimal, reproducible sequence of CLI commands, SDK calls, or UI actions
5. Observed vs Expected Behavior – Include log excerpts from /var/log/cubesandbox/* or component-specific debug logs
6. Additional Context – Relevant configuration files, custom templates, or network policies

Security Vulnerability Reporting

If the bug represents a security vulnerability, do not open a public GitHub Issue. Instead, follow the responsible disclosure process documented in CONTRIBUTING.md [lines 49-52]. Report these issues through GitHub Security Advisories to prevent public exposure of exploit details.

Practical Bug Report Templates

Python SDK Reproduction Script

When bugs involve the Python SDK, provide a minimal reproduction script:

from cubesandbox import CubeSandbox

sandbox = CubeSandbox(api_key="YOUR_API_KEY")
try:
    # This call triggers the bug (e.g., unexpected 500 from CubeProxy)

    resp = sandbox.create(name="bug-repro")
    print("Sandbox created:", resp.id)
except Exception as e:
    print("Error:", e)
    # Capture the full traceback and HTTP response for the issue

Attach the complete traceback and any response output when filing the issue.

CLI Verification with cURL

For REST API issues, verify the endpoint behavior directly:

curl -X POST https://<api-host>/v1/sandboxes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"bug-repro"}' -i

Include the raw HTTP headers and body if the response deviates from the expected 201 Created status.

Issue Template Markdown

Copy and paste this template into your GitHub Issue:

## Bug Summary

<Brief description>

## Environment

- OS: Ubuntu 22.04
- Kernel: 5.15.0-72-generic
- Docker: 24.0.5
- Cube Sandbox version: `<git rev-parse HEAD>`

## Steps to Reproduce

1. Run the following Python snippet:
   ```python
   # (insert reproduction code)

2. Observe the error output.

Observed Behavior

Expected Behavior

Component (if known)

CubeProxy / CubeAPI / Cubelet …

## Summary

- **Open GitHub Issues** for all non-security bugs in the TencentCloud/CubeSandbox repository as directed in [`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) [lines 73-74]
- **Include reproduction steps** and environment details as required by [`CONTRIBUTING.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CONTRIBUTING.md) [lines 7-9]
- **Identify the component** using the architecture overview in [`docs/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/architecture/overview.md) [lines 18-33]
- **Use Security Advisories** for vulnerabilities, not public issues, per [`CONTRIBUTING.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CONTRIBUTING.md) [lines 49-52]
- **Attach debug logs** from `/var/log/cubesandbox/` and relevant configuration files

## Frequently Asked Questions

### How do I report security vulnerabilities in CubeSandbox?

Do not open a public GitHub Issue. Follow the responsible disclosure process in [`CONTRIBUTING.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CONTRIBUTING.md) [lines 49-52] and submit through GitHub Security Advisories to protect sensitive vulnerability details from public exposure.

### What information is most important when reporting bugs in CubeSandbox?

The [`CONTRIBUTING.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CONTRIBUTING.md) file emphasizes steps to reproduce as the most critical element. Additionally, specify your environment (OS, kernel, Docker version, and `git rev-parse HEAD` output) and identify the suspected component (CubeAPI, CubeProxy, etc.) to accelerate triage.

### Where can I find CubeSandbox architecture documentation?

Reference [`docs/architecture/overview.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/architecture/overview.md) [lines 18-33] for the high-level flow of sandbox creation requests. Each component also maintains its own README in subdirectories like `CubeAPI/`, `CubeMaster/`, and `CubeProxy/` with implementation-specific details.

### Should I report component-specific bugs in separate repositories?

No. Despite CubeSandbox comprising distinct components (CubeAPI, CubeMaster, CubeShim, etc.), all bugs should be reported in the main TencentCloud/CubeSandbox repository via GitHub Issues, as indicated in the root [`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) [lines 73-74].

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}