How to Integrate CubeSandbox with External Services via Configuration

CubeSandbox integrates with external APIs and databases through a two-layer YAML configuration system that stores secrets in the host-side Credential Vault (cubemaster.yaml) and routes traffic through the Egress Gateway (cubelet.yaml), ensuring credentials never appear in the sandbox filesystem or logs.

TencentCloud/CubeSandbox provides isolated environments for executing untrusted code, but connecting these sandboxes to external services requires secure credential management without exposing secrets to the guest OS. By configuring the Credential Vault and Egress Policy components, you can enable controlled outbound connectivity while maintaining strict security boundaries.

Understanding the Two-Layer Security Model

Credential Vault (Cube Egress)

The Credential Vault operates on the control-plane side of the service and stores sensitive data such as API keys, tokens, and database credentials. Located in configs/single-node/cubemaster.yaml, this vault injects authentication headers or query parameters into outbound requests after they leave the sandbox, guaranteeing that secrets remain invisible to the guest operating system. You can define credential sources using valueFromEnv to read directly from the host environment at startup, preventing secrets from being embedded in sandbox images.

Egress Policy (Cube Egress Gateway)

The Egress Policy defines granular allow-lists and block-lists for destination domains, ports, and paths. Configured in configs/single-node/cubelet.yaml, these policies force all sandbox traffic through an OpenResty-based egress proxy backed by the CubeVS eBPF network filter. This architecture ensures that outbound requests cannot bypass the proxy, enabling rate-limiting, audit logging, and request/response rewrites at the network level.

Step-by-Step Configuration Guide

Step 1: Configure the Credential Vault

Edit configs/single-node/cubemaster.yaml to create a credentialVault entry. The name field serves as a unique reference for binding to egress rules later.

# configs/single-node/cubemaster.yaml

credentialVault:
  - name: openai-gpt
    type: http-header
    headerName: Authorization
    valueFromEnv: OPENAI_API_KEY

The valueFromEnv parameter instructs the master process to read the secret from the host environment (e.g., export OPENAI_API_KEY=sk-...). Supported injection types include http-header, query-param, and bearer-token.

Step 2: Define Egress Policies

In configs/single-node/cubelet.yaml, grant the sandbox permission to contact specific external hosts and bind the credential vault entry to that destination.

# configs/single-node/cubelet.yaml

egress:
  policies:
    - name: allow-openai
      allow:
        - host: api.openai.com
          ports: [443]
      credentials:
        - vaultRef: openai-gpt

The vaultRef field links the egress policy to the credential vault entry by name. The underlying CubeEgress proxy and CubeVS eBPF filter enforce these rules at the network level, preventing traffic from bypassing the gateway.

Step 3: Reference the Policy in Sandbox Specifications

When creating a sandbox via the API, web UI, or CLI, include the egress policy name in the sandbox specification. The runtime code in CubeMaster/pkg/templatecenter/*.go reads this specification and applies the requested network policies.

{
  "template": "python-3.10-base",
  "egressPolicy": "allow-openai"
}

The Cube API automatically routes the sandbox's network traffic through the configured egress gateway, injecting the Authorization header on each request to api.openai.com without exposing the token to the sandbox environment.

Step 4: Reload the Configuration

After editing the YAML files, restart the control plane components to apply changes:

systemctl restart cubemaster
systemctl restart cubelet

Alternatively, send a SIGHUP signal to the processes to trigger configuration reloads without dropping active connections.

Practical Integration Examples

Integrating with OpenAI API

The following configuration enables secure access to the OpenAI API:

# configs/single-node/cubemaster.yaml

credentialVault:
  - name: openai-gpt
    type: http-header
    headerName: Authorization
    valueFromEnv: OPENAI_API_KEY

# configs/single-node/cubelet.yaml

egress:
  policies:
    - name: allow-openai
      allow:
        - host: api.openai.com
          ports: [443]
      credentials:
        - vaultRef: openai-gpt

Connecting to MySQL Databases

For database connections using query parameter authentication:

# configs/single-node/cubemaster.yaml

credentialVault:
  - name: mysql-prod
    type: query-param
    paramName: token
    valueFromEnv: MYSQL_TOKEN

# configs/single-node/cubelet.yaml

egress:
  policies:
    - name: allow-mysql
      allow:
        - host: mysql.example.com
          ports: [3306]
      credentials:
        - vaultRef: mysql-prod

When creating the sandbox:

{
  "template": "nodejs-14-base",
  "egressPolicy": "allow-mysql",
  "env": {
    "DB_HOST": "mysql.example.com"
  }
}

Key Configuration Files and Implementation Details

The following files govern external service integration in TencentCloud/CubeSandbox:

• configs/single-node/cubemaster.yaml — Defines the credential vault entries used for secret injection.

• configs/single-node/cubelet.yaml — Contains egress policy definitions including allow-l

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