CubeSandbox Default Configuration Settings: Complete Single-Node Setup Guide

CubeSandbox default configuration settings are defined in YAML files located in configs/single-node/, including cubemaster.yaml (HTTP port 8089, gRPC port 9999) and 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.

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.

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.

Supporting Infrastructure

• CubeProxy: Reverse-proxy compatible with the E2B protocol; routes traffic to sandbox instances (see 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).

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.

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.

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:

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.

Listing Sandboxes with Go Client

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.

Configuring Egress Policies

To customize outbound traffic rules, modify CubeEgress/lua/policy.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 and 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 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 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. 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 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.

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