# How to Integrate CubeSandbox with External Services via Configuration

> Learn how to integrate CubeSandbox with external services using its two-layer YAML configuration. Securely manage credentials with the Credential Vault and Egress Gateway for seamless integration.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml)) **and routes traffic through the Egress Gateway** ([`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) to create a `credentialVault` entry. The `name` field serves as a unique reference for binding to egress rules later.

```yaml

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml), grant the sandbox permission to contact specific external hosts and bind the credential vault entry to that destination.

```yaml

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

```json
{
  "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:

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

```yaml

# configs/single-node/cubemaster.yaml

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

```

```yaml

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

```yaml

# configs/single-node/cubemaster.yaml

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

```

```yaml

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

```json
{
  "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`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml)** — Defines the **credential vault** entries used for secret injection.

- **[`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml)** — Contains **egress policy** definitions including allow-l