How CubeSandbox Handles Sandboxing: Container Isolation Architecture

CubeSandbox isolates user workloads by provisioning lightweight container-style sandboxes through the CubeMaster/pkg/service/sandbox package, utilizing Linux namespaces, read-only root images with overlay filesystems, virtualized networking, and strict cgroup-based resource limits.

CubeSandbox, an open-source project from TencentCloud, provides secure workload isolation for multi-tenant environments. This article examines exactly how CubeSandbox handles sandboxing by dissecting the core components within the CubeMaster/pkg/service/sandbox package and tracing the complete execution lifecycle from initialization to resource cleanup.

Core Sandboxing Components

The sandbox implementation relies on specialized modules that enforce isolation at different layers of the system stack.

Lifecycle Management

The sandbox_run.go file orchestrates the creation and destruction of sandboxes. It initializes new instances via sandbox_init and launches them through the underlying container runtime. When execution completes or timeouts occur, sandbox_remove.go handles complete teardown of containers, network namespaces, and mount points.

Namespace and Filesystem Isolation

Isolation begins with namespace separation. The sandbox launches with --private-mount and --network flags defined in sandbox_init.go, creating distinct PID, IPC, mount, and network namespaces. For filesystem isolation, image.go prepares a read-only base image while optionally attaching mutable overlay filesystems for temporary writeable layers, ensuring the root filesystem remains immutable.

Network Virtualization and Port Exposure

Network isolation is enforced through dedicated virtual interfaces and NAT/bridge rules configured in exposed_port_endpoint.go. This ensures sandbox traffic remains separate from the host and other sandboxes. The hostdir_mount.go component manages port forwarding and safe bind-mounts of host directories when necessary.

Security Context and Resource Control

Security hardening includes privilege dropping, SELinux/AppArmor profiles, and cgroup limits for CPU, memory, and IO. The sandbox_timeout.go and timeout_provider.go files enforce execution time limits, while sandbox_update.go provides dynamic adjustments to cgroup settings during runtime.

Runtime Hooks and Metadata

The runtime_ref_hook.go file registers callbacks that inject metadata—such as template identity—into the sandbox lifecycle. These hooks execute during startup and cleanup phases, ensuring proper state management and resource accounting.

The Sandbox Execution Workflow

CubeSandbox handles sandboxing through a five-phase workflow that ensures complete isolation and cleanup:

1. Initialization – sandbox_init.go builds the sandbox definition, specifying the container image, mount points, network configuration, and security settings.
2. Launch – sandbox_run.go invokes the container runtime (Docker, containerd, or a custom runtime) with the prepared definition.
3. Execution – Users run commands inside the sandbox via sandbox_exec.go or sandbox_admit.go, which handle process admission and execution within the isolated environment.
4. Monitoring – sandbox_timeout.go continuously monitors execution time, while runtime_ref_hook.go updates internal state and triggers callbacks.
5. Teardown – Upon completion or timeout, sandbox_remove.go cleans up all resources including containers, network namespaces, and mount points.

Practical Implementation Example

The following Go code demonstrates creating and managing a sandbox using the CubeSandbox API:

// 1️⃣ Create a sandbox configuration (image, mounts, timeout)
cfg := sandbox.NewConfig().
    WithImage("cube-sandbox-base:latest").
    WithTimeout(30 * time.Minute).
    WithMounts([]sandbox.Mount{
        {HostPath: "/var/log/app", ContainerPath: "/app/log", ReadOnly: true},
    })

// 2️⃣ Launch the sandbox
sb, err := sandbox.New(cfg)
if err != nil {
    log.Fatalf("failed to create sandbox: %v", err)
}
defer sb.CleanUp() // guarantees removal

// 3️⃣ Run a command inside the sandbox
out, err := sb.Exec(context.Background(), sandbox.ExecOptions{
    Cmd: []string{"/bin/bash", "-c", "echo Hello from sandbox"},
})
if err != nil {
    log.Fatalf("exec failed: %v", err)
}
fmt.Println(string(out))

// 4️⃣ Optional: expose a port from the sandbox
port, err := sb.ExposePort(8080)
if err != nil {
    log.Fatalf("port expose failed: %v", err)
}
fmt.Printf("Sandbox reachable at host port %d\n", port)

Key Source Files in CubeMaster/pkg/service/sandbox

Understanding how CubeSandbox handles sandboxing requires familiarity with these specific implementation files:

• sandbox/init.go – Builds the sandbox definition including image selection, mount configuration, and security policies.
• sandbox/run.go – Starts the sandbox via the container runtime interface.
• sandbox/exec.go – Handles command execution within running sandboxes.
• sandbox/remove.go – Tears down sandboxes and releases all associated resources.
• sandbox/timeout.go – Enforces execution timeout policies and triggers termination.
• sandbox/runtime_ref_hook.go – Provides lifecycle hooks for metadata injection and cleanup.
• sandbox/image.go – Manages base image preparation and overlay filesystem setup.
• sandbox/hostdir_mount.go – Validates and performs safe host directory bind-mounts.
• sandbox/exposed_port_endpoint.go – Configures network port mapping between host and sandbox.

Summary

• CubeSandbox provisions lightweight container-style sandboxes through the CubeMaster/pkg/service/sandbox package.
• Namespace isolation (PID, IPC, mount, network) is enforced via --private-mount and --network flags during initialization.
• Filesystem isolation combines read-only base images with mutable overlay layers managed by image.go.
• Network virtualization in exposed_port_endpoint.go isolates traffic while allowing controlled port exposure.
• Resource limits and security policies are enforced through cgroups, SELinux/AppArmor, and timeout mechanisms in sandbox_timeout.go.
• The five-phase workflow (Initialization, Launch, Execution, Monitoring, Teardown) ensures complete lifecycle management.

Frequently Asked Questions

What container runtime does CubeSandbox use for sandboxing?

According to the TencentCloud/CubeSandbox source code, the sandbox_run.go implementation supports multiple container runtimes including Docker, containerd, or custom runtimes. The system invokes the configured runtime through a standardized interface while managing the sandbox lifecycle independently.

How does CubeSandbox enforce timeout limits?

The sandbox_timeout.go and timeout_provider.go files implement timeout enforcement by monitoring execution duration and triggering forced termination when the configured limit expires. This prevents sandboxes from consuming resources indefinitely.

Can CubeSandbox expose network ports from isolated workloads?

Yes. The exposed_port_endpoint.go file manages network port mapping between the host and sandbox environments. The API provides ExposePort() functionality that configures NAT rules while maintaining network isolation between different sandboxes.

How are host directories safely mounted into sandboxes?

The hostdir_mount.go file validates and performs safe bind-mounts of host directories into the sandbox filesystem. This allows selective exposure of host paths (such as logs or configuration files) with configurable read-only or read-write permissions while maintaining filesystem isolation boundaries.

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