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

> Learn how to report bugs in CubeSandbox effectively. This guide details opening GitHub Issues with steps to reproduce, environment details, and component specifics for swift resolution.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) explicitly directs contributors to "Submit an issue on GitHub Issues" [lines 73-74]. The [`CONTRIBUTING.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```python
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:

```bash
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:

```markdown

## 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

<Error message and logs>

## Expected Behavior

<What should have happened>

## 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].