How to Configure HTTPS and Custom Domains for Cube Sandbox Access

Configure HTTPS and custom domains for Cube Sandbox by setting the CUBE_API_SANDBOX_DOMAIN environment variable on the Cube API server, creating a wildcard DNS record pointing to CubeProxy, and updating the TLS certificate paths in CubeProxy/nginx.conf.

CubeSandbox from TencentCloud exposes every sandbox through CubeProxy, an Nginx/OpenResty reverse proxy that terminates both HTTP (port 80) and HTTPS (port 443). By default, the SDK generates sandbox URLs using the cube.app domain, but you can override this to use your own domain and production-grade TLS certificates. This guide explains how to configure HTTPS and custom domains for sandbox access using the actual source configuration files and environment variables.

Understand the Sandbox Domain Mechanism

When a sandbox starts, the Cube API constructs a service address using the pattern:

<service-port>-<sandboxID>.<domain>

For example: 49983-1aa1fae8fb364edaa8203a7481995b4d.cube.app【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L11-L16】.

• service-port – The port your code listens on inside the sandbox.
• sandboxID – A unique UUID generated for each sandbox instance.
• domain – Defaults to cube.app, but can be overridden (see the next section).

Because the subdomain contains a dynamic sandbox ID, you must configure a wildcard DNS record (*.cube.app or your custom domain) that resolves to the IP address of the CubeProxy host【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L28-L32】.

Set Up a Custom Domain

To switch from the default cube.app to your own domain (e.g., your.domain.com):

1. Create a wildcard DNS entry pointing to your CubeProxy host:

   *.your.domain.com  →  <CubeProxy host IP>

2. Configure the Cube API server to return your domain in API responses. You can use either the startup flag:

   ./cube-api --sandbox-domain your.domain.com

   Or the environment variable:

   export CUBE_API_SANDBOX_DOMAIN=your.domain.com
   ./cube-api

   After this change, every API response includes your.domain.com in the domain field, causing the SDK to build URLs like 49983-<id>.your.domain.com【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L44-L53】.

Configure HTTPS Certificates

CubeProxy ships with a self-signed certificate for cube.app that is suitable only for local testing. For custom domains, choose one of the following methods based on your environment.

Method A: Local Development with mkcert

For trusted local development certificates, generate them with mkcert and point CubeProxy to the root CA:

mkcert -install
mkcert <your-domain-or-ip>
export SSL_CERT_FILE=/root/.local/share/mkcert/rootCA.pem

This allows your local browser to trust the sandbox endpoints without certificate warnings【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L98-L11】.

Method B: Production-Grade Certificates

Edit CubeProxy/nginx.conf and replace the TLS section in the listen 443 ssl block with your own certificate paths:

server {
    listen 443 ssl;
    server_name your.domain.com;
    ssl_certificate     /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;
}

The default configuration in CubeProxy/nginx.conf contains the template for this block at lines 58-26【https://github.com/TencentCloud/CubeSandbox/blob/master/CubeProxy/nginx.conf#L58-L26】.

Method C: HTTPS-Only Mode

To disable HTTP entirely and enforce TLS:

1. Remove the HTTP server block from CubeProxy/nginx.conf.
2. Delete the 80 port mapping from docker-compose.yaml in the project root.

The SDK will continue to use HTTPS only, so client code requires no changes【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L31-L35】.

Use Path-Based Routing (No DNS Required)

If configuring wildcard DNS is not possible, CubeProxy supports a path-based access mode that requires no DNS changes:

http://<cube-proxy-host>:<http-port>/sandbox/<sandbox-id>/<container-port>/...

Example: http://10.0.0.5/sandbox/abc123/49999/health【https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/https-and-domain.md#L63-L73】.

Both the HTTP and HTTPS server blocks in CubeProxy/nginx.conf contain a location /sandbox/ block (lines 66-95) that rewrites the request and forwards it to the backend sandbox【https://github.com/TencentCloud/CubeSandbox/blob/master/CubeProxy/nginx.conf#L66-L95】. This mode is ideal for internal networks or quick demos where DNS cannot be altered.

Summary

• Domain format: CubeSandbox uses <port>-<uuid>.<domain> addresses generated by the Cube API and resolved by CubeProxy.
• Custom domains: Set CUBE_API_SANDBOX_DOMAIN or --sandbox-domain and configure a wildcard DNS record (*.your.domain.com) pointing to the CubeProxy IP.
• HTTPS configuration: Replace the self-signed certs in CubeProxy/nginx.conf with production certificates (Method B) or use mkcert for local development (Method A).
• HTTPS-only: Remove the HTTP server block and port 80 mapping from docker-compose.yaml to disable cleartext access.
• Path routing: Use /sandbox/<id>/<port>/ URLs when DNS is unavailable, handled by the Lua rewrite logic in CubeProxy/lua/path_rewrite_phase.lua.

Frequently Asked Questions

How do I change the default domain from cube.app to my own domain?

Set the CUBE_API_SANDBOX_DOMAIN environment variable to your domain (e.g., your.domain.com) when starting the Cube API server, or pass the --sandbox-domain your.domain.com flag. Ensure you also create a wildcard DNS record (*.your.domain.com) pointing to your CubeProxy host so the subdomains resolve correctly.

Where does CubeProxy store its TLS certificates?

CubeProxy reads certificate paths from the ssl_certificate and ssl_certificate_key directives in CubeProxy/nginx.conf. By default, it uses a self-signed certificate for cube.app. For production, replace these paths with your own PEM-encoded certificate and key files.

Can I run CubeSandbox without configuring DNS?

Yes. Use path-based routing by accessing URLs in the format http://<cube-proxy-host>/sandbox/<sandbox-id>/<port>/. CubeProxy’s Lua scripts (CubeProxy/lua/path_rewrite_phase.lua) automatically rewrite these paths to the correct sandbox instance, eliminating the need for wildcard DNS records.

How do I disable HTTP and force HTTPS only?

Remove the HTTP server block listening on port 80 from CubeProxy/nginx.conf and delete the 80 port mapping from docker-compose.yaml. Restart CubeProxy. The SDK will automatically use HTTPS, and HTTP requests will be rejected.

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