# How CubeSandbox Handles Sandboxing: Container Isolation Architecture

> Discover how CubeSandbox handles sandboxing using container isolation. Explore Linux namespaces, overlay filesystems, virtual networking, and cgroup limits for secure workload execution.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_init.go), creating distinct PID, IPC, mount, and network namespaces. For filesystem isolation, [`image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/exposed_port_endpoint.go). This ensures sandbox traffic remains separate from the host and other sandboxes. The [`hostdir_mount.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_timeout.go) and [`timeout_provider.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/timeout_provider.go) files enforce execution time limits, while [`sandbox_update.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_update.go) provides dynamic adjustments to cgroup settings during runtime.

### Runtime Hooks and Metadata

The [`runtime_ref_hook.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_init.go) builds the sandbox definition, specifying the container image, mount points, network configuration, and security settings.
2. **Launch** – [`sandbox_run.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_exec.go) or [`sandbox_admit.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_admit.go), which handle process admission and execution within the isolated environment.
4. **Monitoring** – [`sandbox_timeout.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_timeout.go) continuously monitors execution time, while [`runtime_ref_hook.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/runtime_ref_hook.go) updates internal state and triggers callbacks.
5. **Teardown** – Upon completion or timeout, [`sandbox_remove.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```go
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/init.go)** – Builds the sandbox definition including image selection, mount configuration, and security policies.
- **[`sandbox/run.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/run.go)** – Starts the sandbox via the container runtime interface.
- **[`sandbox/exec.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/exec.go)** – Handles command execution within running sandboxes.
- **[`sandbox/remove.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/remove.go)** – Tears down sandboxes and releases all associated resources.
- **[`sandbox/timeout.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/timeout.go)** – Enforces execution timeout policies and triggers termination.
- **[`sandbox/runtime_ref_hook.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/runtime_ref_hook.go)** – Provides lifecycle hooks for metadata injection and cleanup.
- **[`sandbox/image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/image.go)** – Manages base image preparation and overlay filesystem setup.
- **[`sandbox/hostdir_mount.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox/hostdir_mount.go)** – Validates and performs safe host directory bind-mounts.
- **[`sandbox/exposed_port_endpoint.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/image.go).
- **Network virtualization** in [`exposed_port_endpoint.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/sandbox_timeout.go) and [`timeout_provider.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.