# How to Configure HTTPS and Custom Domains for Cube Sandbox Access

> Learn how to configure HTTPS and custom domains for Cube Sandbox access. Secure your sandbox environment with custom domains and SSL certificates efficiently.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

   ```text
   *.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:

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

   Or the environment variable:

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

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/nginx.conf) and replace the TLS section in the `listen 443 ssl` block with your own certificate paths:

```nginx
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/nginx.conf).
2. Delete the `80` port mapping from [`docker-compose.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/nginx.conf) and delete the `80` port mapping from [`docker-compose.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/docker-compose.yaml). Restart CubeProxy. The SDK will automatically use HTTPS, and HTTP requests will be rejected.