# CubeSandbox Default Configuration Settings: Complete Single-Node Setup Guide

> Explore CubeSandbox default configuration settings for single-node setup. Learn about cubemaster and cubelet YAML files, ports, and environment variables for seamless deployment.

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

---

**CubeSandbox default configuration settings are defined in YAML files located in `configs/single-node/`, including [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml) (HTTP port 8089, gRPC port 9999) and [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml) (72h code expiration, network agent enabled), with environment variable placeholders for database credentials and hardware quotas.**

**CubeSandbox** is an open-source, high-performance sandbox platform designed for AI agents, developed by TencentCloud. It delivers sub-60ms sandbox startup using hardware-level isolation via dedicated KVM micro-VMs. Understanding the default configuration settings is essential for deploying the single-node reference architecture or extending the platform to a multi-node cluster.

## Core Architecture Overview

Before examining the configuration files, it is important to understand the components that consume these settings. CubeSandbox consists of loosely coupled services that communicate via gRPC or Unix domain sockets.

### CubeAPI

**CubeAPI** is the high-concurrency REST gateway written in Rust that exposes an E2B-compatible HTTP API. It handles client requests and translates them into gRPC calls to the master node. The service implementation resides in [`CubeAPI/src/services/sandboxes.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/services/sandboxes.rs).

### CubeMaster

**CubeMaster** acts as the cluster orchestrator. It processes API requests, schedules sandboxes onto appropriate nodes, and maintains cluster state. The default configuration for this component is stored in [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml).

### Cubelet

**Cubelet** is the node-level compute agent that manages the lifecycle of sandboxes on a single host. It instantiates KVM micro-VMs and handles storage snapshots. Its behavior is controlled by [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml).

### Supporting Infrastructure

- **CubeProxy**: Reverse-proxy compatible with the E2B protocol; routes traffic to sandbox instances (see [`CubeProxy/nginx.conf`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeProxy/nginx.conf)).
- **CubeVS**: eBPF-based virtual switch enforcing kernel-level network isolation.
- **CubeEgress**: OpenResty-powered egress gateway handling L7 domain allow-listing and credential injection (see [`CubeEgress/lua/policy.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeEgress/lua/policy.lua)).

## Default Configuration Files

CubeSandbox ships with ready-to-use YAML configurations in the `configs/single-node/` directory. These files contain sensible defaults optimized for development and testing, which can be overridden via environment variables.

### cubemaster.yaml Configuration

The **cubemaster.yaml** file defines the control plane settings. It resides at [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml).

```yaml
common:
  http_port: 8089              # HTTP API port

  http_bind: __CUBEMASTER_HTTP_BIND__   # Bind address (0.0.0.0 = all)

  http_readtimeout: 120
  http_writetimeout: 360
  http_idletimeout: 360
  sync_meta_data_interval: 30s
  sync_metric_data_interval: 1s
  collect_metric_interval: 1s
  default_headless_service_nodes_num: 1
  enable_check_com_net_id_param: false

log:
  module: "cubemaster"
  path: "/data/log/CubeMaster"
  file_size: 100
  file_num: 10
  level: "info"

cubelet_conf:
  grpc:
    grpc_port: 9999
  common_timeout_insec: 30
  create_image_timeout_insec: 300
  default_timeout_insec: -1
  create_timeout_insec: 300
  enable_exposed_port: true
  exposed_port_list:
    - "80"
  disable_redis_proxy_port: true

auth:
  enable: false

```

Key default settings include:

- **HTTP binding**: The server listens on port `8089`. The bind address uses the placeholder `__CUBEMASTER_HTTP_BIND__`, which defaults to `0.0.0.0` for multi-node visibility or `127.0.0.1` for single-node hardening.
- **Metrics synchronization**: The master syncs metric data every `1s` to maintain a fresh cluster view.
- **Cubelet communication**: The internal gRPC control channel uses port `9999`.
- **Exposed ports**: By default, only port `80` is exposed to sandboxes. Additional ports must be added explicitly to the `exposed_port_list`.
- **Authentication**: Disabled by default (`enable: false`), suitable for development environments only.

### cubelet.yaml Configuration

The **cubelet.yaml** file configures the node agent behavior. It is located at [`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml).

```yaml
common:
  common_timeout: "10s"
  enable_network_agent: true
  network_agent_endpoint: "grpc+unix:///tmp/cube/network-agent-grpc.sock"

host:
  scheduler_label: "default-cluster"
  quota:
    mcpu_limit: 0
    mem_limit: ""
    mvm_limit: 0
    creation_concurrent_num: 0
    paused_resource_release_ratio: 0.0
  gc:
    code_expiration_time: "72h"
    image_expiration_time: "24h"

```

Critical defaults include:

- **Network agent**: Enabled by default (`enable_network_agent: true`). The cubelet communicates with the local network agent via the Unix domain socket at `/tmp/cube/network-agent-grpc.sock` for eBPF policy enforcement.
- **Resource quotas**: `mcpu_limit` and `mem_limit` are set to `0` and empty strings respectively, meaning no limits are enforced by default.
- **Garbage collection**: Sandbox code is automatically pruned after `72h`, while images expire after `24h`.

### Database and Redis Placeholders

Both configuration files contain placeholder variables for external dependencies:

- Database connections use the pattern `__CUBE_SANDBOX_MYSQL_*__` (host, port, user, password).
- Redis connections use `__CUBE_SANDBOX_REDIS_*__`.

In production deployments, these placeholders are replaced via environment variables or secret management solutions. The **credential vault** ensures that keys never flow into the sandbox itself.

## Customizing Configuration with Environment Variables

CubeSandbox supports environment variable substitution for all settings marked with double underscores. For example:

- `__CUBEMASTER_HTTP_BIND__` controls the HTTP bind address.
- `__CUBE_SANDBOX_MYSQL_PORT__` specifies the database port.

This pattern allows the same YAML files to be used across development, staging, and production environments without modification.

## Practical Configuration Examples

### Creating a Sandbox via HTTP API

The following Python example uses the default HTTP port `8089` defined in [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml):

```python
import requests

# Replace with your CubeMaster endpoint

BASE_URL = "http://<master-ip>:8089/v1"
API_KEY = "YOUR_E2B_API_KEY"

payload = {
    "template_id": "e2b-demo/python",
    "timeout": 300,
    "allow_internet_access": True,
    "metadata": {"example_key": "example_value"},
    "env_vars": {"PYTHONPATH": "/app"},
    "network": {"allow_internet_access": True}
}

resp = requests.post(
    f"{BASE_URL}/sandboxes",
    json=payload,
    headers={"Authorization": f"Bearer {API_KEY}"}
)

print(resp.json())

```

This follows the request model defined in [`CubeAPI/src/models.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/models.rs).

### Listing Sandboxes with Go Client

```go
package main

import (
    "context"
    "fmt"
    "github.com/tencentcloud/cubesandbox/CubeAPI/client"
)

func main() {
    c, err := client.NewCubeMasterClient("unix:///tmp/cube/master-grpc.sock")
    if err != nil {
        panic(err)
    }
    svc := client.NewSandboxService(c, "demo", "sandbox.cubesandbox.com")
    list, err := svc.List(context.Background(), nil, nil, 10)
    if err != nil {
        panic(err)
    }
    for _, sb := range list {
        fmt.Printf("Sandbox %s – state %s\n", sb.SandboxID, sb.State)
    }
}

```

The Go client mirrors the Rust service implementation in [`CubeAPI/src/services/sandboxes.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeAPI/src/services/sandboxes.rs).

### Configuring Egress Policies

To customize outbound traffic rules, modify [`CubeEgress/lua/policy.lua`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeEgress/lua/policy.lua):

```lua
local policy = {
    allow = { "api.openai.com", "github.com" },
    deny = { "example.com" },
    inject = {
        { name = "API_KEY", value = "REDACTED" }
    }
}
return policy

```

The egress gateway applies these rules to all sandbox outbound traffic, performing L7 domain filtering and secure credential injection.

## Summary

- **CubeSandbox** default configurations reside in [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) and [`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml).
- **cubemaster.yaml** defaults to HTTP port `8089`, gRPC port `9999`, and exposes only port `80` to sandboxes.
- **cubelet.yaml** enables the network agent by default, sets no resource limits (values of `0`), and configures garbage collection for code (`72h`) and images (`24h`).
- **Environment variables** (e.g., `__CUBEMASTER_HTTP_BIND__`) override YAML values without modifying files.
- **Authentication is disabled** by default; enable it before production deployment.
- **Credential placeholders** (`__CUBE_SANDBOX_MYSQL_*__`) require substitution for database connectivity.

## Frequently Asked Questions

### How do I change the default HTTP port in CubeSandbox?

Modify the `http_port` value in [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) or set the environment variable `__CUBEMASTER_HTTP_PORT__`. The default is `8089`. Remember to update any client configurations or firewall rules to match the new port.

### What is the default sandbox expiration time?

By default, sandbox code expires after **72 hours** and container images expire after **24 hours**, as defined in [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml) under the `gc` section. These values are controlled by `code_expiration_time` and `image_expiration_time`.

### How do I expose additional ports beyond port 80?

Edit the `exposed_port_list` array in [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml). The default configuration only exposes port `"80"`. Add your desired ports as strings to this list and restart the CubeMaster service. The `enable_exposed_port` setting must remain `true`.

### Are resource limits enforced by default in CubeSandbox?

No. The default [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml) sets `mcpu_limit: 0`, `mem_limit: ""`, and `mvm_limit: 0`, which means no CPU, memory, or micro-VM limits are enforced. To enable quotas, set these to specific values (e.g., `mcpu_limit: 4000` for 4 CPUs) according to your node capacity.