# CubePod Full Documentation Corpus (v0.4.0)

Source: https://cubepod.cubeplex.ai

---
# E2B Drop-in Compatibility
URL: https://cubepod.cubeplex.ai/getting-started/e2b-compatibility/

CubePod provides **wire-level drop-in compatibility** with official E2B SDKs (`e2b`, `e2b-code-interpreter`, `@e2b/code-interpreter`) as specified in [CEP-0018](/ceps/0018-e2b-protocol-compatibility/) and [CEP-0019](/ceps/0019-e2b-template-api/). Existing LangChain, LlamaIndex, AutoGen, CrewAI, OpenHands, and Smolagents pipelines can switch from hosted E2B to self-hosted persistent Kata MicroVMs simply by setting environment variables.

## Pointing Official E2B SDKs at CubePod

Configure your environment according to whether `cubepod-gateway` sits behind HTTPS wildcard ingress or is accessed over local HTTP:

### Production HTTPS + Wildcard Ingress

```bash
export E2B_DOMAIN="cubepod.example.com"
export E2B_API_KEY="cpod_live_secret"
```

When `E2B_DOMAIN` is set, official E2B SDKs send control-plane calls to `api.<E2B_DOMAIN>` and sandbox port traffic to `<port>-<sandboxID>.<E2B_DOMAIN>` (`cubepod-gateway` matches `^([0-9]+)-([a-zA-Z0-9_-]+)\.(.*)$` in the `Host` header).

### Local HTTP / Direct Gateway

When testing against `http://127.0.0.1:8080` without TLS or wildcard DNS, set both `E2B_API_URL` and `E2B_SANDBOX_URL` (the same configuration used by CubePod's `test/e2b-compat/` suite):

```bash
export E2B_API_URL="http://127.0.0.1:8080"
export E2B_SANDBOX_URL="http://127.0.0.1:8080"
export E2B_API_KEY="cpod_test_api_key"
```

## Unmodified Official E2B Examples

### Official `e2b` Python SDK (Sync & Async)

```python
from e2b import Sandbox

# Uses E2B_API_URL / E2B_SANDBOX_URL / E2B_DOMAIN automatically
with Sandbox.create("base", timeout=300) as sbx:
    sbx.files.write("/workspace/data.txt", "hello from e2b sdk")
    result = sbx.commands.run("cat /workspace/data.txt")
    print(result.stdout)
```

### Official `e2b-code-interpreter` SDK

`podd` exposes stateful execution contexts for 6 languages (`python`, `bash`, `javascript`, `typescript`, `r`, `java`) over NDJSON streams compatible with `e2b-code-interpreter`:

```python
from e2b_code_interpreter import Sandbox

with Sandbox.create() as sbx:
    sbx.run_code("x = 21 * 2")
    execution = sbx.run_code("print(f'result={x}')")
    print(execution.logs.stdout)
```

## Protocol Surface Implemented by `cubepod-gateway`

`cubepod-gateway` (`pkg/gateway/`) implements both E2B's control plane and data plane (including Connect-RPC `envd` semantics on port `49983`):

| Surface | Endpoints Implemented | Behavior in CubePod |
| :--- | :--- | :--- |
| **Control Plane** | `POST /sandboxes`, `POST /v2/sandboxes`, `GET /sandboxes`, `GET /v2/sandboxes`, `GET /sandboxes/{id}`, `DELETE /sandboxes/{id}` | Provisions or lists `PodBox` sandboxes; always populates mandatory E2B fields (`sandboxID`, `templateID`, `clientID`, `envdVersion`, `state`, `startedAt`, `endAt`, `cpuCount`, `memoryMB`, `diskSizeMB`). |
| **Lifecycle & Leases** | `POST /sandboxes/{id}/refreshes`, `POST /sandboxes/{id}/timeout`, `POST /sandboxes/{id}/pause`, `POST /sandboxes/{id}/connect` | Renews idle timers/leases, tears down compute on pause while retaining PVCs, and transparently auto-resumes paused sandboxes on `connect`. |
| **Commands & Streaming** | `POST /sandboxes/{id}/commands`, `POST /sandboxes/{id}/commands/run`, `GET .../logs?cursor=N`, `POST .../kill`, Connect-RPC `/process.Process/{Start,SendSignal,Connect,List}` | Executes commands inside the guest as unprivileged UID/GID `1000:1000` (`cubeplex`) with cursor-based incremental streaming and PGID cleanup. |
| **Filesystem & Sync** | `PUT/GET/DELETE /sandboxes/{id}/files`, `GET .../files/list`, `POST .../files/archive-sync`, Connect-RPC `/filesystem.Filesystem/{Read,Write,List,ListDir,Stat,Remove,MakeDir}` | Performs direct guest I/O and path-traversal-safe `.tar`/`.tar.gz` directory sync against persistent `/workspace` or RootFS paths. |
| **Code Interpreter** | `POST /sandboxes/{id}/execute`, `POST /sandboxes/{id}/code/execute`, `/contexts` | Manages stateful multi-language REPL kernels inside `podd` (`python`, `bash`, `javascript`, `typescript`, `r`, `java`). |
| **Subdomain Port Routing** | `Host: <port>-<sandboxID>.<domain>` and `GET/POST /sandboxes/{id}/endpoints/{port}` | Auto-resumes paused sandboxes if needed, rewrites `/envd/*` to `podd` (`:49983`), and proxies arbitrary guest app ports or mints signed `/panel/{token}/` URLs. |
| **Template Catalog & Builds** | `/templates`, `/v2/templates`, `/v3/templates`, `/templates/{id}/builds/{buildID}/status`, `/templates/{id}/files/{hash}` | Enabled via `--e2b-template-api=true` (or `-feature-gate E2BTemplateAPI=true`) for `e2b template build` workflows. |

## CubePod Superset Capabilities Beyond E2B

When you use CubePod's native SDKs ([Python](/sdks/python/), [TypeScript](/sdks/typescript/), [Go & CLI](/sdks/go-and-cli/)) or REST superset endpoints, you unlock features not present in standard E2B:

- **Persistent Writable OS RootFS & Non-Destructive OS Reset**: `POST /sandboxes/{id}/reset-rootfs` increments `spec.rootfsGeneration`, allocating a fresh OS `upperdir` PVC while preserving `/workspace`.
- **1-Second CoW Forking**: `POST /sandboxes/{id}/fork` triggers `FIFREEZE` quiesce -> CSI/reflink clone -> `FITHAW` to branch both OS and `/workspace` state without disturbing the running parent.
- **Zero-Trust `cpodref_` Egress Vault**: Pass `secretBindings` at sandbox creation so agents only ever see `cpodref_` placeholders while `cubepod-egress` injects real credentials at the network boundary.
- **Lazy Interactive Desktops**: Call `/sandboxes/{id}/desktop/{start,status,stop}` to spin up `Xvfb`, Chromium CDP, `noVNC`, and `ttyd` on demand behind signed `/panel/{token}/` endpoints.

## Next Steps

- See the **[API Reference](/api/)** for the full OpenAPI 3.1 contract (`api/openapi/cubepod-v1.yaml`).
- Compare native clients in **[Python SDK](/sdks/python/)** and **[TypeScript SDK](/sdks/typescript/)**.
- Inspect **[CRD Reference](/reference/crds/)** for Kubernetes `PodBox` and `PodTemplate` schemas.

---
# Introduction
URL: https://cubepod.cubeplex.ai/getting-started/introduction/

**CubePod** is an open-source, cloud-native **Persistent Writable RootFS MicroVM Execution Platform for AI Agents**, built to power **CubePlex** and the broader **E2B / MCP** open-source ecosystem.

Unlike stateless container runners or ephemeral sandboxes that discard installed dependencies, browser state, and system configuration whenever a session pauses or restarts, CubePod gives every AI agent a hardware-isolated sandbox whose **entire OS filesystem (`/`, `/usr`, `/etc`, `/var/lib`) and user project directory (`/workspace`) both persist independently**.

## Why Persistent Writable RootFS Matters

Modern autonomous agents do far more than evaluate isolated Python snippets. Over multi-hour or multi-day tasks they install system packages (`apt`, `pip`, `npm`, Playwright browsers), configure systemd or background daemons, authenticate CLI tools, compile code, and edit repositories.

Standard sandbox platforms leave you with an awkward trade-off:

- **Ephemeral MicroVMs** offer strong hypervisor isolation, but their RootFS lives only in RAM/scratch layers — pausing or restarting wipes OS packages and system state unless you rebuild custom base images on every mutation.
- **Persistent Volume Containers** keep `/workspace` alive, but lack hardware VM boundaries and force agents to reinstall OS packages or lose system config across pod restarts.

CubePod removes this compromise by booting **stock, unmodified OCI images** inside **Kata Containers MicroVMs** backed by **dual persistent volumes**: one volume holds an `OverlayFS` writable `upperdir` for the entire Linux RootFS, while a second volume exclusively stores `/workspace`.

## Platform Comparison

| Capability | Plain Containers | Ephemeral MicroVMs | CubePod |
| :--- | :--- | :--- | :--- |
| **Compute Isolation** | Shared host Linux kernel | Hardware VM (`Firecracker` / `QEMU`) | Hardware VM (`Kata QEMU` / `Cloud Hypervisor`) + local Docker loopback |
| **OS RootFS Persistence** | Ephemeral writable layer | Ephemeral scratch layer | **Persistent `OverlayFS` `upperdir`** (`<box>-rootfs-pvc`) |
| **Workspace Persistence** | Optional PVC mount | Optional or lost on stop | **Decoupled persistent volume** (`<box>-workspace-pvc`) |
| **RootFS Reset / OS Upgrade** | Recreate container | Image rebuild | Monotonic `rootfsGeneration` swap — **`/workspace` stays intact** |
| **Cold Start Latency** | ~1–3 s | ~150 ms | **`< 50 ms`** via pre-attached `PodWarmPool` CAS claims |
| **Compute Pause-to-Zero** | Deletes state on stop | Snapshot or ephemeral stop | `desiredState: Paused` tears down compute (`0 CPU / 0 RAM`), keeps dual PVCs |
| **State Cloning (CoW Fork)** | Slow image commit | VM snapshot | **Crash-consistent CoW fork** (`FIFREEZE` -> CSI clone / reflink -> `FITHAW`) |
| **Secret & Egress Safety** | Real env vars inside sandbox | Real env vars inside sandbox | **`cpodref_` placeholders** + selective MITM over per-pod mTLS |
| **SDK & Protocol Ecosystem** | Custom APIs | E2B REST / Connect-RPC | **100% E2B drop-in compatible** + native Python, TS, Go, CLI, MCP |

## Core Architectural Pillars

1. **[Dual-Volume Persistence](/concepts/dual-volume-persistence/)**: Isolates the writable OS RootFS (`<box>-rootfs-pvc` or `<box>-rootfs-gen<N>-pvc`) from user project files (`<box>-workspace-pvc` mounted at `/workspace`). Incrementing `rootfsGeneration` wipes or upgrades OS mutations without losing a byte in `/workspace`.
2. **[Clean OCI Images via `podd-init` & `podd`](/concepts/in-guest-init-and-podd/)**: Runtime binaries are never baked into user images. An `initContainer` (`podd-installer`) or host bind-mount injects `/opt/cubepod/bin/{podd-init,podd}` at startup. A single-threaded Rust PID 1 (`podd-init`) checks/heals `ext4`, mounts `OverlayFS`, pivots root (`pivot_root`), and execs into `podd` (`:49983`).
3. **[WarmPool, Pause-to-Zero, CoW Fork & Stateless HA](/concepts/lifecycle-warmpool-fork/)**: `PodWarmPool` pre-attaches standby MicroVMs claimed atomically in `< 50 ms`. `spec.forkFrom` performs crash-consistent cloning (`FIFREEZE`/`FITHAW` + CSI or `cp --reflink=auto`), and `cubepod-gateway` reconstructs state directly from Kubernetes `PodBox` CRDs for multi-replica HA.
4. **[Drop-in E2B Compatibility](/getting-started/e2b-compatibility/)**: Point `E2B_DOMAIN` or `E2B_API_URL` at `cubepod-gateway` so existing `e2b`, `e2b-code-interpreter`, `@e2b/code-interpreter`, LangChain, LlamaIndex, and OpenHands workflows run unmodified.
5. **[Zero-Trust Egress & Secret Vault](/concepts/zero-trust-egress/)**: Real API keys never enter sandbox memory or disk. Only `cpodref_` 32-character Base32 placeholders are injected; `cubepod-egress` intercepts outbound traffic (`nftables` + DNS proxy + selective HTTPS MITM) and swaps placeholders over per-pod mTLS against `cubepod-gateway`.
6. **[Lazy Interactive Desktop & Signed Panel Proxy](/concepts/desktop-and-panel-proxy/)**: GUI images start with ~0 MiB desktop RAM overhead and launch `Xvfb`, `openbox`, Chromium CDP (`:9222`), `x11vnc`/`noVNC` (`:8080`), and `ttyd` (`:7681`) on demand, exposed securely via HMAC-SHA256 `/panel/{token}/` URLs.

## Dual-Runtime Fidelity

Every CubePod subsystem runs with behavioral parity across two environments:

- **Production Kubernetes (`Kata + CSI Block`)**: Hardware-isolated Pods (`kata-qemu` / `kata-clh`) attaching two `volumeMode: Block` PVCs (`/dev/cubepod-rootfs` and `/dev/cubepod-workspace`), with `volumeMode: Filesystem` fallback when CSI raw block storage is unavailable.
- **Local Development (`Docker + Loopback ext4`)**: Running `CUBEPOD_RUNTIME_MODE=docker-loopback` (including via Docker Compose) backs each sandbox with sparse `.ext4` loopback files and runs the exact same `podd-init` + `podd` in-guest stack on your laptop.

## Next Steps

- Launch a local stack and run your first persistent sandbox in the **[Quickstart](/getting-started/quickstart/)**.
- Connect existing E2B agents with **[E2B Drop-in Compatibility](/getting-started/e2b-compatibility/)**.
- Dive into the control and data plane in **[Platform Architecture](/concepts/architecture/)**.
- Deploy to production clusters with **[Kubernetes & Helm Deployment](/deployment/kubernetes-helm/)**.

---
# Quickstart
URL: https://cubepod.cubeplex.ai/getting-started/quickstart/

Get CubePod running locally in minutes using `docker-compose`, then interact with your persistent sandboxes through the Python SDK, TypeScript SDK, or `cubepod` CLI.

## Prerequisites

- **Docker Engine** with Docker Compose v2 (`docker compose`)
- **Python 3.11+** (for the Python SDK) and/or **Node.js 20+** (for the TypeScript SDK)
- *(Optional, if building binaries from source)* **Go 1.22+** and **Rust** (`cargo`)

## 1. Start the Local Control Plane

From the root of the CubePod repository, boot `cubepod-gateway` (`:8080`), `cubepod-controller` (`:8081`), and `cubepod-egress` (`:18080`):

```bash
docker compose -f deploy/docker-compose/docker-compose.yaml up -d --build
```

Verify that the gateway is healthy:

```bash
curl -fsS http://127.0.0.1:8080/health
```

> **Note:** `deploy/docker-compose/docker-compose.yaml` sets `CUBEPOD_RUNTIME_MODE=docker-loopback` on `cubepod-gateway`, mounts `/var/run/docker.sock` and `cubepod-volumes`, and starts `cubepod-egress` with `-default-allow=true` for local development. For building all Rust and Go binaries locally without Docker Compose, run `make build` (`bin/podd-init`, `bin/podd`, `bin/cubepod-controller`, `bin/cubepod-gateway`, `bin/cubepod-egress`, and `bin/cubepod`).

## 2. Create a Sandbox & Verify Persistence

Choose your preferred client SDK or the native CLI below.

### Python SDK

Install the Python SDK from PyPI or from `sdks/python/` in the repository:

```bash
pip install cubepod
```

Create a sandbox, write files to `/workspace`, execute commands, pause compute (`0 CPU / 0 RAM`), reconnect, and create a Copy-on-Write fork:

```python
from cubepod import CubePod

with CubePod(base_url="http://127.0.0.1:8080") as client:
    # 1. Create a persistent sandbox
    sbx = client.create("cubeplex-ubuntu24-desktop", timeout_seconds=3600)
    print("Created:", sbx.sandbox_id, "state:", sbx.state)

    # 2. Write a file in /workspace and run a command
    client.write_file(sbx.sandbox_id, "/workspace/hello.txt", b"persistent data\n")
    res = client.execute(sbx.sandbox_id, "cat /workspace/hello.txt && id")
    print("Output:", res.output)

    # 3. Pause compute (retains both rootfs and /workspace volumes)
    client.pause(sbx.sandbox_id)

    # 4. Resume on connect and verify state survived pause
    client.connect(sbx.sandbox_id)
    print("After resume:", client.read_text_file(sbx.sandbox_id, "/workspace/hello.txt"))

    # 5. Create an independent Copy-on-Write fork
    child = client.fork(sbx.sandbox_id)
    print("Forked child sandbox:", child.sandbox_id)

    # 6. Clean up both sandboxes
    client.delete(child.sandbox_id)
    client.delete(sbx.sandbox_id)
```

### TypeScript / Node.js SDK

The official TypeScript SDK has zero external runtime dependencies on Node.js 20+:

```bash
npm install cubepod
```

```typescript
import { Sandbox } from 'cubepod';

const sandbox = await Sandbox.create('cubeplex-ubuntu24-desktop', {
  baseUrl: 'http://127.0.0.1:8080',
  timeoutSeconds: 3600,
});

await sandbox.files.write('/workspace/hello.txt', 'persistent data\n');
const cmd = await sandbox.commands.run('cat /workspace/hello.txt');
console.log('Command output:', cmd.output);

// Run code via podd's built-in stateful interpreter (Python, Bash, JS, TS, R, Java)
const exec = await sandbox.code.runCode('print(6 * 7)', { language: 'python' });
console.log('Interpreter:', exec.output);

// Pause and later reconnect transparently
await sandbox.pause();
await sandbox.connect();

// Crash-consistent CoW fork
const child = await sandbox.fork();
await child.kill();
await sandbox.kill();
```

### `cubepod` CLI

Build the CLI with `make build-cli` (outputs `bin/cubepod`), then drive the full lifecycle from your terminal:

```bash
export CUBEPOD_GATEWAY_URL="http://127.0.0.1:8080"

# Check gateway health
./bin/cubepod health

# Create a sandbox and run a command
./bin/cubepod sandbox create --template cubeplex-ubuntu24-desktop
./bin/cubepod sandbox exec <sandbox-id> "uname -a && id"

# Upload/read files and sync a directory as tar.gz
./bin/cubepod sandbox write-file <sandbox-id> /workspace/app.py "print('hello from cubepod')"
./bin/cubepod sandbox read-file <sandbox-id> /workspace/app.py
./bin/cubepod sandbox archive-sync <sandbox-id> /workspace/project ./local-project

# Pause, reconnect, fork, reset OS rootfs (keeping /workspace), or delete
./bin/cubepod sandbox pause <sandbox-id>
./bin/cubepod sandbox connect <sandbox-id>
./bin/cubepod sandbox fork <sandbox-id>
./bin/cubepod sandbox reset-rootfs <sandbox-id>
./bin/cubepod sandbox delete <sandbox-id>
```

## 3. Reset RootFS Without Losing `/workspace`

If an agent installs broken system libraries or corrupts OS state under `/etc` or `/usr`, you can reset the RootFS layer while keeping `/workspace` intact:

```python
# Wipes the persistent OverlayFS upperdir (allocates rootfs-gen<N>)
# while re-attaching the exact same /workspace volume.
client.reset_rootfs(sbx.sandbox_id)
```

Read [Dual-Volume Persistence](/concepts/dual-volume-persistence/) to see how `rootfsGeneration` keeps OS upgrades and project data strictly separated.

## 4. Launch an Interactive Desktop (Optional)

When using a desktop-capable template image (see [Interactive Desktop & Panel Proxy](/concepts/desktop-and-panel-proxy/)), you can lazily start `Xvfb`, `openbox`, Chromium CDP, `noVNC`, and `ttyd` inside the sandbox:

```python
session = client.start_desktop(
    sbx.sandbox_id,
    resolution="1280x800x24",
    initial_url="https://example.com",
)
print("noVNC URL:", session.desktop_url)
print("Terminal URL:", session.terminal_url)
print("Chromium CDP URL:", session.cdp_url)
```

> **Tip:** If your sandbox template does not contain `/opt/cubepod/desktop/cubepod-desktop-ctl`, `start_desktop` fails fast with HTTP `422 desktop_not_installed`.

## Next Steps

- Run existing `e2b` / `e2b-code-interpreter` code unchanged via **[E2B Drop-in Compatibility](/getting-started/e2b-compatibility/)**.
- Explore the internals in **[Platform Architecture](/concepts/architecture/)**.
- Deploy CubePod on Kubernetes with Kata Containers and CSI raw block storage in **[Kubernetes & Helm Deployment](/deployment/kubernetes-helm/)**.

---
# Platform Architecture
URL: https://cubepod.cubeplex.ai/concepts/architecture/

CubePod separates **agent orchestration**, **persistent storage**, **hardware compute isolation**, **in-guest execution**, and **outbound credential security** into focused, loosely coupled components. Every component maintains behavioral parity between **Production Kubernetes (`Kata + CSI Block`)** and **Local Development (`Docker + Loopback ext4`)**.

## End-to-End Topology

```mermaid
flowchart TB
    SDK["Agent / SDK Client (cubepod, e2b, MCP)"] -->|"REST, Connect-RPC, SSE, Panel HTTP/WS"| GW["cubepod-gateway (:8080, Stateless HA)"]
    GW -->|"CRD Watch / CRUD / Status"| K8S["Kubernetes API Server (cubepod.io/v1alpha1)"]
    GW -->|"Reconcile / Pause / Fork API"| CTRL["cubepod-controller (:8081)"]
    CTRL -->|"Provision / Claim / Snapshot"| K8S

    GW -->|"PodIP:49983 & Panel Ports"| PODD["podd Execution Daemon (:49983)"]

    subgraph POD["Sandbox Pod (Kata MicroVM or Docker Container)"]
        INIT["initContainer: podd-installer & egress-init"] -->|"Inject /opt/cubepod/bin + nftables"| PID1["PID 1: podd-init (Single-Threaded Rust)"]
        PID1 -->|"pivot_root + execvp"| PODD
        ROOTFS["OverlayFS RootFS (upperdir on rootfs-pvc)"] --- PID1
        WS["/workspace (workspace-pvc, 1000:1000)"] --- PID1
        PODD -->|"Guest Outbound Traffic"| NFT["nftables cubepod_egress"]
        NFT -->|"Redirect TCP 80/443 & DNS 53"| EGRESS["cubepod-egress Sidecar (:18080, :18053, :18081, :18443)"]
    end

    EGRESS -->|"mTLS POST /internal/v1/egress/exchange"| GW
    EGRESS -->|"Passthrough Splice or Real Auth Header"| EXT["External APIs (GitHub, OpenAI, Anthropic, Web)"]
```

## Control Plane & Operator Components

### 1. Stateless HA Control Plane Gateway (`cubepod-gateway`)

Implemented in `cmd/cubepod-gateway/` and `pkg/gateway/`, `cubepod-gateway` listens on `:8080` and terminates all client traffic:

- **E2B-Compatible & Superset API**: Serves sandbox lifecycle (`POST /sandboxes`, `/v2/sandboxes`), command/filesystem data plane, Connect-RPC (`/process.Process/*`, `/filesystem.Filesystem/*`), wildcard subdomain routing (`<port>-<sandboxID>.<domain>`), and optional template builds (`--e2b-template-api`).
- **Auto-Resume & Readiness Polling**: When a request arrives for a `Paused` sandbox, the gateway drives `desiredState: Running` and polls `podd` `/health` via `waitForPoddReady` before forwarding traffic.
- **Stateless Multi-Replica HA**: All authoritative sandbox metadata is persisted on Kubernetes `PodBox` annotations (`cubepod.io/template-id`, `cubepod.io/timeout-seconds`, `cubepod.io/volume-key`, `cubepod.io/metadata-*`, `cubepod.io/resolved-image`, `cubepod.io/forked-from`) and `status.podIP`. Any replica suffering an in-memory cache miss reconstructs state via `resolveSandbox` directly from the cluster.
- **Signed Panel Proxy & Secret Vault**: Mints and validates HMAC-SHA256 `/panel/{token}/` URLs for interactive desktops and dev previews, and serves `POST /internal/v1/egress/exchange` over mTLS for `cpodref_` placeholder swapping.

### 2. Kubernetes Operator (`cubepod-controller`)

Implemented in `cmd/cubepod-controller/` and `pkg/controller/`, `cubepod-controller` reconciles three custom resources defined in `deploy/helm/cubepod/crds/` under **`cubepod.io/v1alpha1`** (`api/v1alpha1/types.go` defines both `CRDGroup = "cubepod.io"` and `GroupName = "pod.cubeplex.ai"`):

- **`PodBox` (`pb`, `pbox`)**: Represents a single persistent sandbox with independent RootFS and `/workspace` PVCs, lifecycle timeouts, `forkFrom` lineage, and `networkPolicy`.
- **`PodTemplate` (`pt`, `ptemplate`)**: Defines base OCI image, `runtimeClassName` (`kata-qemu`, `kata-clh`, or empty for local dev), CPU/memory limits, storage class, and default egress posture.
- **`PodWarmPool` (`pwp`, `warmpool`)**: Maintains pre-booted, pre-attached standby MicroVMs claimed via atomic Kubernetes CAS label updates in `< 50 ms`.

The controller manages dual PVC provisioning, `rootfsGeneration` resets, CoW `ForkFrom` resolution across rootfs generations, idle/TTL reaping (`ReapIdle`), and per-pod ECDSA P-256 mTLS & MITM CA secrets (`ensureEgressSecretsLocked`).

## Data Plane & In-Guest Components

### 3. Clean Image Injection & In-Guest Rust Runtime (`podd-init` & `podd`)

CubePod never requires baking proprietary agents or init scripts into user Dockerfiles:

- `images/podd/Dockerfile` packages static Rust binaries into a minimal `busybox:1.37-musl` injector image.
- An `initContainer` (`podd-installer`) copies `/opt/cubepod/bin/{podd-init,podd}` into a shared `emptyDir` volume (or Docker bind-mounts the binary directory read-only).
- **`podd-init`** (`crates/podd-init/`) runs as a **single-threaded PID 1**: formats or heals `ext4` (`blkid` / `mkfs.ext4` / `e2fsck -p`), mounts the RootFS `OverlayFS` (`lowerdir=/`), attaches `/workspace` as UID/GID `1000:1000`, bind-mounts `/opt/cubepod` across the mount namespace, executes `pivot_root`, and `execvp`s into `podd`.
- **`podd`** (`crates/podd/`) listens on `:49983` for command execution (cursor-tailed stdout/stderr, PGID kill, Connect-RPC), file transfer & streaming `tar.gz` `archive-sync`, crash-consistent `FIFREEZE`/`FITHAW` quiescing, and 6 persistent code-interpreter kernels.

### 4. Zero-Trust Egress Sidecar (`cubepod-egress`)

Co-located inside the sandbox Pod as a dedicated UID `65532` sidecar container (`cmd/cubepod-egress/`, `pkg/egress/`), `cubepod-egress` enforces domain policies (`DenyHosts` > `AllowHosts` > `DefaultAction`), refuses unauthorized DNS (`RCODE=5` on `:18053`), receives `nftables`-redirected HTTP/TLS traffic (`:18081` / `:18443`), performs zero-copy splicing for normal sites, and selectively MITMs only secret-bound hosts to swap `cpodref_` placeholders over mTLS.

### 5. Lazy Interactive Desktop (`images/desktop/`)

Optional desktop images launch cleanly with `sleep infinity` (~0 MiB idle RAM) and expose `/opt/cubepod/desktop/cubepod-desktop-ctl` to bring up `Xvfb`, `openbox`, Chromium CDP (`127.0.0.1:9222`), `x11vnc`/`websockify`/`noVNC` (`:8080`), and `ttyd` (`:7681`) on demand.

## Dual-Runtime Architecture Parity

| Layer | Production Kubernetes (`Kata + CSI Block`) | Local Development (`Docker + Loopback`) |
| :--- | :--- | :--- |
| **Compute Isolation** | `Kata Containers` (`runtimeClassName: kata-qemu` / `kata-clh`) | Docker container (`CUBEPOD_RUNTIME_MODE=docker-loopback`) |
| **Storage Backing** | Two `volumeMode: Block` PVCs (`/dev/cubepod-rootfs`, `/dev/cubepod-workspace`) or `volumeMode: Filesystem` fallback | Sparse `.ext4` loopback files per sandbox (`cubepod-volumes`) |
| **In-Guest Mounts** | `podd-init` mounts `OverlayFS` (`lowerdir=/`) + `/workspace` inside VM kernel | Identical `podd-init` `e2fsck` + `OverlayFS` + `pivot_root` path |
| **CoW Fork Mechanism** | `podd` `FIFREEZE` -> CSI `DataSourcePVC` / snapshot clone -> `FITHAW` | `podd` `FIFREEZE` -> `cp --reflink=auto --sparse=always -a` -> `FITHAW` |
| **Runtime Binary Injection** | `podd-installer` `initContainer` -> `emptyDir` `/opt/cubepod/bin` | Read-only host bind-mount `-v <binDir>:/opt/cubepod/bin:ro` |

> **Note on Defaults:** Production Helm defaults (`deploy/helm/cubepod/values.yaml`) and `controller.NewReconciler()` target `volumeMode: Block`, `runtimeClassName: kata-qemu`, and `storageClassName: longhorn-v2-block-thin`. When running standalone `cmd/cubepod-controller` or `cmd/cubepod-gateway` binaries outside Helm, CLI flags default to `-volume-mode=Filesystem`, `-storage-class=nfs-storage`, and `-runtime-class=""` unless explicitly overridden.

## Next Steps

- Understand volume separation in **[Dual-Volume Persistence](/concepts/dual-volume-persistence/)**.
- Inspect the Rust PID 1 boot sequence in **[In-Guest Runtime (podd-init & podd)](/concepts/in-guest-init-and-podd/)**.
- Explore `< 50ms` scheduling and cloning in **[Lifecycle, WarmPool, CoW Fork & HA](/concepts/lifecycle-warmpool-fork/)**.

---
# Interactive Desktop & Signed Panel Proxy
URL: https://cubepod.cubeplex.ai/concepts/desktop-and-panel-proxy/

Computer-use and browser-automation agents frequently need a real X11 display, Chromium DevTools Protocol (CDP), human-in-the-loop VNC viewing, and a live browser shell — without forcing non-GUI sandboxes to pay idle RAM overhead or punch per-sandbox firewall holes in Kubernetes.

CubePod solves this with two tightly integrated mechanisms ([CEP-0004](/ceps/0004-gateway-and-panel-proxy/), [CEP-0021](/ceps/0021-interactive-desktop-and-panel-stack/)): a **lazy on-demand desktop stack (`images/desktop/`)** and a **stateless HMAC-SHA256 `/panel/{token}/` reverse proxy (`pkg/gateway/panel.go`)**.

## 1. Zero-Idle-Cost Lazy Desktop Stack

Containers built from CubePod's desktop image (`images/desktop/`) boot into `CMD ["sleep", "infinity"]` with **~0 MiB desktop daemon memory overhead**. Graphical daemons remain dormant until a client explicitly starts a desktop session.

All desktop processes are managed by `/opt/cubepod/desktop/cubepod-desktop-ctl` (`start`, `status`, `stop`), stored separately from `/opt/cubepod/bin` so runtime binaries remain decoupled:

| Daemon | Bind / Display | Role & Configuration |
| :--- | :--- | :--- |
| **`Xvfb`** | Display `:99` | Virtual X11 framebuffer defaulting to `1280x800x24` (customizable via validated `WxHx{16\|24\|32}` resolution). |
| **`openbox`** | Display `:99` | Lightweight X11 window manager for browser and desktop windows. |
| **`chromium-wrapper`** | `127.0.0.1:9222` | Headless/headed Chromium exposing Chrome DevTools Protocol (CDP), optionally navigating to `initialUrl`. Cleans stale `SingletonLock` / `SingletonSocket` / `SingletonCookie` files from persisted RootFS across sandbox pauses or restarts. |
| **`x11vnc`** | `127.0.0.1:5900` | Binds the `:99` X display locally over VNC. |
| **`websockify` + `noVNC`** | `0.0.0.0:8080` | Bridges VNC WebSockets into browser-viewable `vnc.html`. |
| **`ttyd`** | `:7681` | Streams an interactive web terminal (`/bin/bash`) starting in `/workspace`. |

### Reliability & Privilege Safety (`cubepod-desktop-ctl`)

- **Privilege Separation**: Although `podd` spawns control hooks cleanly, `cubepod-desktop-ctl` drops privileges to UID/GID `1000:1000` (`cubeplex`) so browser caches, downloads, and shell sessions run unprivileged and share `/workspace` ownership automatically.
- **Concurrency Locking**: Operations are serialized via `flock` so concurrent `start` / `stop` calls never spawn duplicate `Xvfb` or `x11vnc` instances.
- **RootFS-Safe Chromium Recovery**: Because CubePod persists RootFS across pod restarts, Chromium's previous PID profile locks (`Singleton*`) would normally prevent relaunching after a `Paused` -> `Running` transition. `cubepod-desktop-ctl` cleans stale lock files before starting `chromium-wrapper`.

> **Protocol Note:** The shipping `images/desktop/` stack serves **`noVNC` (`:8080`)**, **`ttyd` (`:7681`)**, and **Chromium CDP (`:9222`)**, while CubePod's panel reverse proxy and architecture blueprint also support proxying WebRTC/Neko streaming endpoints when supplied by custom images.

## 2. Gateway Desktop API (`pkg/gateway/desktop.go`)

`cubepod-gateway` exposes three lifecycle endpoints (also available under `/v1/sandboxes/{id}/desktop/...`):

- `POST /sandboxes/{id}/desktop/start` — validates resolution (`WxHx{16|24|32}`), auto-resumes the sandbox if `Paused`, verifies `/opt/cubepod/desktop/cubepod-desktop-ctl` exists (returning **`HTTP 422 desktop_not_installed`** on non-desktop images), starts the stack via `podd`, and returns ready URLs (`desktopUrl`, `terminalUrl`, `cdpUrl`).
- `GET /sandboxes/{id}/desktop/status` — returns live status of `Xvfb`, `openbox`, `chromium`, `x11vnc`/`noVNC`, and `ttyd`.
- `POST /sandboxes/{id}/desktop/stop` — gracefully tears down GUI daemons to reclaim RAM while preserving sandbox compute and files.

Example response URLs returned by `start`:

- `desktopUrl`: `/panel/<signed-token>/vnc.html?autoconnect=true&resize=scale`
- `terminalUrl`: interactive `ttyd` terminal endpoint (port `7681`)
- `cdpUrl`: Chrome DevTools Protocol (CDP) endpoint for headless/headed Chromium automation (port `9222`)

## 3. Stateless Signed Panel Proxy (`pkg/gateway/panel.go`)

Instead of provisioning per-sandbox Kubernetes `Ingress` objects or exposing container ports directly, `cubepod-gateway` issues short-lived, cryptographically signed panel URLs for **any** port inside a sandbox (desktop `8080`, `ttyd` `7681`, Jupyter, Vite/React dev servers, MCP UIs):

1. **Token Minting (`POST /sandboxes/{id}/endpoints/{port}`)**: Encodes payload `sandboxID:port:expUnix` (default TTL **`3600` seconds**), signs it with **HMAC-SHA256**, and outputs:
   ```text
   base64url(sandboxID:port:expUnix).base64url(hmacSha256)
   ```
2. **Stateless Verification Across Replicas**: Any `cubepod-gateway` replica receiving `GET /panel/{token}/{rest...}` (or a WebSocket upgrade handshake) verifies the HMAC signature and expiration timestamp without needing central session storage.
3. **Auto-Resume & Live Reverse Proxy**: Using `resolveSandbox`, the gateway wakes the sandbox if it is `Paused`, resolves its current `<status.podIP>:<port>`, and reverse-proxies HTTP assets and bidirectional WebSocket frames (`noVNC`, `ttyd`, HMR dev servers) directly to the MicroVM.

## Next Steps

- Try launching a desktop session in Python from the **[Quickstart](/getting-started/quickstart/#4-launch-an-interactive-desktop-optional)**.
- Inspect the full gateway endpoints in the **[API Reference](/api/)**.
- Read the design specifications in **[CEP-0004](/ceps/0004-gateway-and-panel-proxy/)** and **[CEP-0021](/ceps/0021-interactive-desktop-and-panel-stack/)**.

---
# Dual-Volume Persistence
URL: https://cubepod.cubeplex.ai/concepts/dual-volume-persistence/

A foundational invariant of CubePod is **Dual-Volume Independence**: the lifecycle of user project files in `/workspace` (`workspace-pvc`) is strictly decoupled from the container's persistent OS `OverlayFS` layer (`rootfs-pvc`).

## Why Two Independent Volumes?

If an agent sandbox keeps everything on one volume or leaves the OS RootFS ephemeral:

- **With an ephemeral RootFS**, any `apt-get install`, `npm install -g`, Python toolchain, Playwright browser binary, or `/etc` configuration disappears whenever compute scales to zero (`Paused`) or moves across Kubernetes nodes.
- **With a single merged volume**, resetting a corrupted OS installation or upgrading the underlying base OCI template image forces a destructive wipe of the agent's source code, checkpoints, and datasets.

CubePod avoids both failure modes by attaching **two independent persistent volumes** to every `PodBox`.

```mermaid
flowchart LR
    IMG["Base OCI Image (lowerdir=/, read-only)"] --> OVL["Linux OverlayFS (merged /)"]
    RPVC["rootfs-pvc / rootfs-genN-pvc (ext4, upper/ + work/)"] -->|"upperdir + workdir"| OVL
    OVL -->|"pivot_root"| GUEST["Guest Root Filesystem (/, /usr, /etc, /home, /var)"]
    WPVC["workspace-pvc (ext4, UID/GID 1000:1000)"] -->|"Independent Mount"| WDIR["/workspace (User Code, Datasets, Artifacts)"]
```

## Volume Layout Inside the Sandbox

| Volume | Default Size (`manifests.go`) | PVC Naming Convention | Mount Path in Guest | Ownership & Purpose |
| :--- | :--- | :--- | :--- | :--- |
| **RootFS Upper** | `10Gi` | `<box>-rootfs-pvc` (gen `1`) or `<box>-rootfs-gen<N>-pvc` (gen `> 1`) | Block device `/dev/cubepod-rootfs` -> mounted at `/mnt/cubepod-upper` -> `OverlayFS` `upperdir` + `workdir` | Persists every OS-level mutation (`/usr`, `/etc`, `/var`, installed packages, system libs) on top of the read-only OCI `lowerdir`. |
| **Workspace** | `20Gi` | `<box>-workspace-pvc` | Block device `/dev/cubepod-workspace` -> mounted directly at `/workspace` | Dedicated workspace storage initialized to `UID:GID 1000:1000` (`cubeplex`). Survives base image upgrades and `RootFS` resets untouched. |

In Kubernetes, both PVCs carry deterministic labels (`pod.cubeplex.ai/box: <boxName>` and `pod.cubeplex.ai/vol-type: rootfs | workspace`) so garbage collection, snapshot cloning, and multi-generation tracking remain unambiguous.

## Non-Destructive OS Reset (`rootfsGeneration`)

When an AI agent breaks system libraries, pollutes `/etc`, or needs a newer base OCI image, CubePod does not discard `/workspace`:

1. A client calls `POST /sandboxes/{id}/reset-rootfs` (or `client.reset_rootfs(id)` / `sandbox.resetRootfs()`), or updates `PodBox.spec.rootfsGeneration`.
2. `cubepod-controller` transitions the `PodBox` phase to `ResettingRootFS` (`Reconcile` compares `spec.rootfsGeneration` against `status.observedRootfsGeneration`).
3. The controller tears down the running Pod, allocates a **fresh RootFS PVC** named `<box>-rootfs-gen<N>-pvc`, and leaves the original `<box>-workspace-pvc` (`status.workspacePVCName`) completely intact.
4. A new Pod boots against the new `upperdir` while re-attaching the exact same `/workspace` volume, updating `status.observedRootfsGeneration` and `status.rootfsPVCName`.

> **Important for CoW Fork:** When a forked sandbox (`spec.forkFrom`) is later created from a parent that has reset its RootFS one or more times, the controller's `resolveParentPVCNames` reads `status.RootfsPVCName` (e.g., `<parent>-rootfs-gen3-pvc`) instead of assuming `-rootfs-pvc`, ensuring forks always clone the parent's active RootFS generation.

## Three Storage Backends Across Production and Local Dev

CubePod executes the same dual-volume abstraction across three storage modes implemented in `pkg/controller/manifests.go` and `pkg/runtime/docker.go`:

### 1. CSI Raw Block (`volumeMode: Block` + Kata MicroVM)

In production (`kata-qemu` / `kata-clh` with Longhorn V2 SPDK, OpenEBS LVM-LocalPV, Ceph RBD, or cloud EBS):

- `BuildBlockPVCs` requests two `volumeMode: Block` PVCs and injects them into the Pod's `volumeDevices` at `/dev/cubepod-rootfs` and `/dev/cubepod-workspace`.
- Inside the Kata guest VM kernel, `podd-init` checks `blkid`, formats fresh volumes with `mkfs.ext4 -F -L ... -m 0 -E lazy_itable_init=0,lazy_journal_init=0`, or heals existing volumes with `e2fsck -p`, then mounts `ext4` (`-o noatime`) and builds the `OverlayFS` inside the MicroVM's own Linux kernel.
- **Why Raw Block Inside Kata Matters**: Mounting `OverlayFS` directly on a containerd overlayfs root inside a standard host container fails in Linux kernels that forbid nested `OverlayFS`-on-`OverlayFS` (`overlay` `lowerdir` cannot be another `overlay`). Inside a Kata MicroVM (`virtio-blk` + guest kernel), `podd-init` runs cleanly without polluting host `containerd` image layers.

### 2. CSI Filesystem Fallback (`volumeMode: Filesystem`)

When deploying into standard Kubernetes clusters without raw block CSI support (`runtimeClassName: ""`, `-volume-mode=Filesystem`):

- `BuildBlockPVCs` provisions normal `volumeMode: Filesystem` PVCs mounted into `/mnt/cubepod/rootfs` and `/workspace`.
- `podd-init` detects the absence of raw block devices (or `CUBEPOD_SKIP_PIVOT=1`), records `pivoted: false` in `/run/cubepod/init-state.json`, and hands off cleanly to `podd` so `/workspace` still persists across Pod restarts.

### 3. Local Docker Loopback (`CUBEPOD_RUNTIME_MODE=docker-loopback`)

For laptop development without Kubernetes:

- `pkg/runtime/docker.go` creates sparse `.ext4` loopback files per sandbox inside the volumes directory and attaches them alongside `--entrypoint /opt/cubepod/bin/podd-init`.
- `podd-init` runs the exact same `blkid` / `e2fsck -p` / `OverlayFS` / `pivot_root` sequence used inside Kata MicroVMs, giving developers high fidelity locally.

## Next Steps

- Follow the exact PID 1 boot steps inside the guest in **[In-Guest Runtime (podd-init & podd)](/concepts/in-guest-init-and-podd/)**.
- Learn how `PodWarmPool` and `ForkFrom` snapshot dual volumes in **[Lifecycle, WarmPool, CoW Fork & HA](/concepts/lifecycle-warmpool-fork/)**.
- Configure CSI storage classes in **[Kata & Block Storage](/deployment/kata-and-block-storage/)**.

---
# In-Guest Runtime (podd-init & podd)
URL: https://cubepod.cubeplex.ai/concepts/in-guest-init-and-podd/

To support arbitrary user Docker images without rebuilding base images or polluting the user's writable RootFS layer, CubePod splits its in-guest runtime into a dedicated injector image (`images/podd/Dockerfile`) and two statically linked Rust binaries: **`podd-init`** (`crates/podd-init/`) and **`podd`** (`crates/podd/`).

## Zero-Contamination Binary Injection

**User sandbox images must never contain `podd-init` or `podd`.** Stock images such as `ubuntu:24.04`, `python:3.12`, or custom desktop/ML images remain completely untouched:

1. `images/podd/Dockerfile` packages compiled `podd-init` and `podd` into a `busybox:1.37-musl` image under `/opt/cubepod/dist/`.
2. **In Kubernetes**: an `initContainer` named `podd-installer` copies `/opt/cubepod/dist/{podd-init,podd}` into a shared Pod `emptyDir` mounted at `/opt/cubepod/bin`.
3. **In Local Docker Loopback**: `pkg/runtime/docker.go` bind-mounts the host binary directory read-only (`-v <binDir>:/opt/cubepod/bin:ro`) and sets `--entrypoint /opt/cubepod/bin/podd-init`.
4. **Across `pivot_root`**: `podd-init` recursively bind-mounts `/opt/cubepod` from the initial root into the newly pivoted merged root before detaching `.old_root`.

Because `/opt/cubepod` lives purely in the ephemeral `emptyDir` / read-only mount rather than the persistent `upperdir`, upgrading CubePod's runtime binaries on Pod resume never leaves stale runtime artifacts inside the user's persistent RootFS volume.

## Why `podd-init` Is Single-Threaded Rust

`podd-init` (`crates/podd-init/src/main.rs`) runs as **PID 1** inside the container/MicroVM prior to `pivot_root(2)` and `execvp(3)`:

- Linux `pivot_root(2)` and mount-namespace manipulations fail (`EINVAL`) or leak stale filesystem references if multiple OS threads exist inside the calling process.
- Go binaries spawn OS runtime scheduler/sysmon threads before entering `main()`, making pure-Go PID 1 `pivot_root` unsafe.
- Writing `podd-init` as a tiny, single-threaded, zero-GC Rust binary guarantees deterministic mount setup, filesystem healing, root pivoting, and clean `execvp` handoff into `podd`.

## PID 1 Boot Sequence (`crates/podd-init/src/main.rs`)

At container start, `podd-init` reads environment configuration (`CUBEPOD_ROOTFS_DEV` default `/dev/cubepod-rootfs`, `CUBEPOD_WORKSPACE_DEV` default `/dev/cubepod-workspace`, `CUBEPOD_UPPER_MOUNT` default `/mnt/cubepod-upper`, `CUBEPOD_MERGED_ROOT` default `/mnt/cubepod-merged`, `CUBEPOD_UID`/`CUBEPOD_GID` default `1000`, `CUBEPOD_INIT_STATE_PATH` default `/run/cubepod/init-state.json`, and `CUBEPOD_SKIP_PIVOT`) and executes:

1. **Private Mount Propagation**: Calls `make_mount_private("/")` (`MS_PRIVATE | MS_REC`) so mounts inside the guest never propagate back out.
2. **Fallback Check (`volumeMode: Filesystem`)**: If `CUBEPOD_SKIP_PIVOT=1` or the configured block devices do not exist, `podd-init` skips formatting and pivoting, writes `pivoted: false` to `/run/cubepod/init-state.json`, ensures `/workspace` ownership (`1000:1000`), and launches `podd` immediately.
3. **Self-Healing `ext4` Preparation (`ensure_ext4`)**:
   - Probes `/dev/cubepod-rootfs` and `/dev/cubepod-workspace` with `blkid`.
   - **First boot (blank block device)**: Formats with `mkfs.ext4 -F -L <label> -m 0 -E lazy_itable_init=0,lazy_journal_init=0` so metadata is synchronously initialized without post-boot background stall.
   - **Subsequent boots or forked volumes**: Runs non-interactive `e2fsck -p`, retrying up to **10 times with 500 ms backoff** if the kernel returns exit code `8` (`EBUSY` right after device attach).
4. **RootFS `OverlayFS` Mount**: Mounts the RootFS `ext4` partition at `/mnt/cubepod-upper` (`-o noatime`), ensures `upper/` and `work/` directories exist, and mounts Linux `overlay` (`lowerdir=/,upperdir=/mnt/cubepod-upper/upper,workdir=/mnt/cubepod-upper/work`) onto `/mnt/cubepod-merged`.
5. **Workspace Mount & Unprivileged Ownership**: Mounts `/dev/cubepod-workspace` inside `<merged>/workspace` and applies `chown 1000:1000` (`cubeplex`) so agent commands can read/write immediately without follow-up `chown` hacks.
6. **Virtual FS & Config Carry-Over**: Recursively bind-mounts (`--rbind`) `/proc`, `/sys`, `/dev`, `/run`, and `/opt/cubepod`, and bind-mounts (`/etc/resolv.conf`, `/etc/hosts`, `/etc/hostname`) into `<merged>`.
7. **Atomic `pivot_root` & Old Root Detach**: Transitions the root filesystem via `pivot_root` into `.old_root` (with `chroot` fallback if `pivot_root` is restricted), then calls `umount2(MNT_DETACH)` on `/.old_root`.
8. **State Record & Handoff**: Writes `/run/cubepod/init-state.json` (`pivoted: true`, device/mount diagnostics) and `execvp`s into `/opt/cubepod/bin/podd`, replacing itself while retaining PID 1.

## The `podd` Execution & Control Daemon (`:49983`)

Once `podd` (`crates/podd/src/main.rs`) takes over PID 1:

- **Subreaper & Zombie Collection**: Installs a zombie reaper (`install_zombie_reaper`) so orphaned agent subprocesses are cleanly reaped.
- **Bootstrap Command & Privilege Separation**: Optionally launches `CUBEPOD_START_CMD` in the background (for template services) while running agent commands and file writes as unprivileged UID/GID `1000:1000` (`CUBEPOD_RUN_AS_USER`, `CUBEPOD_RUN_AS_GROUP`, `CUBEPOD_RUN_AS_USERNAME`).

`podd` exposes an HTTP/1.1 + Connect-RPC listener on **`:49983`** consumed exclusively by `cubepod-gateway` and `cubepod-controller`:

### Lifecycle & Crash-Consistent Quiescing (`crates/podd/src/lifecycle.rs`)

| Endpoint | Kernel Syscalls & Safety Mechanisms | Purpose |
| :--- | :--- | :--- |
| `GET /health` | Process readiness check | Polled by `cubepod-gateway` (`waitForPoddReady`) after cold start or resume. |
| `POST /v1/lifecycle/prepare-stop` | `libc::sync()` | Flushes dirty page cache prior to clean shutdown or pause. |
| `POST /v1/lifecycle/quiesce` | `sync` + `syncfs` + `FIFREEZE` (`0xC0045877`) | Freezes guest filesystems cleanly before CSI snapshot / `reflink` fork. Accepts `maxFreezeMs` (default `1500` ms, clamped to `[100, 5000]` ms) backed by a monotonic watchdog timer that auto-thaws even if the controller crashes mid-fork. |
| `POST /v1/lifecycle/thaw` | `FITHAW` (`0xC0045878`) | Immediately unfreezes guest filesystems once the snapshot/clone finishes. |

### Command Execution & Process Control (`crates/podd/src/commands.rs`)

- **REST Execution**: `POST /v1/commands/run` (foreground or background), `GET /v1/commands/{id}/status`, `GET /v1/commands/{id}/logs?cursor=N` (byte-offset cursor streaming without re-sending earlier output), and `POST /v1/commands/{id}/kill` (terminates the full POSIX process group via negative `PGID`, eliminating zombie children).
- **Connect-RPC Compatibility**: Serves `/process.Process/Start` and `/process.Process/SendSignal` for E2B SDK interoperability.

### Files & High-Throughput `archive-sync` (`crates/podd/src/files.rs`)

- **Single-File REST**: `PUT /v1/files`, `GET /v1/files`, `DELETE /v1/files`, `GET /v1/files/list` with UID/GID metadata handling.
- **Streaming `POST /v1/files/archive-sync`**: Accepts raw `.tar` or `.tar.gz` archives and extracts directly inside the guest using verified path-traversal guards (rejects `..` components and leading `/`), applying `dest`, `uid`/`gid` (`1000:1000`), and optional `remove_paths` deletion — syncing thousands of project files in a single round-trip.

### Multi-Language Stateful Code Interpreter (`crates/podd/src/interpreter.rs`)

Serves `/execute`, `/v1/code/execute`, and `/contexts` with **6 persistent execution kernels**:

- `python`
- `bash`
- `javascript`
- `typescript`
- `r`
- `java`

Outputs stream back as NDJSON events (`stdout`, `stderr`, `result`, `error`) preserving variables and working state across repeated executions inside the same context.

## Next Steps

- See how `podd`'s `FIFREEZE`/`FITHAW` hooks power 1-second forks in **[Lifecycle, WarmPool, CoW Fork & HA](/concepts/lifecycle-warmpool-fork/)**.
- Inspect the [`crates/podd-init/`](https://github.com/cubeplexai/cubepod/tree/main/crates/podd-init) and [`crates/podd/`](https://github.com/cubeplexai/cubepod/tree/main/crates/podd) source trees or read **[CEP-0001](/ceps/0001-in-guest-overlayfs-pivot/)** and **[CEP-0002](/ceps/0002-podd-execution-daemon/)**.

---
# Lifecycle, WarmPool, CoW Fork & HA
URL: https://cubepod.cubeplex.ai/concepts/lifecycle-warmpool-fork/

CubePod combines Kubernetes-native reconciliation (`pkg/controller/reconciler.go`) with stateless gateway routing (`pkg/gateway/sandboxes.go`) to give persistent MicroVMs `< 50 ms` startup, `0 CPU / 0 RAM` idle pause, crash-consistent cloning, and multi-replica gateway High Availability ([CEP-0022](/ceps/0022-cow-fork-and-stateless-ha-gateway/)).

## `PodBox` State Machine

A `PodBox` (`cubepod.io/v1alpha1`) separates **desired compute state** (`spec.desiredState`: `Running` or `Paused`) from **observed controller phase** (`status.phase`), while preserving both persistent volumes (`status.rootfsPVCName` and `status.workspacePVCName`) across compute pauses and OS resets.

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Provisioning: Allocate dual PVCs or Claim WarmPool
    Provisioning --> Running: Pod ready and podd :49983 healthy

    Running --> Pausing: Pause API or idleTimeoutSeconds expired
    Pausing --> Paused: Delete Kata Pod (keep dual PVCs, 0 CPU/RAM)

    Paused --> Resuming: Connect or incoming traffic triggers auto-resume
    Resuming --> Running: Re-attach existing dual PVCs to new Pod

    Running --> ResettingRootFS: spec.rootfsGeneration incremented
    Paused --> ResettingRootFS: spec.rootfsGeneration incremented
    ResettingRootFS --> Running: Allocate rootfs-genN-pvc, keep workspace-pvc

    Running --> Terminated: Delete sandbox
    Paused --> Terminated: pausedTTLSeconds expired or Delete
    Provisioning --> Failed: Storage or runtime provisioning error
    Terminated --> [*]
```

### Idle Auto-Pause, Leases & Auto-Resume

- **Idle Reaping (`ReapIdle`)**: `cubepod-controller` monitors `status.lastActivityAt` against `spec.lifecycle.idleTimeoutSeconds`. If an agent holds an active lease (`spec.lifecycle.leaseExpiresAt` in the future), idle auto-pause is suppressed until the lease expires.
- **Compute Pause-to-Zero**: Transitioning `desiredState` to `Paused` deletes the Kubernetes Pod (`status.podName` and `status.podIP` clear) while keeping `<box>-rootfs-pvc` and `<box>-workspace-pvc` bound and untouched.
- **Paused TTL Reclamation**: Once `status.pausedAt` exceeds `spec.lifecycle.pausedTTLSeconds`, expired PVCs are reclaimed cleanly.
- **Transparent Auto-Resume**: Any request hitting `cubepod-gateway` for a `Paused` sandbox — explicit `POST /sandboxes/{id}/connect`, data-plane `/commands` or `/files`, wildcard subdomain routing, desktop start, or `/panel/{token}/` proxy — automatically patches `desiredState: Running` and polls `podd` `/health` via `waitForPoddReady` before serving the request.

## Sub-50ms Startup via `PodWarmPool`

Waiting seconds for PVC creation, CSI attachment, Kata VM boot, and `e2fsck` breaks interactive agent responsiveness. `PodWarmPool` shifts provisioning latency off the critical path:

1. **Pre-Warming**: For each pool, `cubepod-controller` maintains `spec.replicas` standby Kata Pods named `<pool>-warm-<N>-kata-pod`, each with pre-provisioned & pre-mounted dual PVCs (`podd-init` has already mounted `OverlayFS`, initialized `/workspace`, and started `podd` on `:49983`).
2. **Atomic CAS Claim (`ClaimPod`)**: When `handleCreateSandbox` receives `warmPoolRef` (or auto-discovers an available pool via `FindAvailableWarmPool`), `ClaimPod` performs a **Kubernetes Compare-And-Swap (CAS) label/metadata update** (`cubepod.io/claimed=true`, `cubepod.io/claimed-by=<boxName>`). Concurrent gateway requests cannot double-claim the same warm pod.
3. **Instant Ownership Transfer & Replenishment**: The claimed pod and its attached PVCs immediately bind to the new `PodBox` (delivering ready sandboxes in `< 50 ms`), while the controller asynchronously replenishes a replacement standby pod back up to `spec.replicas`.

## Crash-Consistent Multi-Generation CoW Fork (`spec.forkFrom`)

Forking an active sandbox lets AI agents branch filesystem and environment state speculatively (for example, trying competing fixes in parallel) without interrupting the parent session.

```mermaid
sequenceDiagram
    participant Client as Agent / SDK Client
    participant GW as cubepod-gateway
    participant CTRL as cubepod-controller
    participant ParentPodd as Parent podd (:49983)
    participant Storage as CSI Block / Loopback Storage
    participant ChildPod as Child Pod (podd-init + podd)

    Client->>GW: POST /sandboxes/{parentId}/fork
    GW->>CTRL: Reconcile child PodBox (spec.forkFrom)
    CTRL->>ParentPodd: POST /v1/lifecycle/quiesce (maxFreezeMs=1500)
    ParentPodd->>ParentPodd: sync + syncfs + ioctl FIFREEZE (with auto-thaw watchdog)
    CTRL->>Storage: Resolve active generation PVCs & CoW clone (CSI DataSourcePVC or reflink cp)
    Storage-->>CTRL: Child dual volumes ready
    CTRL->>ParentPodd: POST /v1/lifecycle/thaw (ioctl FITHAW)
    CTRL->>ChildPod: Boot Pod with CUBEPOD_FORKED=1
    ChildPod->>ChildPod: podd-init runs e2fsck -p & mounts OverlayFS + /workspace
    CTRL-->>GW: Child PodBox Running + podIP
    GW-->>Client: Return child SandboxInfo
```

### Key CoW Fork Invariants

- **Bounded Freeze Safety**: `ParentPodd` flushes kernel dirty pages (`sync` + `syncfs`) and calls `FIFREEZE` (`0xC0045877`) backed by a monotonic watchdog timer (`maxFreezeMs` clamped to `[100, 5000]`, default `1500` ms). Even if `cubepod-controller` restarts mid-fork, the parent MicroVM automatically unfreezes rather than deadlocking.
- **Dual-Backend Cloning**:
  - **Kubernetes CSI Mode**: `cubepod-controller` creates child PVCs with `dataSource` (`DataSourcePVC` / snapshot clone) targeting the parent's RootFS and Workspace PVCs.
  - **Local Docker Loopback Mode**: `pkg/runtime/docker.go` calls `quiesceSandbox`, clones both `.ext4` loopback files via `cp --reflink=auto --sparse=always -a`, calls `thaw`, and boots the child with `CUBEPOD_FORKED=1`.
- **Multi-Generation PVC Resolution (`resolveParentPVCNames`)**: If the parent sandbox previously ran `reset-rootfs` (`rootfsGeneration > 1`), its live RootFS PVC is `<parent>-rootfs-gen<N>-pvc` rather than `<parent>-rootfs-pvc`. `resolveParentPVCNames` inspects the parent's `status.RootfsPVCName` and `status.WorkspacePVCName` so forks always capture the parent's true active generation.

## Stateless Multi-Replica Gateway HA

In production, `cubepod-gateway` scales horizontally behind a Kubernetes Service or LoadBalancer without sticky sessions or shared Redis state:

- **Kubernetes CRD as Single Source of Truth**: Every gateway mutation writes canonical state into `PodBox` annotations (`cubepod.io/template-id`, `cubepod.io/timeout-seconds`, `cubepod.io/volume-key`, `cubepod.io/metadata-*`, `cubepod.io/resolved-image`, `cubepod.io/forked-from`) alongside `spec.networkPolicy` and `status.podIP`.
- **Cache-Miss Reconstruction (`resolveSandbox`)**: When any replica receives a request for a `sandboxID` missing from its local in-memory cache (for instance after a pod rollout or round-robin load balancing), `resolveSandbox` fetches the `PodBox` resource from Kubernetes, reconstructs the full `SandboxRecord`, transparently resumes it if `Paused`, and proxies directly to `http://<status.podIP>:49983`.

## Next Steps

- Inspect all `PodBox`, `PodTemplate`, and `PodWarmPool` fields in the **[CRD Reference](/reference/crds/)**.
- Understand how credentials and outbound traffic stay isolated across forks and resumes in **[Zero-Trust Egress & Secret Vault](/concepts/zero-trust-egress/)**.
- Read the architectural design spec in **[CEP-0022](/ceps/0022-cow-fork-and-stateless-ha-gateway/)**.

---
# Zero-Trust Egress & Secret Vault
URL: https://cubepod.cubeplex.ai/concepts/zero-trust-egress/

AI agents routinely call external APIs (OpenAI, Anthropic, GitHub, Slack, internal SaaS gateways) using privileged credentials. Giving an agent real API keys inside environment variables exposes those keys to prompt injection, untrusted code execution, `env` dumps, and `/proc/self/environ` reads.

CubePod enforces a strict **Zero-Trust Egress Secret Safety** invariant ([CEP-0005](/ceps/0005-zero-trust-egress-and-sdk/), [CEP-0020](/ceps/0020-transparent-zero-trust-egress/)):

> **Real external credentials must never enter the sandbox environment, filesystem, or guest process memory.** Inside the MicroVM, agents receive only opaque `cpodref_` placeholders swapped at the Pod egress boundary over per-sandbox mTLS.

## Architecture Overview

```mermaid
flowchart LR
    GUEST["Guest Process (cpodref_xxx in env)"] -->|"Outbound HTTP/HTTPS/DNS"| NFT["nftables cubepod_egress (excludes UID 65532 & lo)"]
    NFT -->|"TCP 80 -> :18081, TCP 443 -> :18443, DNS 53 -> :18053"| EGRESS["cubepod-egress Sidecar (UID 65532)"]

    EGRESS -->|"Policy Denied"| BLOCK["DNS RCODE=5 Refused / HTTP 403"]
    EGRESS -->|"Allowed, No Secret Binding"| SPLICE["Zero-Copy TCP Passthrough (spliceUpstream)"]
    EGRESS -->|"Allowed + SecretBindings Match"| MITM["Selective TLS MITM (verify Host == SNI)"]

    MITM <-->|"Per-pod mTLS POST /internal/v1/egress/exchange"| VAULT["cubepod-gateway Secret Vault"]
    MITM -->|"Inject Real Secret on the Wire"| EXT["Bound Upstream API (api.github.com, api.openai.com)"]
```

## 1. `cpodref_` Placeholders & Secret Binding

When creating a sandbox with `secretBindings`, you bind an environment variable (e.g., `GITHUB_TOKEN`) to a real secret, `allowedHosts` (e.g., `["api.github.com"]`), and optional `allowedHeaders` (e.g., `["Authorization"]`):

- `Vault.BindSecret` (`pkg/egress/vault.go`) stores the raw credential inside the control-plane vault and returns a deterministic opaque placeholder formatted as **`cpodref_` followed by 32 lowercase Base32 characters**.
- Only `GITHUB_TOKEN=cpodref_<32chars>` is injected into the sandbox environment. If untrusted code prints `os.environ` or attempts to send the placeholder to an attacker-controlled server (`evil.example.com`), `evil.example.com` receives only the useless `cpodref_` string — never the real credential.

## 2. Per-Pod Cryptographic Identity (`mTLS` + `MITM CA`)

In `pkg/controller/reconciler.go` (`ensureEgressSecretsLocked`), `cubepod-controller` provisions two distinct Kubernetes `Secret` objects for each sandbox using **ECDSA P-256** cryptography:

| Kubernetes Secret | Contents | Mounted Where | Purpose |
| :--- | :--- | :--- | :--- |
| **`<box>-egress-mtls`** | Per-pod client leaf cert/key (`CN = <sandboxID>`), CA cert, plus per-pod MITM CA private key & cert | **Only** inside the `cubepod-egress` sidecar at `/etc/cubepod/certs` | Authenticates the sidecar to `cubepod-gateway` over mTLS and signs short-lived leaf certificates during selective MITM. |
| **`<box>-egress-ca`** | **Public `mitm-ca.crt` only** (zero private keys) | Sandbox user container at `/etc/cubepod/ca` | Exported via `NODE_EXTRA_CA_CERTS` and `CUBEPOD_EXTRA_CA_CERT` (plus proxy envs `HTTP_PROXY`/`HTTPS_PROXY=http://127.0.0.1:18080`) so guest TLS clients trust the sidecar's selective MITM certs without touching private key material. |

## 3. Dual Interception: Explicit Proxy & Transparent `nftables`

`cubepod-egress` (`cmd/cubepod-egress/`, `pkg/egress/`) supports both explicit HTTP proxy clients and proxy-unaware binaries (such as static Go/Rust tools, `curl --noproxy`, or raw sockets):

- **Explicit Proxy Listener (`:18080`)**: Serves HTTP proxy and `HTTPS CONNECT` tunnels via `HTTP_PROXY` / `HTTPS_PROXY`.
- **Transparent Interception (`CUBEPOD_TRANSPARENT=1`)**: An init hook (`images/egress/egress-init.sh`) installs the `nftables` table `cubepod_egress` in the Pod network namespace before guest workload start:
  - Redirects outbound **TCP port `80`** -> **`:18081`** (`cubepod-egress` transparent HTTP)
  - Redirects outbound **TCP port `443`** -> **`:18443`** (`cubepod-egress` transparent TLS SNI router)
  - Redirects outbound **UDP/TCP port `53`** -> **`:18053`** (`cubepod-egress` policy-enforcing DNS proxy)
  - Drops/rejects outbound **UDP port `443`** to prevent HTTP/3 QUIC bypasses, transparently falling back to TLS over TCP
  - Excludes loopback traffic and **`skuid 65532`** (the `cubepod-egress` sidecar user ID) so the sidecar's own upstream connections exit normally without redirect loops

## 4. Policy Evaluation & DNS Tunneling Defense

Every destination host is evaluated against `spec.networkPolicy` (`pkg/egress/policy.go`) using deterministic precedence:

1. **`DenyHosts`** is evaluated first and always wins.
2. **`AllowHosts`** is checked next.
3. **`DefaultAction`** (`Allow` or `Deny`) acts as fallback.

Wildcard rules follow strict **dot-boundary matching**: `*.github.com` matches `api.github.com` and `uploads.github.com`, while rejecting lookalikes such as `evilgithub.com`.

On port **`:18053`**, `cubepod-egress` inspects DNS queries in flight (`pkg/egress/dns.go`) and immediately replies with **`RCODE=5` (`Refused`)** for policy-denied domains — blocking DNS exfiltration even when TCP/HTTP is never opened.

## 5. Selective HTTPS MITM vs. Zero-Copy Passthrough

For allowed TLS connections (`CONNECT :18080` or transparent `:18443`), `pkg/egress/sni.go` peeks the raw TLS `ClientHello` **SNI** via `prefixConn` before deciding how to handle the stream (`pkg/egress/proxy.go`):

- **Non-Secret Destinations -> Zero-Copy Passthrough (`spliceUpstream`)**: If the SNI host does not match any `SecretBindings[].AllowedHosts`, `cubepod-egress` **never decrypts TLS**. It replays the peeked bytes into a zero-copy TCP splice (optionally chaining through `spec.networkPolicy.upstreamProxy`), preserving native end-to-end TLS certificates and WebSocket/HTTP2 fidelity.
- **Secret-Bound Destinations -> Selective MITM (`serveMITMTLS`)**: Only hosts listed in `SecretBindings[].AllowedHosts` undergo TLS termination using the per-pod MITM CA:
  1. Enforces **`HTTP Host == TLS SNI`**, immediately returning **`HTTP 421 Misdirected Request`** if a compromised client attempts domain fronting across a mismatched Host header.
  2. Scans headers (respecting `AllowedHeaders` restrictions when set) for `cpodref_` tokens.
  3. Calls `cubepod-gateway` (`POST /internal/v1/egress/exchange`) over **per-sandbox mTLS**, where the gateway verifies that the sidecar's client certificate **`CN` matches `sandboxID`**, along with `sniHost` and `headerName`.
  4. Replaces `cpodref_...` with the real secret solely in transit buffers and forwards upstream; real credentials are never logged or sent back to the guest.

Prometheus metrics and liveness probes are exposed by `cubepod-egress` on **`:19090`** (`/metrics` and `/healthz`).

## Next Steps

- Review `networkPolicy` and `secretBindings` schemas in **[CRD Reference](/reference/crds/)**.
- Inspect the underlying architecture specs in **[CEP-0005](/ceps/0005-zero-trust-egress-and-sdk/)** and **[CEP-0020](/ceps/0020-transparent-zero-trust-egress/)**.

---
# Go SDK & CLI
URL: https://cubepod.cubeplex.ai/sdks/go-and-cli/

CubePod provides an idiomatic, zero-external-dependency Go client library (`github.com/cubeplexai/cubepod/pkg/client`) alongside the `cubepod` CLI binary (`cmd/cubepod`).

## Part 1: Go Client SDK (`pkg/client`)

### Installation

```bash
go get github.com/cubeplexai/cubepod/pkg/client
```

### Initializing the Client

`client.New(baseURL, opts...)` defaults to `http://127.0.0.1:8080` and a `60s` HTTP timeout:

```go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/cubeplexai/cubepod/pkg/client"
)

func main() {
	ctx := context.Background()
	c := client.New(
		"http://localhost:8080",
		client.WithAPIKey("your-api-key"),
		client.WithTimeout(60*time.Second),
	)

	// Provision a persistent sandbox
	sb, err := c.CreateSandbox(ctx, client.CreateSandboxRequest{
		TemplateID: "cubeplex-ubuntu24-desktop",
		VolumeKey:  "agent-ws-01",
		Metadata:   map[string]string{"owner": "team-ai"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer c.DeleteSandbox(ctx, sb.SandboxID)

	res, err := c.RunCommand(ctx, sb.SandboxID, client.RunCommandRequest{
		Command: "uname -a",
		Workdir: "/workspace",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.Output)
}
```

Available constructor options:
- `client.WithAPIKey(apiKey string)`: Attaches `Authorization: Bearer <apiKey>`.
- `client.WithTimeout(timeout time.Duration)`: Overrides the default `60s` `http.Client.Timeout`.
- `client.WithHTTPClient(httpClient *http.Client)`: Supplies a custom `*http.Client`.

### Sandbox Lifecycle, Reset & CoW Fork

```go
// Inspect and list
sb, err := c.GetSandbox(ctx, sandboxID)
list, err := c.ListSandboxes(ctx, "cubeplex-ubuntu24-desktop") // "" for all

// Timeout & exclusive lease protection
err = c.SetTimeout(ctx, sandboxID, 3600)
err = c.AcquireLease(ctx, sandboxID, 300)

// Pause (deletes Pod, retains dual PVCs) & Auto-Resume Connect
sb, err = c.PauseSandbox(ctx, sandboxID)
sb, err = c.ConnectSandbox(ctx, sandboxID)

// Reset RootFS Upper while keeping /workspace intact
sb, err = c.ResetRootFS(ctx, sandboxID)

// 1-second Copy-on-Write clone of both RootFS and Workspace
child, err := c.ForkSandbox(ctx, sandboxID)

// Delete (with option to permanently delete PVCs)
err = c.DeleteSandbox(ctx, sandboxID)
err = c.DeleteSandboxWithOptions(ctx, child.SandboxID, true)
```

### Commands & UID/GID Handling

Because Go's `0` is the zero value for `int` (`omitempty`), `RunCommandRequest` provides `RunAsRoot`, `UIDPtr`, and `GIDPtr` so you can distinguish between *"let the server/template default decide"* and *"explicitly run as root (`uid=0, gid=0`)"*:

```go
// Background command
bg, err := c.RunCommand(ctx, sandboxID, client.RunCommandRequest{
	Command:    "python3 -u server.py",
	Background: true,
	Workdir:    "/workspace",
	Envs:       map[string]string{"PORT": "8080"},
})

// Explicit root execution
rootRes, err := c.RunCommand(ctx, sandboxID, client.RunCommandRequest{
	Command:   "apt-get update",
	RunAsRoot: true,
})

// Poll status, incremental cursor logs, or kill process group
status, err := c.GetCommandStatus(ctx, sandboxID, bg.ID)
logs, err := c.GetCommandLogs(ctx, sandboxID, bg.ID, 0) // pass logs.Cursor next
err = c.KillCommand(ctx, sandboxID, bg.ID)
```

### Files & Recursive `ArchiveSyncDir`

```go
// Write / read / list / delete files
err := c.WriteFile(ctx, sandboxID, "/workspace/hello.txt", []byte("hi\n"), "0644")

// Custom UID/GID ownership
uid, gid := 1000, 1000
err = c.WriteFileWithOwner(ctx, sandboxID, "/workspace/bin/run", data, "0755", &uid, &gid)

raw, err := c.ReadFile(ctx, sandboxID, "/workspace/hello.txt")
entries, err := c.ListFiles(ctx, sandboxID, "/workspace")
err = c.DeleteFile(ctx, sandboxID, "/workspace/hello.txt")

// In-memory tar.gz sync
err = c.ArchiveSync(ctx, sandboxID, "/workspace", map[string][]byte{
	"app/main.go": []byte("package main\n"),
})

// Walk a local directory and upload all files in a single tar.gz request
err = c.ArchiveSyncDir(ctx, sandboxID, "/workspace/skills", "./local-skills")
```

### Endpoints, WarmPools & Templates

```go
// Signed HMAC-SHA256 panel URL
ep, err := c.GetPanelEndpoint(ctx, sandboxID, 8080, 3600)

// WarmPools
wp, err := c.CreateWarmPool(ctx, "fast-pool", "cubeplex-ubuntu24-desktop", 3)
pools, err := c.ListWarmPools(ctx)

// Templates (E2B-compatible catalog & builds)
templates, err := c.ListTemplates(ctx)
tpl, err := c.GetTemplateByAlias(ctx, "base")

// Register an existing OCI image without BuildKit
created, err := c.CreateTemplateFromImage(ctx, client.CreateTemplateFromImageRequest{
	FromImage: "python:3.13-slim",
	Alias:     "py313-slim",
	CPUCount:  2,
	MemoryMB:  2048,
})

// Build via rootless BuildKit
built, err := c.BuildTemplate(ctx, client.BuildTemplateRequest{
	Alias:     "custom-agent",
	FromImage: "ubuntu:24.04",
	Steps: []client.BuildStep{
		{Type: "RUN", Args: []string{"apt-get update && apt-get install -y curl"}},
	},
})
```

### Error Handling

Non-2xx/3xx HTTP responses return `*client.APIError`:

```go
var apiErr *client.APIError
if errors.As(err, &apiErr) {
	fmt.Printf("HTTP %d: %s\n", apiErr.StatusCode, apiErr.Body)
}
```

---

## Part 2: `cubepod` CLI

### Building or Installing

```bash
# From the repository root
make build-cli
./bin/cubepod --help

# Or via Go toolchain
go install github.com/cubeplexai/cubepod/cmd/cubepod@latest
```

### Global Flags & Environment Variables

:::caution[Flag Placement]
Global flags **must appear before** the subcommand (for example, `cubepod --json sandbox list`), because the CLI parses global flags from leading arguments prior to dispatching the command.
:::

| Flag | Environment Variable | Default | Description |
| :--- | :--- | :--- | :--- |
| `--gateway-url` | `CUBEPOD_GATEWAY_URL` | `http://127.0.0.1:8080` | CubePod Gateway base URL. |
| `--api-key` | `CUBEPOD_API_KEY` | `""` | API Bearer token. |
| `--json` | — | `false` | Emit structured JSON output for scripting. |

### Command Reference

#### Health & MCP Server

```bash
cubepod health
cubepod mcp    # Starts MCP JSON-RPC 2.0 server over stdio
```

#### Sandbox Commands

| Command | Description |
| :--- | :--- |
| `cubepod sandbox create [--template <id>] [--volume-key <key>]` | Provision a new sandbox (default template: `cubeplex-ubuntu24-desktop`). |
| `cubepod sandbox list [--template <id>]` | List active and paused sandboxes, optionally filtered by template. |
| `cubepod sandbox get <sandbox-id>` | Inspect state, `rootfsGeneration`, and `volumeKey`. |
| `cubepod sandbox exec <sandbox-id> <cmd...>` | Run a foreground command and exit with the remote exit code. |
| `cubepod sandbox write-file <id> <path> <file\|text>` | Write a local file (if the path exists locally) or literal string to `<path>`. |
| `cubepod sandbox read-file <id> <path>` | Stream remote file bytes to `stdout`. |
| `cubepod sandbox ls <id> [path]` | List entries in `[path]` (default `/workspace`). |
| `cubepod sandbox rm <id> <path>` | Delete a file or directory inside the sandbox. |
| `cubepod sandbox archive-sync <id> <dest> <localdir>` | Sync a local directory into `<dest>` via atomic `tar.gz` extraction. |
| `cubepod sandbox pause <id>` | Pause compute (`0` CPU/RAM) while retaining persistent PVCs. |
| `cubepod sandbox connect <id>` | Auto-resume a paused sandbox to `Running`. |
| `cubepod sandbox reset-rootfs <id>` | Reset RootFS Upper while keeping `/workspace` intact. |
| `cubepod sandbox fork <id>` | Create a ~1s CoW clone of both volumes. |
| `cubepod sandbox delete <id>` | Terminate and delete a sandbox. |

#### Template Commands

Requires `featureGates.e2bTemplateAPI=true` on the Gateway for catalog/registration endpoints:

| Command | Description |
| :--- | :--- |
| `cubepod template list` | List available templates (`TEMPLATE ID`, `ALIASES`, `STATUS`, `CPU`, `MEMORY`). |
| `cubepod template get <id-or-alias> [--alias]` | Inspect a template by ID or alias (auto-falls back to alias lookup on 404 or `:`/`/`). |
| `cubepod template create --from-image <img> --alias <alias> [--name <name>] [--cpu <n>] [--memory-mb <n>] [--disk-mb <n>]` | Register a template from an existing OCI image without BuildKit. |
| `cubepod template update <id> --public=true\|false` | Update template public visibility. |
| `cubepod template delete <id> [--force]` | Delete a template (`--force` deletes even if referenced). |

#### WarmPool Commands

| Command | Description |
| :--- | :--- |
| `cubepod warmpool create <name> [--template <id>] [--replicas <n>]` | Create or scale a `PodWarmPool` (default template `cubeplex-ubuntu24-desktop`, replicas `2`). |
| `cubepod warmpool list` | List all active WarmPools and their ready replica counts. |

### CLI Workflow Example

```bash
export CUBEPOD_GATEWAY_URL="http://localhost:8080"

# Create a sandbox with a deterministic workspace key
SANDBOX_ID=$(cubepod --json sandbox create --template cubeplex-ubuntu24-desktop --volume-key ws-demo | jq -r '.sandboxID')

# Sync local skills directory and run an agent script
cubepod sandbox archive-sync "$SANDBOX_ID" /workspace/skills ./skills
cubepod sandbox exec "$SANDBOX_ID" "ls -la /workspace/skills && python3 --version"

# Reset OS packages without touching /workspace
cubepod sandbox reset-rootfs "$SANDBOX_ID"

# Fork into an independent sandbox
FORK_ID=$(cubepod --json sandbox fork "$SANDBOX_ID" | jq -r '.sandboxID')
```

To expose CubePod directly to MCP-compatible IDEs and desktop assistants, continue to [MCP Server Integration](/sdks/mcp-server/).

---
# MCP Server Integration
URL: https://cubepod.cubeplex.ai/sdks/mcp-server/

The `cubepod` binary includes a native **Model Context Protocol (MCP)** JSON-RPC 2.0 stdio server (`cubepod mcp`). Any MCP-compatible client—such as Claude Desktop, Cursor, Windsurf, or custom agent orchestrators—can provision persistent MicroVMs, execute shell commands, edit files, pause compute, and reset RootFS layers without custom glue code.

## Architecture & Protocol

- **Transport**: Line-delimited JSON-RPC 2.0 over `stdin` / `stdout`
- **Protocol Version**: `2024-11-05`
- **Server Info**: `{"name": "cubepod-mcp", "version": "<cubepod-version>"}`
- **Capabilities**: `tools` (`initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`)
- **Gateway Target**: Configured via `--gateway-url` / `$CUBEPOD_GATEWAY_URL` (default `http://127.0.0.1:8080`) and `--api-key` / `$CUBEPOD_API_KEY`.

```mermaid
flowchart LR
  Client["MCP Client (Claude / Cursor / Agent)"] <-->|"JSON-RPC 2.0 stdio"| MCP["cubepod mcp"]
  MCP <-->|"HTTP / REST + Bearer Auth"| GW["cubepod-gateway (:8080)"]
  GW <-->|"in-guest :49983"| Podd["Kata MicroVM (podd)"]
```

## Available MCP Tools (`tools/list`)

`cubepod mcp` exposes 8 tools mapped directly to `pkg/client`:

### 1. `cubepod_create_sandbox`
Provision a new persistent MicroVM execution sandbox.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `templateID` | `string` | No | Template ID for the sandbox base image (default: `cubeplex-ubuntu24-desktop`). |
| `timeout` | `integer` | No | Optional idle timeout in seconds before auto-pause. |

### 2. `cubepod_list_sandboxes`
List active and paused CubePod sandboxes, optionally filtered by template ID.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `templateID` | `string` | No | Optional template ID filter. |

### 3. `cubepod_run_command`
Execute a shell command inside a CubePod sandbox.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID. |
| `command` | `string` | **Yes** | Shell command string to execute. |
| `workdir` | `string` | No | Optional working directory inside the sandbox (default: `/workspace`). |
| `background` | `boolean` | No | Whether to run the command in the background. |

### 4. `cubepod_read_file`
Read file contents from inside a CubePod sandbox.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID. |
| `path` | `string` | **Yes** | Absolute path of the file inside the sandbox. |

### 5. `cubepod_write_file`
Write content to a file inside a CubePod sandbox.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID. |
| `path` | `string` | **Yes** | Absolute destination path inside the sandbox. |
| `content` | `string` | **Yes** | Text or binary content to write. |
| `mode` | `string` | No | File permissions mode (default: `0644`). |

### 6. `cubepod_pause_sandbox`
Pause a running sandbox while retaining persistent volumes (`0` CPU/RAM).

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID to pause. |

### 7. `cubepod_reset_rootfs`
Reset the persistent RootFS Upper layer of a sandbox while preserving `/workspace`.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID. |

### 8. `cubepod_delete_sandbox`
Permanently terminate and delete a CubePod sandbox.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `sandboxID` | `string` | **Yes** | Target sandbox ID to delete. |
| `deleteVolumes` | `boolean` | No | Whether to also delete persistent volumes (default: `false`). |

## Client Configuration Examples

Ensure the `cubepod` binary is built and on your `PATH` (see [Go SDK & CLI](/sdks/go-and-cli/)).

### Claude Desktop

Add `cubepod` to your `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `~/.config/Claude/claude_desktop_config.json` on Linux):

```json
{
  "mcpServers": {
    "cubepod": {
      "command": "/usr/local/bin/cubepod",
      "args": [
        "--gateway-url", "http://127.0.0.1:8080",
        "mcp"
      ],
      "env": {
        "CUBEPOD_API_KEY": "your-api-key-if-configured"
      }
    }
  }
}
```

### Cursor / Windsurf / VS Code

Configure an `stdio` MCP server entry in `.cursor/mcp.json` or your IDE MCP settings:

```json
{
  "mcpServers": {
    "cubepod": {
      "command": "cubepod",
      "args": ["mcp"],
      "env": {
        "CUBEPOD_GATEWAY_URL": "http://127.0.0.1:8080",
        "CUBEPOD_API_KEY": "your-api-key"
      }
    }
  }
}
```

:::tip[Remember Leading Global Flags]
If you pass `--gateway-url` or `--api-key` in `args`, place them **before** `mcp` (for example `["--gateway-url", "http://127.0.0.1:8080", "mcp"]`), or set `CUBEPOD_GATEWAY_URL` and `CUBEPOD_API_KEY` in `env`.
:::

## Smoke Testing via `stdin` / `stdout`

You can verify the MCP server directly from your shell without an external IDE:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | cubepod --gateway-url http://127.0.0.1:8080 mcp
```

Notifications (such as `notifications/initialized` or messages with no `id`) produce no output per the JSON-RPC 2.0 specification, while `initialize` and `tools/list` return single-line JSON responses.

## Agent Recovery Pattern with `reset_rootfs`

Because `cubepod_reset_rootfs` is exposed directly as an MCP tool, an AI coding agent that breaks system packages (e.g. an incompatible `apt` or global `pip` install) can self-heal without losing any source code or artifacts stored under `/workspace`:

1. Call `cubepod_reset_rootfs` with `sandboxID`.
2. Continue calling `cubepod_run_command` and `cubepod_read_file` against the same `sandboxID` and intact `/workspace`.

---
# Python SDK
URL: https://cubepod.cubeplex.ai/sdks/python/

The official CubePod Python SDK (`cubepod`) provides both **async-first** (`AsyncCubePod`) and **synchronous** (`CubePod` / `SyncCubePod`) clients over the CubePod Control and Data Plane HTTP APIs.

- **Package**: `cubepod` (`0.4.0`, Apache-2.0)
- **Python**: `>= 3.11` with inline `py.typed` type annotations
- **Runtime dependency**: `httpx >= 0.27.0`

## Installation

```bash
pip install cubepod
```

:::tip[Using the Official `e2b` Python SDK?]
If you have existing agent code written against `e2b` or `e2b-code-interpreter`, CubePod supports drop-in protocol compatibility without rewriting your SDK calls. See [E2B Drop-in Compatibility](/getting-started/e2b-compatibility/).
:::

## Quickstart (Async & Sync)

Both clients support Python context managers (`async with` / `with`) to close the underlying `httpx` connection pool cleanly.

```python
import asyncio
from cubepod import AsyncCubePod, CubePod

async def main() -> None:
    async with AsyncCubePod(
        base_url="http://localhost:8080",
        api_key="your-api-key",
    ) as client:
        box = await client.create("cubeplex-ubuntu24-desktop")
        res = await client.execute(box.sandbox_id, "python3 --version")
        print(res.output)
        await client.delete(box.sandbox_id)

asyncio.run(main())

# Synchronous client (SyncCubePod is an alias for CubePod)
with CubePod(base_url="http://localhost:8080", api_key="your-api-key") as client:
    box = client.create("cubeplex-ubuntu24-desktop")
    print(client.execute(box.sandbox_id, "uname -a").output)
    client.delete(box.sandbox_id)
```

### Client Configuration

`AsyncCubePod(...)` and `CubePod(...)` share the same constructor options:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `base_url` | `str` | `"http://localhost:8080"` | CubePod Gateway base URL (`http://` is prepended if scheme is omitted). |
| `api_key` | `str \| None` | `None` | Optional Bearer token sent as `Authorization: Bearer <api_key>`. |
| `transport` | `httpx transport \| None` | `None` | Custom `httpx.AsyncBaseTransport` or `httpx.BaseTransport` for testing or custom routing. |
| `max_retries` | `int` | `2` | Maximum automatic retries with exponential backoff on HTTP `502`, `503`, and `504`. |
| `timeout` | `float` | `60.0` | Default request timeout in seconds. |
| `trust_env` | `bool` | `False` | Whether `httpx` should read host `HTTP_PROXY` / `HTTPS_PROXY` environment variables. |

## Sandbox Lifecycle, Reset & 1s CoW Fork

CubePod separates the persistent container RootFS `upperdir` from `/workspace` (see [Dual-Volume Persistence](/concepts/dual-volume-persistence/)). Every lifecycle operation returns a `SandboxInfo` dataclass:

```python
box = await client.create(
    template_id="cubeplex-ubuntu24-desktop",
    volume_key="user-42-workspace",
    timeout_seconds=1800,
    warm_pool_ref="default-pool",
    metadata={"agent": "coder", "env": "dev"},
)

# Check terminal state helper
print(box.sandbox_id, box.state, box.rootfs_generation, box.is_terminal)

# List or inspect sandboxes
boxes = await client.list(template_id="cubeplex-ubuntu24-desktop")
same_box = await client.get(box.sandbox_id)
raw_json = await client.get_raw(box.sandbox_id)

# Keepalive timeout & lease protection against idle auto-pause
await client.renew_timeout(box.sandbox_id, timeout_seconds=3600)
await client.acquire_lease(box.sandbox_id, lease_seconds=300)

# Pause compute (0 CPU/RAM, retains both RootFS Upper and Workspace PVCs)
await client.pause(box.sandbox_id)

# Connect (automatically resumes a Paused sandbox)
await client.connect(box.sandbox_id)

# Wipe RootFS Upper changes (e.g., broken apt/pip state) while preserving /workspace
await client.reset_rootfs(box.sandbox_id)

# Create a ~1s Copy-on-Write clone of both RootFS and Workspace volumes
child = await client.fork(
    box.sandbox_id,
    volume_key="user-42-branch-a",
    metadata={"branch": "experiment-1"},
)

await client.delete(child.sandbox_id)
await client.delete(box.sandbox_id)
```

### `create(...)` Parameters

- `template_id` (`str = "cubeplex-ubuntu24-desktop"`): Template ID, alias, or OCI image reference.
- `volume_key` (`str | None`): Deterministic persistent storage key (`extension.volumeKey`) for re-attaching workspace state across sandboxes.
- `metadata` (`dict[str, str] | None`): Arbitrary key-value labels attached to the sandbox.
- `network_policy` (`dict[str, Any] | None`): Zero-Trust outbound firewall specification (`defaultAction`, `allowHosts`, `denyHosts`, `upstreamProxy`).
- `secret_bindings` (`list[dict[str, Any]] | None`): `cpodref_` credential bindings merged into `networkPolicy.secretBindings`.
- `timeout_seconds` (`int | None`): Idle timeout before automatic pause.
- `warm_pool_ref` (`str | None`): Claim a pre-attached MicroVM from a `PodWarmPool`.
- `resource` (`dict[str, str] | None`): Optional resource overrides placed in `extension.resource`.

## Command Execution & Cursor Log Streaming

Foreground commands run via `execute(...)` and default to `uid=1000, gid=1000` (override with `uid=0, gid=0` when root privileges are needed, or `uid=None, gid=None` to omit).

```python
# Foreground execution
res = await client.execute(
    box.sandbox_id,
    "pytest -q",
    workdir="/workspace",
    envs={"PYTHONUNBUFFERED": "1"},
    uid=1000,
    gid=1000,
    timeout=120.0,
)
print(res.exit_code, res.output)

# Background execution + stateless byte-offset cursor polling
cmd = await client.start_command(
    box.sandbox_id,
    "for i in 1 2 3; do echo tick-$i; sleep 1; done",
    workdir="/workspace",
)

status = await client.get_command_status(box.sandbox_id, cmd.id)
logs = await client.poll_command(box.sandbox_id, cmd.id, cursor=0)
print(logs.content, logs.cursor, logs.running)

# Stream incremental CommandLogs chunks until completion
async for chunk in client.stream_command(box.sandbox_id, cmd.id, poll_interval=0.05):
    if chunk.content:
        print(chunk.content, end="")

# Terminate a background command process group
await client.kill_command(box.sandbox_id, cmd.id)
```

## Files, Streaming Reads & `archive_sync`

```python
# Write UTF-8 text or raw bytes
await client.write_file(
    box.sandbox_id,
    "/workspace/app.py",
    "print('hello cubepod')\n",
    uid=1000,
    gid=1000,
    mode="0644",
)

# Read full bytes, stream raw chunks, or bounded text read
raw_bytes = await client.read_file(box.sandbox_id, "/workspace/app.py")

stream = await client.stream_file(box.sandbox_id, "/workspace/large.bin", chunk_size=65536)
async for chunk in stream:
    process_chunk(chunk)

# Raises CubePodFileTooLargeError if file exceeds max_bytes
from cubepod import CubePodFileTooLargeError

try:
    text = await client.read_text_file(
        box.sandbox_id,
        "/workspace/app.py",
        max_bytes=1024 * 1024,
        encoding="utf-8",
    )
except CubePodFileTooLargeError as exc:
    print("File too large:", exc)

# List and delete files
entries = await client.list_files(box.sandbox_id, "/workspace")
for entry in entries:
    print(entry.name, entry.is_dir, entry.size, entry.mode)

await client.delete_file(box.sandbox_id, "/workspace/old.txt")

# Atomic tar.gz directory sync (accepts a dict of path -> content, or prebuilt .tar.gz bytes)
await client.archive_sync(
    box.sandbox_id,
    {
        "skills/research/SKILL.md": "# Research Skill\n",
        "skills/research/run.py": b"print('ready')\n",
    },
    dest="/workspace",
    uid=1000,
    gid=1000,
    remove_paths=["skills/deprecated"],
)
```

## Interactive Desktop & Signed Panel Endpoints

CubePod supports lazy desktop activation (XFCE + noVNC, `ttyd` web terminal, and Chromium CDP) and HMAC-SHA256 signed `/panel/{token}/` proxy endpoints:

```python
# Start interactive desktop stack lazily inside a desktop-enabled sandbox
desktop = await client.start_desktop(
    box.sandbox_id,
    resolution="1280x800x24",
    initial_url="https://example.com",
    expires_in_seconds=3600,
)
print(desktop.desktop_url, desktop.terminal_url, desktop.cdp_url)

status = await client.get_desktop_status(box.sandbox_id)
await client.stop_desktop(box.sandbox_id)

# Mint a signed panel URL for any HTTP/WS/WebRTC port inside the sandbox
panel = await client.get_panel_endpoint(box.sandbox_id, port=8080, expires_in_seconds=3600)
print(panel.url, panel.token, panel.expires_at)
```

## Zero-Trust `cpodref_` Egress Secret Bindings

Never pass raw external API keys inside `envs` or files. Register `secret_bindings` at sandbox creation time so only opaque `cpodref_` placeholders exist inside the MicroVM, while `cubepod-egress` substitutes the real credential exclusively on approved target hosts:

```python
box = await client.create(
    "cubeplex-ubuntu24-desktop",
    network_policy={
        "defaultAction": "Deny",
        "allowHosts": ["api.openai.com", "api.github.com"],
    },
    secret_bindings=[
        {
            "envName": "OPENAI_API_KEY",
            "rawSecret": os.environ["REAL_OPENAI_KEY"],
            "allowedHosts": ["api.openai.com"],
            "allowedHeaders": ["Authorization"],
        }
    ],
)
```

See [Zero-Trust Egress & Secrets](/concepts/zero-trust-egress/) for the full mTLS exchange flow.

## WarmPools & Templates

```python
# Create or scale a standby PodWarmPool for <50ms sandbox claims
await client.create_warmpool("fast-pool", template_id="cubeplex-ubuntu24-desktop", replicas=3)
pools = await client.list_warmpools()

# Template catalog & builds
templates = await client.list_templates()
tpl = await client.get_template_by_alias("base")

# Register an existing OCI image (no BuildKit required)
registered = await client.create_template_from_image(
    from_image="python:3.13-slim",
    alias="py313-slim",
    cpu_count=2,
    memory_mb=2048,
    wait=True,
)

# Full recipe build via BuildKit
built = await client.build_template(
    name="data-science:v1",
    from_image="python:3.13",
    steps=[{"type": "RUN", "args": ["pip install pandas numpy"]}],
    cpu_count=4,
    memory_mb=4096,
    wait=True,
)
```

For full template build rules and constraints, see [Template Catalog & Builds](/sdks/templates/).

## Data Models Reference

| Model | Key Fields |
| :--- | :--- |
| `SandboxInfo` | `sandbox_id`, `template_id`, `state`, `envd_port` (`49983`), `rootfs_generation` (`1`), `metadata`, `raw`, `.is_terminal` |
| `ExecutionResult` | `id`, `exit_code`, `output`, `running`, `pid`, `cursor` |
| `CommandInfo` | `id`, `pid`, `running`, `exit_code`, `cursor`, `output` |
| `CommandLogs` | `id`, `content`, `cursor`, `running`, `exit_code` |
| `FileEntry` | `name`, `path`, `is_dir`, `size`, `mode`, `modified_at` |
| `PanelEndpoint` | `url`, `token`, `expires_at` |
| `DesktopSession` | `status`, `desktop_url`, `terminal_url`, `cdp_url`, `expires_at` |
| `CubePodFileTooLargeError` | Subclass of `ValueError` raised by `read_text_file` when `max_bytes` is exceeded |

---
# Template Catalog & Builds
URL: https://cubepod.cubeplex.ai/sdks/templates/

CubePod resolves every `templateID` passed to `POST /sandboxes` through the `PodTemplate` CRD (`cubepod.io/v1alpha1`) and supports two template workflows:

1. **Zero-BuildKit Registration (Alpha)**: Register an existing OCI registry image with CPU, memory, and RootFS size metadata.
2. **Dockerfile-Subset Recipe Builds (Beta)**: Build and push custom OCI images via **rootless BuildKit** in Kubernetes (or the local Docker daemon in `docker-loopback` mode) using the E2B-compatible `v3`/`v2` template build protocol.

## Feature Gates & Helm Settings

Template catalog and build endpoints are controlled by two independent flags on `cubepod-gateway` and `cubepod-controller`:

| Helm Value | CLI Flag | Default | Effect |
| :--- | :--- | :--- | :--- |
| `featureGates.e2bTemplateAPI` | `--e2b-template-api` / `--feature-gate=E2BTemplateAPI=true` | `false` | Switches `GET /templates` from the legacy 3-card `{"templates":[...]}` wrapper to the E2B JSON array (`E2BTemplate[]`), and enables `/v2/templates`, `/v3/templates`, `/templates/aliases/{alias}`, `/templates/tags`, `PATCH`, and `DELETE`. |
| `templateBuild.enabled` | `--template-build` | `false` | Enables `BuildKit` (Kubernetes) or local Docker recipe builds (`POST /v2/templates/{id}/builds/{buildID}` with `steps` and `PUT /templates/{id}/files/{hash}`). When `false`, those endpoints return HTTP `501`, though registering an existing `fromImage` with empty `steps` still works when `e2bTemplateAPI` is enabled. |

## Built-In Seeded Templates & Aliases

On startup, `cubepod-controller` seeds three default `PodTemplate` entries (without overwriting existing objects):

| Template Name | Aliases | Default Image | CPU / RAM / Disk |
| :--- | :--- | :--- | :--- |
| `cubeplex-ubuntu24-desktop` | `cubeplex-ubuntu24-desktop`, `base`, `code-interpreter`, `code-interpreter-v1`, `python` | `cubeplex-ubuntu24-desktop:latest` | `2` vCPU / `2048 MB` / `10Gi` RootFS + `20Gi` Workspace |
| `ubuntu-24-04` | `ubuntu:24.04` | `ubuntu:24.04` | `2` vCPU / `2048 MB` / `10Gi` RootFS + `20Gi` Workspace |
| `debian-12` | `debian:12` | `debian:12` | `2` vCPU / `2048 MB` / `10Gi` RootFS + `20Gi` Workspace |

If `POST /sandboxes` receives an unknown `templateID` containing a registry/tag shape (such as `ghcr.io/org/custom:v1`), CubePod falls back to booting that string as a direct OCI image reference unless it matches an in-progress/unready `PodTemplate`.

## Path 1: Register an Existing OCI Image (No BuildKit)

When you already have an OCI image in a registry your cluster can pull, register it with `fromImage` and empty `steps`:

```python
# Python SDK
from cubepod import CubePod

with CubePod(base_url="http://localhost:8080") as client:
    res = client.create_template_from_image(
        from_image="python:3.13-slim",
        alias="py313-slim",
        cpu_count=2,
        memory_mb=2048,
        min_free_disk_mb=10240,
        wait=True,
    )
    print(res["templateID"], res["aliases"])
```

```bash
# cubepod CLI
cubepod template create \
  --from-image python:3.13-slim \
  --alias py313-slim \
  --cpu 2 \
  --memory-mb 2048 \
  --disk-mb 10240
```

Once ready, launch sandboxes using either `templateID` or the alias `py313-slim`.

## Path 2: Custom Recipe Builds (`POST /v3/templates` + `POST /v2/.../builds`)

When `templateBuild.enabled=true`, CubePod implements the E2B multi-step build flow:

```mermaid
flowchart LR
  Step1["1. POST /v3/templates"] -->|"202 templateID + buildID"| Step2["2. Upload COPY context (optional)"]
  Step2 -->|"GET/PUT /templates/{id}/files/{hash}"| Step3["3. POST /v2/templates/{id}/builds/{buildID}"]
  Step3 -->|"BuildKit / Docker + readyCmd probe"| Step4["4. Poll /builds/{buildID}/status -> ready"]
```

### Example in TypeScript

```ts
import { CubePodClient } from 'cubepod';

const client = new CubePodClient({ baseUrl: 'http://localhost:8080' });

// 1. Register template build slot
const reg = await client.createTemplate({
  name: 'ml-sandbox:v1',
  cpuCount: 4,
  memoryMB: 4096,
  minFreeDiskMb: 12288,
});

// 2. Start BuildKit build
await client.startTemplateBuild(reg.templateID, reg.buildID, {
  fromImage: 'python:3.13',
  steps: [
    { type: 'ENV', args: ['PIP_NO_CACHE_DIR', '1'] },
    { type: 'RUN', args: ['pip install numpy pandas matplotlib'] },
    { type: 'WORKDIR', args: ['/app'] },
    { type: 'USER', args: ['1000:1000'] },
  ],
  startCmd: 'python3 -m http.server 8000',
  readyCmd: 'curl -fsS http://127.0.0.1:8000 >/dev/null',
});

// 3. Poll until status === 'ready' or 'error'
let status = await client.getTemplateBuildStatus(reg.templateID, reg.buildID);
while (status.status === 'waiting' || status.status === 'building') {
  await new Promise((r) => setTimeout(r, 1000));
  status = await client.getTemplateBuildStatus(reg.templateID, reg.buildID);
}
if (status.status === 'error') {
  throw new Error(`${status.reason?.step}: ${status.reason?.message}`);
}
```

### Supported Build Steps & Validation Rules

`RenderDockerfile` in `pkg/controller/template.go` validates every step before invoking BuildKit or Docker:

| Step Type | Arguments | Behavior & Constraints |
| :--- | :--- | :--- |
| `RUN` | `[command, optionalUser]` | Runs shell command. Preceding `ENV` variables are exported inline during `RUN`. |
| `COPY` / `ADD` | `[src, dest, optionalChown, optionalMode]` | Copies from uploaded `filesHash` tar context (`64` lowercase hex chars). Rejects absolute `src`, `..` traversal, copying `podd`/`podd-init`, or `dest` under `/workspace`. |
| `WORKDIR` | `[dir]` | Sets working directory. **Rejects `/workspace` or subdirectories** (HTTP `400`). |
| `USER` | `[uid \| uid:gid \| username]` | Sets image `USER` and populates `PodTemplate` runtime user (`runAsUser` / `runAsGroup` / `runAsUsername`). |
| `ENV` | `[key1, val1, key2, val2, ...]` | **Build-time only** (applied to subsequent `RUN` steps, not persisted in image `Config.Env`). |
| `ARG` | — | **Disallowed** (HTTP `400`). CubePod only emits an internal `ARG CUBEPOD_CACHEBUST` when `force: true`. |

:::caution[Why `/workspace` Is Forbidden During Template Builds]
In CubePod, `/workspace` is dynamically mounted at Pod startup from a per-sandbox `workspace-pvc` (see [Dual-Volume Persistence](/concepts/dual-volume-persistence/)). Any file written to `/workspace` during image build would be masked at runtime and could pollute persistent user workspaces, so `WORKDIR`, `COPY`, and `ADD` targeting `/workspace` fail fast with HTTP `400`. Place baked assets in `/app`, `/opt`, or `/home/user` instead.
:::

### Important Differences from Firecracker Snapshot Builders

1. **No `podd` or `podd-init` in Template Images**: CubePod injects `/opt/cubepod/bin/{podd-init,podd}` via `initContainer` at Pod startup. Attempting to `COPY`/`ADD` binaries named `podd` or `podd-init` is rejected (`400`).
2. **`startCmd` & `readyCmd` Execution Model**: CubePod does not snapshot guest RAM at build time. Instead, `PodTemplate.spec.startCmd` is started by `podd` after `pivot_root` on every sandbox boot, and `readyCmd` is probed up to `templateBuild.probeTimeout` (default `120s`). If `readyCmd` times out on sandbox creation, `POST /sandboxes` returns `503` with `sandboxID` and `logPath: "/var/log/cubepod/start-cmd.log"` so you can inspect logs.
3. **Zero Impact on Existing Sandboxes**: Rebuilding a template updates `PodTemplate` for **new** sandboxes only. Existing `rootfs-pvc` and `workspace-pvc` volumes are never touched, and if a rebuild fails (`error`), the previous `ready` image remains active.
4. **Build Status Machine**: `waiting` → `building` (wire mapping combines internal `uploaded` and `building`) → `ready` or `error`.

## Registry Credentials & Security Separation

CubePod strictly separates **base-image pull credentials** from **target template registry credentials**:

- **`fromImageRegistry`**: Passed per-build by the user (`{type, username, password}`) to pull a private base image. The controller stores it in an ephemeral Secret (`cubepod-template-src-<buildID>`), passes it only to the BuildKit session, scrubs the password (`[REDACTED]`) from build logs, rejects steps containing the password or `cpodref_` references, and deletes the Secret once the build finishes (`ready` or `error`).
- **Cluster Target Registry (`templateBuild.registry`)**: Configured by cluster operators via Helm (`url`, `repositoryPrefix`, `pushSecret`, `pullSecret`). `pushSecret` pushes the built image to `<url>/<repositoryPrefix>/...`, while `pullSecret` is attached as `imagePullSecrets` on probe and sandbox Pods.

See [Helm Chart Values](/reference/helm-values/) and [Kubernetes CRDs](/reference/crds/) for the full `PodTemplate` and `templateBuild` field definitions.

---
# TypeScript SDK
URL: https://cubepod.cubeplex.ai/sdks/typescript/

The official CubePod TypeScript / JavaScript SDK (`cubepod`) is a **zero-dependency** ESM library built exclusively on Web and Node.js 20+ standard APIs (`fetch`, `ReadableStream`, `TextDecoder`, `Headers`, `URLSearchParams`, and `CompressionStream`). It ships complete `.d.ts` type declarations and runs on Node.js 20+, Deno, Bun, and modern edge runtimes.

- **Package**: `cubepod` (`0.4.0`, Apache-2.0)
- **Module format**: Native ESM (`"type": "module"`)
- **Engines**: `node >= 20.0.0`

## Installation

```bash
npm install cubepod
```

## Two Ways to Use the SDK

1. **`Sandbox` (Object-Oriented)**: High-level handle with `.commands`, `.code`, and `.files` namespaces—similar to E2B's `Sandbox` ergonomics.
2. **`CubePodClient` (Stateless HTTP Client)**: Direct client covering all sandbox, command, code interpreter, filesystem, template catalog/build, and WarmPool endpoints.

```ts
import { CubePodClient, Sandbox } from 'cubepod';

const sandbox = await Sandbox.create({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.CUBEPOD_API_KEY,
  templateId: 'cubeplex-ubuntu24-desktop',
  volumeKey: 'workspace-user-42',
});

const result = await sandbox.commands.run('ls -la /workspace');
console.log(result.stdout);

await sandbox.kill();
```

### Configuration & Environment Fallbacks

Both `new CubePodClient(options)` and `Sandbox.create(options)` accept `CubePodClientOptions`:

| Option | Default / Env Fallback | Description |
| :--- | :--- | :--- |
| `baseUrl` | `CUBEPOD_BASE_URL` → `CUBEPOD_API_URL` → `'http://localhost:8080'` | Gateway base URL. |
| `apiKey` | `CUBEPOD_API_KEY` → `E2B_API_KEY` → `undefined` | Bearer token for `Authorization: Bearer ...`. |
| `timeoutMs` | `60_000` | Per-request timeout in milliseconds (can also pass `AbortSignal` via `options.signal`). |
| `maxRetries` | `2` | Retries on transient `502`, `503`, `504` (skips retry on `503` terminal `readyCmd` probe timeout). |
| `retryDelayMs` | `10` | Initial exponential backoff delay in milliseconds. |
| `fetch` | `globalThis.fetch` | Custom `fetch` implementation for proxies or unit testing. |
| `headers` | `{}` | Default headers appended to every request. |

## Sandbox Lifecycle, CoW Fork & RootFS Reset

```ts
import { Sandbox } from 'cubepod';

const sandbox = await Sandbox.create('ubuntu:24.04', {
  baseUrl: 'http://localhost:8080',
  timeout: 1800,
  autoPause: true,
  autoResume: true,
  rootfsSize: '10Gi',
  workspaceSize: '20Gi',
});

// Suspend compute (0 CPU/RAM) while retaining RootFS Upper + Workspace volumes
await sandbox.pause();

// Auto-resume from Paused state
const resumed = await Sandbox.connect(sandbox.sandboxId, {
  baseUrl: 'http://localhost:8080',
});

// Renew idle timeout & protect against idle auto-pause with an exclusive lease
await resumed.setTimeout(3600);
await resumed.acquireLease(600);

// Refresh sandbox snapshot & metadata from the Gateway
await resumed.refresh();

// Wipe RootFS Upper changes while keeping /workspace intact
await resumed.resetRootfs();

// ~1s Copy-on-Write clone of both RootFS and Workspace volumes
const child = await resumed.fork({
  volumeKey: 'workspace-user-42-exp1',
  metadata: { branch: 'experiment-1' },
});

// Permanently delete child sandbox and its PVCs
await child.kill({ deleteVolumes: true });
```

`CubePodClient` also exposes `refreshSandbox(sandboxId, durationSeconds)` (`POST /sandboxes/{id}/refreshes`), `listSandboxes({ state, templateId })`, and `health()`.

## Endpoints & Signed Panel URLs

```ts
// E2B getHost compatibility (returns "<port>-<sandboxID>.<domain>")
const host = await sandbox.getHost(8080);
const endpointInfo = await sandbox.getEndpointHost(8080);
console.log(endpointInfo.url);

// Mint an HMAC-SHA256 signed /panel/{token}/ URL for web, noVNC, ttyd, or WebRTC views
const panel = await sandbox.createEndpoint(8080, { expiresInSeconds: 3600 });
console.log(panel.url, panel.expiresAt);
```

## Commands & Files (UID/GID Preservation)

:::note[Default User Preservation]
Unlike clients that force `uid=1000` on every call, the TypeScript SDK **omits `uid` and `gid` by default** in `commands.run` and `files.write` so the template's configured `USER` is preserved on the server. Pass `uid` / `gid` explicitly (including `uid: 0, gid: 0` for `root`) when overriding ownership.
:::

```ts
// Foreground command (uses template USER by default)
const res = await sandbox.commands.run('id');

// Background command + stateless cursor-based log polling
const bg = await sandbox.commands.run('python3 -u worker.py', {
  background: true,
  workdir: '/workspace',
  envs: { PYTHONUNBUFFERED: '1' },
});
const status = await sandbox.commands.getStatus(bg.id);
const logs = await sandbox.commands.getLogs(bg.id, { cursor: 0 });
await sandbox.commands.kill(bg.id);

// File write, read, list, and delete
await sandbox.files.write('/workspace/app.py', 'print("hello")\n');
await sandbox.files.write('/etc/app.conf', new Uint8Array([1, 2, 3]), {
  uid: 0,
  gid: 0,
  mode: '0600',
});
const text = await sandbox.files.readText('/workspace/app.py');
const bytes = await sandbox.files.readBytes('/workspace/app.py');
const entries = await sandbox.files.list('/workspace');
await sandbox.files.remove('/workspace/app.py');

// Atomic archive-sync (pass a file map or prebuilt tar.gz Uint8Array/ArrayBuffer)
await sandbox.files.archiveSync(
  { 'my-skill/SKILL.md': '# My Skill\n' },
  { dest: '/workspace/skills', removePaths: ['deprecated-skill'] },
);
```

The SDK also exports low-level archive helpers `buildTarBytes(files, options?)`, `gzipBytes(input)`, and `buildTarGzBytes(files, options?)`.

## Code Interpreter (Streaming NDJSON & Contexts)

`sandbox.code` streams NDJSON chunks from the in-guest interpreter and invokes callbacks as output arrives—supporting rich `text`, base64 `png`, and `html` results alongside stateful multi-turn contexts (`python`, `bash`, `javascript`, `typescript`, `r`, `java`).

```ts
const ctx = await sandbox.code.createContext({
  language: 'python',
  cwd: '/workspace',
});

const execution = await sandbox.code.runCode(
  'import math\nprint("pi =", math.pi)\nmath.sqrt(16)',
  {
    contextId: ctx.id,
    onStdout: (msg) => process.stdout.write(msg.text),
    onStderr: (msg) => process.stderr.write(msg.text),
    onResult: (res) => console.log('Result:', res.text, res.png ? '[png]' : ''),
    onError: (err) => console.error(err.name, err.value, err.traceback),
  },
);

console.log(execution.text); // "4.0"

const contexts = await sandbox.code.listContexts();
await sandbox.code.restartContext(ctx.id);
await sandbox.code.deleteContext(ctx.id);
```

For custom streaming parsers, `readNdjsonStream<T>(stream, onItem)` is exported directly from `cubepod`.

## Zero-Trust Egress & `secretBindings`

Pass `networkPolicy` and `secretBindings` when provisioning a sandbox to keep raw credentials outside the MicroVM:

```ts
const sandbox = await Sandbox.create('cubeplex-ubuntu24-desktop', {
  networkPolicy: {
    defaultAction: 'Deny',
    allowHosts: ['api.openai.com'],
  },
  secretBindings: [
    {
      envName: 'OPENAI_API_KEY',
      rawSecret: process.env.REAL_OPENAI_KEY,
      allowedHosts: ['api.openai.com'],
      allowedHeaders: ['Authorization'],
    },
  ],
});
```

## Template Catalog, Builds & WarmPools

`CubePodClient` covers the full E2B-compatible v1/v2/v3 template lifecycle as well as WarmPools:

```ts
const client = new CubePodClient({ baseUrl: 'http://localhost:8080' });

// List templates (v1 and paginated v2 via X-Next-Token)
const templates = await client.listTemplates();
const page = await client.listTemplatesV2({ limit: 50 });

// Inspect by ID or alias (automatically URI-encoded for org/name:v1)
const tpl = await client.getTemplate('org/name:v1');
const byAlias = await client.getTemplateByAlias('base');

// Create and start a template build (v3/v2)
const req = await client.createTemplate({
  name: 'python-data:v1',
  cpuCount: 2,
  memoryMB: 2048,
});

await client.startTemplateBuild(req.templateID, req.buildID, {
  fromImage: 'python:3.13',
  steps: [{ type: 'RUN', args: ['pip install pandas numpy'] }],
});

const buildStatus = await client.getTemplateBuildStatus(req.templateID, req.buildID);
if (buildStatus.status === 'error') {
  console.error(buildStatus.reason?.step, buildStatus.reason?.message);
}

await client.assignTemplateTags(`${req.templateID}:default`, ['prod', 'latest']);
await client.updateTemplateVisibility(req.templateID, true);
await client.deleteTemplate(req.templateID, { force: false });

// WarmPools
await client.createWarmPool({
  name: 'python-pool',
  templateRef: 'python-data:v1',
  replicas: 2,
});
const pools = await client.listWarmPools();
```

See [Template Catalog & Builds](/sdks/templates/) for context upload (`getTemplateFileUploadLink`, `uploadTemplateFileContext`) and Dockerfile step rules.

## Error Handling

All SDK errors extend `CubePodError`. HTTP `>= 400` responses throw `CubePodAPIError` with structured diagnostic properties:

```ts
import { CubePodAPIError, CubePodError } from 'cubepod';

try {
  await client.getTemplate('non-existent');
} catch (err) {
  if (err instanceof CubePodAPIError) {
    console.error({
      statusCode: err.statusCode,
      code: err.code,
      sandboxId: err.sandboxId,
      logPath: err.logPath,
      step: err.step,
      details: err.details,
      message: err.message,
    });
  } else if (err instanceof CubePodError) {
    console.error(err.message);
  }
}
```

---
# Docker Compose Local Development
URL: https://cubepod.cubeplex.ai/deployment/docker-compose/

CubePod includes a self-contained `docker-compose` topology under `deploy/docker-compose/docker-compose.yaml` for developing and testing the control plane, SDKs, CLI, and MCP server on a single Docker host—without needing Kubernetes, KVM, or Kata Containers.

## Topology & Shared Volumes

```mermaid
flowchart LR
  Client["SDK / CLI / curl :8080"] --> Gateway["cubepod-gateway (:8080)\nCUBEPOD_RUNTIME_MODE=docker-loopback"]
  Gateway -->|"State files (/var/lib/cubepod/state)"| StateVol[("cubepod-state")]
  Gateway -->|"Docker Socket (/var/run/docker.sock)"| Docker["Docker Engine"]
  Docker -->|"Loopback volumes (/var/lib/cubepod/volumes)"| VolStore[("cubepod-volumes")]
  Controller["cubepod-controller (:8081)"] -->|"State files (/var/lib/cubepod/state)"| StateVol
  Egress["cubepod-egress (:18080)\n-default-allow=true"] -.->|"Outbound proxy"| Internet["External APIs"]
```

Both `cubepod-gateway` and `cubepod-controller` share the `cubepod-state` Docker named volume at `/var/lib/cubepod/state`, while `cubepod-gateway` mounts the host Docker socket (`/var/run/docker.sock`) and the `cubepod-volumes` named volume at `/var/lib/cubepod/volumes`.

## Quick Start

Start the three services from the repository root:

```bash
docker compose -f deploy/docker-compose/docker-compose.yaml up --build
```

Once the containers are healthy, verify the Gateway and Controller health endpoints:

```bash
curl -fsS http://localhost:8080/health
curl -fsS http://localhost:8081/healthz
```

You can now point any CubePod client at `http://localhost:8080`:

```bash
export CUBEPOD_GATEWAY_URL=http://localhost:8080
cubepod sandbox create --template cubeplex-ubuntu24-desktop
```

To tear down the stack and remove the local state and volume storage:

```bash
docker compose -f deploy/docker-compose/docker-compose.yaml down -v
```

## Service Configuration Reference

The table below reflects the exact service definitions in `deploy/docker-compose/docker-compose.yaml`:

| Service | Dockerfile Context | Published Port | Default Flags & Environment | Mounted Volumes |
| :--- | :--- | :--- | :--- | :--- |
| `cubepod-gateway` | `images/gateway/Dockerfile` (root `../..`) | `8080:8080` | `-addr=:8080`, `--e2b-template-api=false`, `--template-build=false`, `--state-dir=/var/lib/cubepod/state`, `--template-probe-timeout=120s`, `CUBEPOD_RUNTIME_MODE=docker-loopback`, `CUBEPOD_STATE=/var/lib/cubepod/state` | `/var/run/docker.sock:/var/run/docker.sock`, `cubepod-volumes:/var/lib/cubepod/volumes`, `cubepod-state:/var/lib/cubepod/state` |
| `cubepod-controller` | `images/controller/Dockerfile` (root `../..`) | `8081:8081` | `-addr=:8081`, `--e2b-template-api=false`, `--template-build=false`, `--state-dir=/var/lib/cubepod/state`, `--template-probe-timeout=120s`, `CUBEPOD_STATE=/var/lib/cubepod/state` | `cubepod-state:/var/lib/cubepod/state` |
| `cubepod-egress` | `images/egress/Dockerfile` (root `../..`) | `18080:18080` | `-addr=:18080`, `-default-allow=true` | — |

## How `docker-loopback` Simulates Dual-Volume Persistence

In Kubernetes production clusters, CubePod pairs two raw block PVCs per sandbox (`rootfs-pvc` and `workspace-pvc`) and lets `podd-init` mount and `pivot_root` an OverlayFS inside a Kata microVM. Locally, `pkg/runtime/docker.go` mirrors that split using Docker and loopback storage:

- **`BinDir` injection (`/opt/cubepod/bin`)**: Rather than baking `podd` into user images, the Docker driver exposes the runtime binaries from `BinDir` (`/opt/cubepod/bin` by default) into sandbox containers.
- **Sparse `ext4` loopback volumes**: When `EnableSparseExt4` is active on `DockerConfig`, the driver creates sparse `ext4` backing files (default `SparseExt4Size`: `100MiB` under `BaseDir`, defaulting to `<os.TempDir>/cubepod-docker`) so sandbox pause, resume, RootFS resets, and workspace persistence behave consistently with production semantics.
- **Health polling timeout**: Container readiness checks default to a `5s` `HealthTimeout`.

See [Dual-Volume Persistence](/concepts/dual-volume-persistence/) and [In-Guest Init & podd](/concepts/in-guest-init-and-podd/) for how this maps directly onto the production Kata runtime.

## Enabling E2B Template Builds Locally

By default, `deploy/docker-compose/docker-compose.yaml` starts with both `--e2b-template-api=false` and `--template-build=false` (so only the pre-seeded default templates are active).

To test template builds or the `/v2/templates` and `/v3/templates` HTTP endpoints locally:

1. Ensure `/var/run/docker.sock:/var/run/docker.sock` is mounted into `cubepod-controller` and flip `--e2b-template-api=true` and `--template-build=true` on the Gateway and Controller flags so the controller routes builds through `LocalDockerBuilder`.
2. Restart the Compose services or run native Go/Rust binaries directly with `make build` and `make test-e2e`.

## Building & Testing Outside Compose

For rapid edit-compile loops directly on the host machine, the repository `Makefile` exposes:

```bash
# Format Rust & Go code
make fmt

# Run Rust clippy & Go vet
make vet

# Build all binaries (bin/podd-init, bin/podd, bin/cubepod-controller, bin/cubepod-gateway, bin/cubepod-egress, bin/cubepod)
make build

# Run all Rust and Go unit tests
make test

# Run the multi-process local E2E test suite
make test-e2e
```

## Next Steps

- Deploy to Kubernetes with Helm in [Kubernetes & Helm Deployment](/deployment/kubernetes-helm/).
- Configure Kata Containers and block storage drivers in [Kata & Block Storage](/deployment/kata-and-block-storage/).
- Explore the SDKs in [Python SDK](/sdks/python/), [TypeScript SDK](/sdks/typescript/), and [Go SDK & CLI](/sdks/go-and-cli/).

---
# Kata Containers & Block Storage
URL: https://cubepod.cubeplex.ai/deployment/kata-and-block-storage/

In production Kubernetes clusters, CubePod runs each sandbox inside a dedicated Kata Containers microVM backed by two CSI raw `Block` PVCs (`/dev/cubepod-rootfs` and `/dev/cubepod-workspace`). Hardware virtualization ensures kernel, mount-namespace, and device isolation for untrusted agent workloads, while thin raw block storage unlocks fast snapshot cloning (`POST /sandboxes/{id}/fork`) and persistent OverlayFS state across pause/resume cycles.

## Step 1: Configure `containerd` for Kata + Block Devices

Every worker node running sandboxes needs KVM support (`/dev/kvm` with `vmx` or `svm`), `containerd`, `containerd-shim-kata-v2`, and `kata-runtime`.

CubePod ships an automated configuration helper at `deploy/k8s/kata/configure-containerd-kata.sh`:

```bash
# Preview changes without modifying the node
sudo bash deploy/k8s/kata/configure-containerd-kata.sh --dry-run

# Apply configuration and restart containerd
sudo bash deploy/k8s/kata/configure-containerd-kata.sh --restart
```

Supported flags:

| Flag | Default / Purpose |
| :--- | :--- |
| `--dry-run` | Print planned edits without modifying config files |
| `--config-path <path>` | Path to containerd config (default `/etc/containerd/config.toml`) |
| `--kata-config-path <path>` | Override the Kata configuration file path referenced by the shim |
| `--allow-missing-kvm` | Continue validation even if `/dev/kvm` is absent (for non-nested test setups) |
| `--restart` | Restart `containerd` after writing updated configuration |

### Why `privileged_without_host_devices` Is Required

Inside each sandbox pod, `podd-init` runs as PID 1 with privileges to run `e2fsck`, `mkfs.ext4`, `mount`, OverlayFS setup, and `pivot_root` on `/dev/cubepod-rootfs` and `/dev/cubepod-workspace`. `configure-containerd-kata.sh` sets two critical flags on the Kata runtime handler in `/etc/containerd/config.toml`:

- `privileged_without_host_devices = true`
- `privileged_without_host_devices_all_devices_allowed = true`

Without these settings, `containerd` attempts to bind-mount every host `/dev/*` node into the privileged container inside the Kata guest, causing device conflicts such as `/dev/full: EEXIST` during pod startup.

## Step 2: Apply Kata `RuntimeClass` Manifests

Label GPU/KVM-capable worker nodes (`kubectl label node <node> katacontainers.io/kata-runtime=true`) and apply `deploy/k8s/kata/runtimeclasses.yaml`:

```bash
kubectl apply -f deploy/k8s/kata/runtimeclasses.yaml
```

The manifest defines two `RuntimeClass` options selectable via Helm `runtime.runtimeClassName`:

| RuntimeClass | Handler | Fixed Pod Overhead (`cpu` / `memory`) | Node Selector |
| :--- | :--- | :--- | :--- |
| `kata-qemu` | `kata-qemu` | `250m` / `160Mi` | `katacontainers.io/kata-runtime: "true"` |
| `kata-clh` | `kata-clh` | `250m` / `128Mi` | `katacontainers.io/kata-runtime: "true"` |

## Step 3: Provision Raw `Block` CSI Storage

CubePod requires a CSI driver supporting `volumeMode: Block` and ideally fast snapshot/CoW cloning for `fork`. Pick either **Longhorn V2 (SPDK)** or **OpenEBS LVM-LocalPV**.

### Option A: Longhorn V2 (SPDK NVMe-oF + Fast Clones)

Longhorn V2 runs an SPDK user-space storage engine (`v2DataEngine`) capable of fast thin provisioning and copy-on-write cloning. Scripts under `deploy/k8s/longhorn-v2/` automate single-node or multi-node bring-up:

```bash
bash deploy/k8s/longhorn-v2/install.sh
```

What `prep-node.sh` and `install.sh` configure:

1. **Kernel modules & loopback block backing (`prep-node.sh`)**:
   - Loads `nvme-tcp`, `nvme-fabrics`, `uio`, `uio_pci_generic`, and `vfio-pci`.
   - Creates a sparse backing file at `$CUBEPOD_LONGHORN_IMG` (default `/storage/cubepod/longhorn-v2.img`, size `80G`), attaches it via `losetup --direct-io=on`, symlinks `/dev/cubepod/longhorn-v2`, installs `cubepod-longhorn-loop.service`, and reserves `2Mi` hugepages (`CUBEPOD_HUGEPAGES`, default `1024`).
2. **Cluster preparation & Helm installation (`install.sh`)**:
   - Labels the target node `cubepod.io/longhorn-v2=true` and executes the `cubepod-longhorn-v2-prep` job (`node-prep-job.yaml`).
   - Optionally restarts `kubelet` if `CUBEPOD_RESTART_KUBELET=1` is set so kubelet recognizes hugepages immediately.
   - Installs Helm chart `longhorn/longhorn` (`--version 1.8.2`) into namespace `longhorn-system` using `deploy/k8s/longhorn-v2/values.yaml` (`v1DataEngine: false`, `v2DataEngine: true`, `v2DataEngineCPUMask: "0x1"`, `v2DataEngineGuaranteedInstanceManagerCPU: 1000`).
   - Patches `nodes.longhorn.io/<node>` with a `diskType: block` disk tagged `cubepod-v2` and applies `deploy/k8s/longhorn-v2/storageclass.yaml`:

| Field | Value in `storageclass.yaml` |
| :--- | :--- |
| `metadata.name` | `longhorn-v2-block-thin` |
| `provisioner` | `driver.longhorn.io` |
| `parameters.numberOfReplicas` | `"1"` |
| `parameters.dataEngine` | `v2` |
| `parameters.diskSelector` | `cubepod-v2` |
| `allowVolumeExpansion` | `true` |
| `volumeBindingMode` | `Immediate` |

### Option B: OpenEBS LVM-LocalPV (Bare NVMe Volume Group)

If your nodes have a dedicated local NVMe device and you prefer local LVM thin/thick provisioning without SPDK:

```bash
# On each worker node with raw disk /dev/nvme1n1:
sudo pvcreate /dev/nvme1n1
sudo vgcreate cubepod-vg /dev/nvme1n1

# Install operator and CubePod StorageClass:
kubectl apply -f deploy/k8s/openebs-lvm-operator.yaml
kubectl apply -f deploy/k8s/cubepod-lvm-sc.yaml
```

`deploy/k8s/cubepod-lvm-sc.yaml` creates `StorageClass` `cubepod-lvm-block` (`provisioner: lvm.csi.openebs.io`, `storage: "lvm"`, `volgroup: "cubepod-vg"`, `volumeBindingMode: Immediate`, `allowVolumeExpansion: true`). Point `storage.storageClassName: "cubepod-lvm-block"` in your Helm values file when using OpenEBS LVM.

## Step 4: Live Cluster Verification & Performance Benchmarks

Before running Kubernetes verification suites, copy `deploy/k8s/env.example` to `deploy/k8s/env.local` and adjust `KUBECONFIG`, storage class, and runtime settings (`Makefile` targets source `deploy/k8s/env.local` automatically).

### Functional E2E & Block Suites

```bash
# Offline unit checks for K8s E2E helpers
go test -race -v ./test/k8s-e2e/...

# Live cluster block CSI & Kata pod lifecycle suite
make test-k8s-block   # alias: make test-k8s-longhorn-v2

# Full live Kubernetes E2E suite
make test-k8s-e2e
```

### Benchmark Suite & Target SLOs

Run `TestK8sPerformanceBenchmark` against your live cluster to profile cold boot, execution latency, archive sync, pause/auto-resume, RootFS reset, CoW fork, and WarmPool claim speeds:

```bash
CUBEPOD_K8S_BENCH=1 \
CUBEPOD_BENCH_ITERATIONS=3 \
CUBEPOD_BENCH_OUT=/tmp/cubepod-kata-benchmark.md \
  go test -v -timeout 20m ./test/k8s-e2e/ -run TestK8sPerformanceBenchmark
```

The benchmark suite tracks the following operations and CubePod SLO targets documented in `deploy/k8s/kata/README.md`:

| Benchmark Operation | Target SLO | What It Measures |
| :--- | :--- | :--- |
| `cold_create` | — | End-to-end cold sandbox pod boot (`PodBox` + PVC bind + Kata + `podd` ready) |
| `exec_foreground_rtt` | — | Foreground command round-trip latency over Gateway → `podd` |
| `archive_sync` | `< 100ms` | Compressed `tar.gz` workspace upload & streaming extraction via `podd` |
| `pause` / `pause_auto_resume` | `< 1500ms` | Pod scale-down followed by transparent wake-up via `POST /connect` or subdomain traffic |
| `reset_rootfs` | — | Incrementing `rootfsGeneration` and clearing OS state while keeping `/workspace` intact |
| `cow_fork` | `< 1500ms` | CSI block snapshot clone into a newly booted child sandbox |
| `warmpool_prewarm` / `warmpool_claim_e2e` | `< 200ms` E2E HTTP (`< 50ms` controller overhead) | Pre-warmed microVM claim latency through the Gateway |

## Next Steps

- Review the [Kubernetes & Helm Deployment](/deployment/kubernetes-helm/) guide to customize controller and gateway replicas.
- Read [Lifecycle, WarmPool & CoW Fork](/concepts/lifecycle-warmpool-fork/) to understand how `PodWarmPool` and `cow_fork` interact under the hood.

---
# Kubernetes & Helm Deployment
URL: https://cubepod.cubeplex.ai/deployment/kubernetes-helm/

For Kubernetes deployments, CubePod is packaged as Helm chart `cubepod` (`version: 0.4.0`, `appVersion: "0.4.0"`) under `deploy/helm/cubepod/`. It installs the Custom Resource Definitions (`PodBox`, `PodTemplate`, `PodWarmPool`), RBAC rules, workload namespace, Control Plane Gateway, Kubernetes Controller, and—when enabled—an isolated rootless BuildKit builder deployment.

For the exhaustive key-by-key schema generated directly from `deploy/helm/cubepod/values.yaml`, see the [Helm Values Reference](/reference/helm-values/) and [CRD Reference](/reference/crds/).

## Prerequisites

- Kubernetes cluster with `kubectl` and `helm` (`v3+`) configured.
- A [Kata Containers runtime and CSI block storage](/deployment/kata-and-block-storage/) provisioner (such as Longhorn V2 SPDK `longhorn-v2-block-thin` or OpenEBS LVM-LocalPV `cubepod-lvm-block`) if running in production microVM mode.

## Quick Install

Install the chart from your local checkout into a control-plane namespace such as `cubepod-system`:

```bash
helm install cubepod ./deploy/helm/cubepod \
  --namespace cubepod-system \
  --create-namespace
```

Helm automatically installs the three CRDs in `deploy/helm/cubepod/crds/` on a fresh `helm install`:

- `cubepod.io_podboxes.yaml`
- `cubepod.io_podtemplates.yaml`
- `cubepod.io_podwarmpools.yaml`

:::note
Helm skips upgrading files inside `crds/` on subsequent `helm upgrade` runs. When upgrading CubePod, apply updated CRD manifests explicitly before running `helm upgrade`:
```bash
kubectl apply -f deploy/helm/cubepod/crds/
```
:::

## Deployed Resources Architecture

```mermaid
flowchart TB
  Gateway["Deployment: cubepod-gateway (default 2 replicas, :8080)"] -->|"/sandboxes, /commands, /files, /panel"| Workloads["Namespace: cubepod-workloads\nPodBox Kata Pods + PVCs"]
  Gateway -->|"Internal HTTP (:8081)"| Controller["Deployment: cubepod-controller (:8081)"]
  Controller -->|"CRD Reconcile (5s syncInterval)"| K8sAPI["Kubernetes API\nPodBox / PodTemplate / PodWarmPool"]
  Controller -->|"TCP :1234 (NetworkPolicy-restricted)"| BuildKit["Deployment: cubepod-buildkit\n(moby/buildkit:rootless, optional)"]
  BuildKit -->|"Persistent cache"| BKCache[("PVC: cubepod-buildkit-cache (20Gi)")]
  Controller -->|"Build context sync"| CtxVol[("PVC: cubepod-template-context (10Gi)")]
```

| Template File | Resources Created | Notes |
| :--- | :--- | :--- |
| `namespace.yaml` | `Namespace` (`controller.workloadNamespace`, default `cubepod-workloads`) | Labeled `cubepod.io/role: workloads` |
| `rbac.yaml` | `ServiceAccount`, `ClusterRole` (`<fullname>-controller`), `ClusterRoleBinding` | Grants CRUD on `pods`, `pods/exec`, `pods/log`, `persistentvolumeclaims`, `events`, `configmaps`, `secrets` and `cubepod.io`/`pod.cubeplex.ai` resources + statuses; read access to `apps` `deployments`/`statefulsets` |
| `gateway-deployment.yaml` | `Deployment` (`gateway.replicaCount`, default `2`) | Serves `/health` liveness (`initialDelaySeconds: 5, periodSeconds: 10`) & readiness (`initialDelaySeconds: 2, periodSeconds: 5`); sets `CUBEPOD_PANEL_SECRET` if configured |
| `controller-deployment.yaml` | `Deployment` (`controller.replicaCount`, forced to `1` when `templateBuild.enabled` is true) | Serves `/livez` and `/healthz`; reconciles on `--sync-interval` (`5s`); mounts `cubepod-template-context` PVC when `templateBuild.enabled` is true |
| `service.yaml` | `<fullname>-gateway` (`:8080`), `<fullname>-controller` (`:8081`) | Both default to `ClusterIP`; `gateway.service.nodePort` supported when switching to `NodePort` |
| `buildkit.yaml` | `Deployment`, `Service` (`:1234`), 2 `PVC`s, `NetworkPolicy` | Rendered only when `templateBuild.enabled: true` |

## Core Production Values

Override defaults in a custom `my-values.yaml` file rather than editing the chart directly:

```yaml
gateway:
  replicaCount: 2
  port: 8080
  panelSecret: "replace-with-random-hmac-secret"
  service:
    type: ClusterIP

runtime:
  runtimeClassName: kata-qemu
  defaultTemplate: cubeplex-ubuntu24-desktop
  poddInjectorImage: ghcr.io/cubeplexai/cubepod-podd:v0.4.0
  defaultSandboxImage: ghcr.io/cubeplexai/cubeplex-sandbox:v0.4.0

storage:
  storageClassName: longhorn-v2-block-thin
  volumeMode: Block
  rootfsSize: "10Gi"
  workspaceSize: "20Gi"

warmPool:
  enabled: true
  replicas: 3

egress:
  enabled: true
  image:
    registry: "ghcr.io"
    repository: "cubeplexai/cubepod-egress"
    tag: "v0.4.0"
  port: 18080
  exchangeUrl: "https://cubeplex-backend.cubeplex.svc:8443/api/v1/internal/egress/exchange"
```

Install or upgrade with your overrides:

```bash
helm upgrade --install cubepod ./deploy/helm/cubepod \
  --namespace cubepod-system \
  --create-namespace \
  -f my-values.yaml
```

### Key Runtime & Storage Defaults

- **Runtime injection (`runtime.poddInjectorImage`)**: Defaults to `ghcr.io/cubeplexai/cubepod-podd:v0.4.0`. Every sandbox pod uses an `initContainer` to copy `podd-init` and `podd` into an `emptyDir` mounted at `/opt/cubepod/bin` so user images remain clean.
- **Dual block PVCs (`storage.*`)**: Defaults to `storageClassName: longhorn-v2-block-thin`, `volumeMode: Block`, `rootfsSize: "10Gi"`, and `workspaceSize: "20Gi"`.
- **WarmPool (`warmPool.*`)**: Enabled by default with `3` pre-warmed replicas so `POST /sandboxes` can claim an already-running microVM sub-second.
- **Zero-Trust Egress (`egress.*`)**: Enabled by default, injecting the `cubepod-egress` sidecar on port `18080` and swapping `cpodref_` placeholders against `egress.exchangeUrl`. See [Zero-Trust Egress](/concepts/zero-trust-egress/).

## Enabling In-Cluster Template Builds (`BuildKit`)

By default, both `featureGates.e2bTemplateAPI` and `templateBuild.enabled` are `false`. Enabling template builds deploys a locked-down `moby/buildkit:rootless` builder pod alongside the controller:

```yaml
featureGates:
  e2bTemplateAPI: true

templateBuild:
  enabled: true
  cacheSize: "20Gi"
  probeTimeout: "120s"
  buildkit:
    image: "moby/buildkit:rootless"
    address: "tcp://cubepod-buildkit.cubepod-system.svc:1234"
    nodeSelector: {}
    # Optional nodeSelector: { role: builder }
  registry:
    url: "ghcr.io/your-org"
    repositoryPrefix: "cubepod-templates"
    pushSecret: "cubepod-buildkit-push"
    pullSecret: "cubepod-buildkit-pull"
```

Operational constraints when `templateBuild.enabled: true`:

1. **Controller replica pinning**: `controller-deployment.yaml` forces controller replicas to `1` because `cubepod-template-context` (`10Gi`) is mounted `ReadWriteOnce` at `/var/lib/cubepod/context`.
2. **Rootless BuildKit security context**: `cubepod-buildkit` runs as `1000:1000` with `--oci-worker-no-process-sandbox`, `seccompProfile: Unconfined`, and `appArmorProfile: Unconfined` so nested `RUN` builds work without root inside the builder container.
3. **Ingress NetworkPolicy**: `cubepod-buildkit-netpol` restricts TCP port `1234` strictly to pods carrying `app.kubernetes.io/component: controller`.
4. **Image push/pull secrets**: Create the Kubernetes Docker registry secrets referenced by `templateBuild.registry.pushSecret` and `pullSecret` in your control-plane and workload namespaces before triggering builds.

See [Templates & Image Builds](/sdks/templates/) for the SDK and CLI workflow.

## Verifying the Deployment

Confirm pods, CRDs, and health probes are green:

```bash
kubectl -n cubepod-system get pods
kubectl get crds | grep cubepod.io
kubectl -n cubepod-system port-forward svc/cubepod-gateway 8080:8080
curl -fsS http://localhost:8080/health
```

## Next Steps

- Prepare worker nodes for Kata Containers and raw block storage in [Kata Containers & Block Storage](/deployment/kata-and-block-storage/).
- Inspect every Helm value in [Helm Values Reference](/reference/helm-values/) and CRD field in [CRD Reference](/reference/crds/).

---
# API Overview
URL: https://cubepod.cubeplex.ai/reference/api-overview/

The CubePod Gateway (`cmd/cubepod-gateway`) exposes an **E2B-compatible superset** HTTP/streaming API documented in `api/openapi/cubepod-v1.yaml` (OpenAPI `3.1.0`, spec version `0.4.0`). All official SDKs ([Python](/sdks/python/), [TypeScript](/sdks/typescript/), [Go & CLI](/sdks/go-and-cli/)) communicate with this Gateway surface.

For interactive schema exploration and copy-paste request testing, open the [Interactive API Reference](/api/) or fetch the raw OpenAPI YAML at [`/openapi.yaml`](/openapi.yaml) (also served live by every running Gateway at `GET /openapi.yaml`). For LLM agents ingesting CubePod documentation, fetch [`/llms.txt`](/llms.txt) or [`/llms-full.txt`](/llms-full.txt).

## Base URL, Authentication & Subdomain Routing

- **Authentication**: Pass an `Authorization: Bearer <token>` header when Gateway auth is configured, or omit for local unauthenticated dev instances.
- **Health & Observability**:
  - `GET /health` — Gateway liveness/readiness JSON.
  - `GET /metrics` — Prometheus metrics.
  - `GET /openapi.yaml` — Serves the canonical OpenAPI 3.1 YAML specification.
- **Subdomain Host Router**: Requests matching the regex `^([0-9]+)-([a-zA-Z0-9_-]+)\.(.*)$` (for example `https://3000-sbx-abc123.sandboxes.example.com/`) extract `port` (`3000`) and `sandboxID` (`sbx-abc123`), automatically resume the sandbox if it is in `Paused` state, and reverse-proxy HTTP or WebSocket traffic directly to `PodIP:<port>` (with built-in local fallbacks for port `49999` `/execute` and port `49983` Connect-RPC).

## Sandbox Lifecycle

| Method & Path | Purpose | Key Query / Body Parameters |
| :--- | :--- | :--- |
| `POST /sandboxes` (`POST /v2/sandboxes`) | Create a sandbox (claiming from WarmPool if available) | `templateID`, `timeout` / `ttlSeconds`, `cpuCount`, `memoryMB`, `envVars` (`cpodref_` supported), `workspacePvcSize`, `metadata` |
| `GET /sandboxes` | List sandboxes | Query filters: `state`, `templateID` |
| `GET /sandboxes/{id}` | Inspect current sandbox status, IPs, generation, and state | Path: `id` |
| `DELETE /sandboxes/{id}` | Destroy sandbox | Query: `deleteVolumes` (`false` retains PVCs; `true` deletes PVCs) |
| `POST /sandboxes/{id}/pause` | Scale compute to zero while preserving `rootfs` and `/workspace` PVCs | Path: `id` |
| `POST /sandboxes/{id}/connect` | Resume a `Paused` sandbox and wait until `podd` is healthy | Optional timeout update |
| `POST /sandboxes/{id}/timeout` | Set/extend sandbox timeout | Body: `{ "timeoutSeconds": <int> }` |
| `POST /sandboxes/{id}/refreshes` | Refresh lease / extend TTL (E2B alias) | Body: `{ "duration": <int> }` |
| `POST /sandboxes/{id}/lease` | Renew sandbox TTL lease | Body: lease duration / TTL |
| `POST /sandboxes/{id}/reset-rootfs` | Increment `rootfsGeneration` to clear OS rootfs while keeping `/workspace` intact | Body: optional `template` / reset options |
| `POST /sandboxes/{id}/fork` | Clone sandbox via CSI snapshot (`cow_fork`) into an independent child sandbox | Optional fork parameters |

## Command Execution, Cursor Logs & SSE Streaming

Every foreground or background process executes inside the guest via the Rust `podd` daemon (`:49983`), which indexes stdout/stderr lines by monotonic cursor for reliable reconnection.

| Method & Path | Purpose | Notes |
| :--- | :--- | :--- |
| `POST /sandboxes/{id}/commands` (`POST /sandboxes/{id}/commands/run`) | Run a command | Supports `cmd`/`command`, `args`, `cwd`, `envs`/`env`, `background`, `timeout`/`timeoutSeconds`, `uid`, `gid` |
| `GET /sandboxes/{id}/commands/{cmdID}/status` | Fetch process status and exit code | Returns `exitCode`, `running`, signal metadata |
| `GET /sandboxes/{id}/commands/{cmdID}/logs` | Fetch incremental log lines | Query: `cursor=<int>`; returns lines + `nextCursor` |
| `GET /sandboxes/{id}/commands/{cmdID}/stream` | Stream output as Server-Sent Events (`text/event-stream`) | Gateway polls `podd` logs every `50ms` and emits live SSE frames until process exit |
| `POST /sandboxes/{id}/commands/{cmdID}/kill` | Terminate a running process | Sends signal to process inside guest |

## Files & Archive Sync

| Method & Path | Purpose | Notes |
| :--- | :--- | :--- |
| `PUT /sandboxes/{id}/files` (`PUT /files`) | Write raw file bytes | Query: `path`, optional `uid`, `gid`, `mode` |
| `GET /sandboxes/{id}/files` (`GET /files`) | Read raw file bytes | Query: `path` |
| `DELETE /sandboxes/{id}/files` (`DELETE /files`) | Remove file or directory | Query: `path` |
| `GET /sandboxes/{id}/files/list` (`GET /files/list`) | List directory entries | Query: `path` |
| `POST /sandboxes/{id}/files/archive-sync` | Stream compressed `tar.gz` workspace updates | Query: `dest` / `destination`, `uid`, `gid`, `remove_paths` / `removePaths`; `podd` validates relative entries and rejects `..` or leading `/` traversal |

:::tip
The direct `/files` and `/files/list` routes resolve the target sandbox via `E2b-Sandbox-Id`, `X-Sandbox-ID`, query params, or the subdomain router host header for E2B `envd` client parity.
:::

## Code Interpreter (`NDJSON` & Persistent Kernels)

CubePod embeds stateful code interpreter execution directly inside `podd` (`crates/podd/src/interpreter.rs`) supporting six kernels: **`python`**, **`bash`**, **`javascript`**, **`typescript`**, **`r`**, and **`java`**.

- **Execute Code**: `POST /sandboxes/{id}/code/execute` (also `POST /sandboxes/{id}/execute` and `POST /execute`).
  - Streams `application/x-ndjson` lines containing `stdout`, `stderr`, `result` (supporting `text`, `png` base64 images, `html`, `json`), `error` (`name`, `value`, `traceback`), and `number_of_executions`.
- **Stateful Context Management**: In-guest `podd` exposes `/contexts` and `/v1/code/contexts` (with Gateway paths at `/sandboxes/{id}/code/contexts` and `/sandboxes/{id}/code/contexts/{contextId}`) to create, inspect, restart, and delete persistent stateful language sessions.

## Desktop & Signed Panel Proxy

For desktop-enabled images (such as `cubeplex-ubuntu24-desktop`), the Gateway coordinates Xvfb/x11vnc/noVNC/Selkies startup and mints short-lived HMAC-signed reverse-proxy URLs:

| Method & Path | Purpose | Notes |
| :--- | :--- | :--- |
| `POST /sandboxes/{id}/desktop/start` | Start display server & desktop session | Validates `resolution` (`^[0-9]{3,5}x[0-9]{3,5}x(16\|24\|32)$`), optional `initialUrl`, `expiresInSeconds`; returns `422 desktop_not_installed` if the image lacks desktop binaries. Aliased under `/v1/sandboxes/{id}/desktop/start` |
| `GET /sandboxes/{id}/desktop/status` | Inspect desktop status (`desktopStatus`, panel URLs) | Also aliased under `/v1/sandboxes/{id}/desktop/status` |
| `POST /sandboxes/{id}/desktop/stop` | Stop desktop services | Also aliased under `/v1/sandboxes/{id}/desktop/stop` |
| `GET /sandboxes/{id}/endpoints/{port}` & `POST /sandboxes/{id}/endpoints/{port}` | Mint or query a signed proxy token for any sandbox TCP/WebSocket port | Token format: `base64url(sandboxID:port:expUnix).hmacSha256Sig` |
| `ANY /panel/{token}/...` | HMAC-verified HTTP, WebSocket, and WebRTC proxy | Strips `/panel/{token}` prefix and proxies to `PodIP:<port>` inside the sandbox |

See [Desktop & Panel Proxy](/concepts/desktop-and-panel-proxy/) for architecture details.

## E2B Connect-RPC Compatibility Endpoints

For drop-in E2B SDK interoperability (`pkg/gateway/connectrpc.go`), the Gateway translates Connect-RPC service calls—whether rooted at `/` (resolved via `E2b-Sandbox-Id`, `X-Sandbox-ID`, query param, or subdomain host) or nested at `/sandboxes/{id}/`:

- **Process Service**:
  - `POST /process.Process/Start`
  - `POST /process.Process/SendSignal`
  - `POST /process.Process/Connect`
  - `POST /process.Process/List`
- **Filesystem Service**:
  - `POST /filesystem.Filesystem/Read`
  - `POST /filesystem.Filesystem/Write`
  - `POST /filesystem.Filesystem/List`
  - `POST /filesystem.Filesystem/ListDir`
  - `POST /filesystem.Filesystem/Stat`
  - `POST /filesystem.Filesystem/Remove`
  - `POST /filesystem.Filesystem/MakeDir`

Both plain `application/json` payloads and framed `application/connect+json` streaming envelopes (`1-byte flag` where `0` = message frame and `2` = end-of-stream + `4-byte big-endian uint32 length`) are handled natively.

## WarmPools

| Method & Path | Purpose |
| :--- | :--- |
| `POST /warmpools` | Create or update a `PodWarmPool` resource with target template and replica count |
| `GET /warmpools` | List all configured WarmPools and ready/available pod counts |

## Template Catalog & Builds (`E2BTemplateAPI`)

When `--e2b-template-api=true` is enabled on the Gateway and Controller, the full template registry and BuildKit build pipeline become available:

| Method & Path | Purpose | Key Headers / Constraints |
| :--- | :--- | :--- |
| `GET /templates` & `GET /v2/templates` | List templates | `/v2/templates` supports cursor pagination returning `X-Next-Token` |
| `POST /templates` & `POST /v2/templates` | Trigger template build | Returns build ID & status |
| `POST /v3/templates` | Idempotent async template build (v3) | Honors `Idempotency-Key`, returns `202 Accepted` |
| `GET /templates/{id}`, `PATCH /templates/{id}`, `PATCH /v2/templates/{id}`, `DELETE /templates/{id}` | Inspect, update (`public`), or delete template | — |
| `GET /templates/aliases/{alias}` | Resolve human alias to template ID & metadata | — |
| `GET /templates/{id}/files/{hash}` & `PUT /templates/{id}/files/{hash}` | Check or upload SHA-256 content-addressed build context tarball | `{hash}` validated against `^[0-9a-f]{64}$` |
| `POST /v2/templates/{id}/builds/{buildID}` | Submit Dockerfile / build step instructions for execution | Supported with local Docker or in-cluster BuildKit |
| `GET /templates/{id}/builds/{buildID}/status` | Inspect build state & `kubeTemplateName` / `imageRef` | — |
| `GET /templates/{id}/builds/{buildID}/logs` | Fetch structured build log stream | — |
| `POST /templates/tags`, `DELETE /templates/tags`, `GET /templates/{id}/tags` | Assign, remove, or inspect template tags | — |

## Internal Zero-Trust Egress Exchange

| Method & Path | Purpose |
| :--- | :--- |
| `POST /internal/v1/egress/exchange` | Called over mTLS by the `cubepod-egress` sidecar to resolve `cpodref_` credential placeholders into real upstream secrets just before outbound transmission |

## Next Steps

- Try the interactive Swagger/Scalar playground at [Interactive API Reference](/api/).
- Explore the Python, TypeScript, and Go client implementations in [Python SDK](/sdks/python/), [TypeScript SDK](/sdks/typescript/), and [Go SDK & CLI](/sdks/go-and-cli/).

---
# Kubernetes CRDs (v1alpha1)
URL: https://cubepod.cubeplex.ai/reference/crds/

> Auto-generated at build time from [`deploy/helm/cubepod/crds/`](https://github.com/cubeplexai/cubepod/tree/main/deploy/helm/cubepod/crds) and [`api/v1alpha1/types.go`](https://github.com/cubeplexai/cubepod/blob/main/api/v1alpha1/types.go).

## `PodBox` (`cubepod.io/v1alpha1`)

- **Resource**: `podboxes.cubepod.io` | **Scope**: `Namespaced` | **Short Names**: `pb`, `pbox`

### PodBox `.spec`

| Field | Type | Required | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| `spec.templateRef` | `string` | No | — | Name of the `PodTemplate` defining runtime class, base OCI image, storage, and egress defaults. |
| `spec.warmPoolRef` | `string` | No | — | Optional `PodWarmPool` name to claim a pre-attached standby MicroVM in `< 50ms`. |
| `spec.desiredState` | `string` | Yes | enum: `Running`, `Paused` | Target sandbox compute state (`Running` or `Paused`). Setting `Paused` deletes the Pod (0 CPU/RAM) while retaining PVCs. |
| `spec.rootfsGeneration` | `integer` | No | — | Incremented monotonically to wipe and re-image the persistent RootFS `upperdir` PVC without touching `/workspace`. |
| `spec.forkFrom` | `object` | No | — | Copy-on-Write parent source to clone both RootFS and Workspace block volumes from. |
| `spec.forkFrom.podBoxName` | `string` | No | — | Name of the source `PodBox` whose dual volumes are cloned via CSI VolumeSnapshot. |
| `spec.lifecycle` | `object` | No | — | Idle auto-pause, paused TTL expiration, and lease lock controls. |
| `spec.lifecycle.idleTimeoutSeconds` | `integer` | No | — | Seconds of inactivity before `cubepod-controller` transitions the sandbox to `Paused`. |
| `spec.lifecycle.pausedTTLSeconds` | `integer` | No | — | Retention window (seconds) for PVCs while `Paused` before garbage collection. |
| `spec.lifecycle.leaseExpiresAt` | `string (date-time)` | No | — | RFC3339 timestamp until which an active agent lease prevents idle auto-pause. |
| `spec.networkPolicy` | `object` | No | — | Zero-Trust outbound firewall rules and `cpodref_` credential bindings. |
| `spec.networkPolicy.defaultAction` | `string` | No | enum: `Allow`, `Deny` | Default egress posture when a destination host matches neither `allowHosts` nor `denyHosts` (`Allow` or `Deny`). |
| `spec.networkPolicy.allowHosts` | `[]string` | No | — | List of permitted destination hostnames or wildcard patterns (e.g., `*.github.com`). |
| `spec.networkPolicy.denyHosts` | `[]string` | No | — | List of blocked destination hostnames or wildcard patterns. |
| `spec.networkPolicy.upstreamProxy` | `string` | No | — | Optional upstream HTTP/HTTPS proxy URL chained behind `cubepod-egress`. |
| `spec.networkPolicy.secretBindings` | `[]object` | No | — | Array of `cpodref_` placeholder bindings swapped by `cubepod-egress` over per-pod mTLS. |
| `spec.networkPolicy.secretBindings[].envName` | `string` | Yes | — | Environment variable name injected inside the MicroVM (holding only the opaque placeholder). |
| `spec.networkPolicy.secretBindings[].placeholder` | `string` | Yes | — | Opaque `cpodref_...` token exposed to guest processes instead of the real credential. |
| `spec.networkPolicy.secretBindings[].allowedHosts` | `[]string` | Yes | — | Destination hostnames permitted to receive the substituted real credential. |
| `spec.networkPolicy.secretBindings[].allowedHeaders` | `[]string` | No | — | Optional HTTP headers allowed for substitution (e.g., `Authorization`, `x-api-key`). |

### PodBox `.status`

| Field | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `status.phase` | `string` | — | Observed `PodBox` phase (`Pending`, `Provisioning`, `Running`, `Pausing`, `Paused`, `Resuming`, `ResettingRootFS`, `Failed`, `Terminated`). |
| `status.podName` | `string` | — | Name of the currently bound Kubernetes Kata Pod (empty when `Paused`). |
| `status.podIP` | `string` | — | Cluster IP of the active sandbox Pod used by `cubepod-gateway` to proxy `podd` (`:49983`) and panel ports. |
| `status.nodeName` | `string` | — | Kubernetes node currently hosting the sandbox Pod. |
| `status.rootfsPVCName` | `string` | — | Bound PersistentVolumeClaim name for the OverlayFS `upperdir` block/filesystem volume. |
| `status.workspacePVCName` | `string` | — | Bound PersistentVolumeClaim name for `/workspace` (`1000:1000`). |
| `status.observedRootfsGeneration` | `integer` | — | Latest `rootfsGeneration` reconciled by the controller. |
| `status.lastActivityAt` | `string (date-time)` | — | Timestamp of last command, file operation, or panel traffic observed by gateway/controller. |
| `status.pausedAt` | `string (date-time)` | — | Timestamp when the sandbox entered `Paused` phase. |
| `status.reason` | `string` | — | Machine-readable reason code for phase transitions or failures. |
| `status.message` | `string` | — | Human-readable status message. |

### `kubectl get podboxes` Columns

| Column | Type | JSONPath |
| :--- | :--- | :--- |
| `Phase` | `string` | `.status.phase` |
| `Desired` | `string` | `.spec.desiredState` |
| `Pod` | `string` | `.status.podName` |
| `Age` | `date` | `.metadata.creationTimestamp` |

## `PodTemplate` (`cubepod.io/v1alpha1`)

- **Resource**: `podtemplates.cubepod.io` | **Scope**: `Namespaced` | **Short Names**: `pt`, `ptemplate`

### PodTemplate `.spec`

| Field | Type | Required | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| `spec.runtimeClassName` | `string` | No | — | Kubernetes `RuntimeClass` for hardware isolation (e.g., `kata-qemu` or `kata-clh`). |
| `spec.image` | `string` | Yes | — | User/workload OCI container image (kept clean; `podd-init` and `podd` are injected via initContainer). |
| `spec.poddImage` | `string` | No | — | Override injector image containing `/opt/cubepod/bin/{podd-init,podd}`. |
| `spec.resources` | `object` | No | — | CPU and memory requests/limits for the sandbox MicroVM. |
| `spec.resources.cpuRequest` | `string` | No | — | Kubernetes CPU request (e.g., `500m`). |
| `spec.resources.cpuLimit` | `string` | No | — | Kubernetes CPU limit (e.g., `2`). |
| `spec.resources.memoryRequest` | `string` | No | — | Kubernetes memory request (e.g., `1Gi`). |
| `spec.resources.memoryLimit` | `string` | No | — | Kubernetes memory limit (e.g., `4Gi`). |
| `spec.storage` | `object` | No | — | CSI storage defaults for the dual `rootfs` and `workspace` PVCs. |
| `spec.storage.storageClassName` | `string` | No | — | CSI StorageClass name supporting `volumeMode: Block` (or `Filesystem`). |
| `spec.storage.rootfsSize` | `string` | No | — | Size of the RootFS `upperdir` PVC (e.g., `10Gi`). |
| `spec.storage.workspaceSize` | `string` | No | — | Size of the `/workspace` PVC (e.g., `20Gi`). |
| `spec.egress` | `object` | No | — | Per-template zero-trust egress sidecar configuration. |
| `spec.egress.enabled` | `boolean` | No | — | Whether `cubepod-egress` sidecar and `nftables` interception are injected. |
| `spec.egress.image` | `string` | No | — | Container image for `cubepod-egress`. |
| `spec.egress.exchangeUrl` | `string` | No | — | Control-plane vault URL queried over per-pod mTLS to exchange `cpodref_` tokens. |
| `spec.names` | `[]string` | No | — | E2B-compatible template aliases and version tags (e.g., `ubuntu:24.04`, `python-data:v1`). |
| `spec.cpuCount` | `integer` | No | — | E2B integer vCPU count view synced with `resources`. |
| `spec.memoryMB` | `integer` | No | — | E2B memory size in MiB synced with `resources`. |
| `spec.diskSizeMB` | `integer` | No | — | E2B disk size in MiB synced with `storage.rootfsSize`. |
| `spec.public` | `boolean` | No | — | Whether the template is visible publicly in the E2B template catalog. |
| `spec.startCmd` | `string` | No | — | Optional command launched by `podd` after `pivot_root` completes. |
| `spec.readyCmd` | `string` | No | — | Readiness probe command run during template build verification and sandbox startup. |
| `spec.runAsUser` | `integer (int64)` | No | — | Numeric UID from OCI `USER` instruction (`nil` defaults to `1000`, `0` preserves root). |
| `spec.runAsGroup` | `integer (int64)` | No | — | Numeric GID when OCI `USER` specifies `<uid>:<gid>`. |
| `spec.runAsUsername` | `string` | No | — | Named user resolved inside the container image when `USER` is non-numeric. |

### PodTemplate `.status`

| Field | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `status.templateID` | `string` | — | Canonical template identifier returned in E2B Template API responses. |
| `status.readyBuildID` | `string` | — | Build ID of the latest successful BuildKit template build. |
| `status.readyImage` | `string` | — | Built OCI image reference currently served by this template. |
| `status.latestBuildID` | `string` | — | Most recent BuildKit build ID initiated for this template. |
| `status.buildStatus` | `string` | — | Latest build status (`waiting`, `building`, `uploaded`, `ready`, `error`). |
| `status.reason` | `string` | — | Machine-readable reason code for phase transitions or failures. |
| `status.failedStep` | `string` | — | Dockerfile/build step that failed if `buildStatus == error`. |
| `status.public` | `boolean` | — | — |
| `status.buildCount` | `integer (int64)` | — | Total build attempts tracked on this template. |
| `status.spawnCount` | `integer (int64)` | — | Total sandboxes spawned from this template. |
| `status.createdAt` | `string` | — | RFC3339 creation timestamp. |
| `status.updatedAt` | `string` | — | RFC3339 last update timestamp. |
| `status.lastSpawnedAt` | `string` | — | RFC3339 timestamp of the last sandbox creation. |
| `status.builds` | `[]object` | — | — |
| `status.builds[].buildID` | `string` | — | — |
| `status.builds[].status` | `string` | — | — |
| `status.builds[].reason` | `string` | — | — |
| `status.builds[].failedStep` | `string` | — | — |
| `status.builds[].createdAt` | `string` | — | — |
| `status.builds[].updatedAt` | `string` | — | — |
| `status.builds[].cpuCount` | `integer (int32)` | — | — |
| `status.builds[].memoryMB` | `integer (int32)` | — | — |

### `kubectl get podtemplates` Columns

| Column | Type | JSONPath |
| :--- | :--- | :--- |
| `Image` | `string` | `.status.readyImage` |
| `Build` | `string` | `.status.buildStatus` |
| `Age` | `date` | `.metadata.creationTimestamp` |

## `PodWarmPool` (`cubepod.io/v1alpha1`)

- **Resource**: `podwarmpools.cubepod.io` | **Scope**: `Namespaced` | **Short Names**: `pwp`, `warmpool`

### PodWarmPool `.spec`

| Field | Type | Required | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| `spec.templateRef` | `string` | Yes | — | Name of the `PodTemplate` defining runtime class, base OCI image, storage, and egress defaults. |
| `spec.replicas` | `integer` | Yes | min: 0 | Target count of pre-formatted, pre-pivoted standby MicroVM Pods kept ready to claim. |

### PodWarmPool `.status`

| Field | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `status.readyReplicas` | `integer` | — | Number of standby Pods that passed `podd` readiness checks. |
| `status.availableReplicas` | `integer` | — | Number of standby Pods immediately available for `< 50ms` sandbox claiming. |

### `kubectl get podwarmpools` Columns

| Column | Type | JSONPath |
| :--- | :--- | :--- |
| `Desired` | `integer` | `.spec.replicas` |
| `Ready` | `integer` | `.status.readyReplicas` |
| `Available` | `integer` | `.status.availableReplicas` |
| `Age` | `date` | `.metadata.creationTimestamp` |

## Inspecting CRDs on a Cluster

```bash
kubectl get crds | grep cubepod.io
kubectl get podboxes,podtemplates,podwarmpools -n cubepod-workloads
```

---
# Helm Chart Values
URL: https://cubepod.cubeplex.ai/reference/helm-values/

> Synced directly from [`deploy/helm/cubepod/values.yaml`](https://github.com/cubeplexai/cubepod/blob/main/deploy/helm/cubepod/values.yaml) (Chart `0.4.0` · App `0.4.0`).

## Parameter Reference

| Key | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `global.imageRegistry` | `string` | `ghcr.io` | — |
| `global.repository` | `string` | `cubeplexai` | — |
| `runtime.runtimeClassName` | `string` | `kata-qemu` | — |
| `runtime.defaultTemplate` | `string` | `cubeplex-ubuntu24-desktop` | — |
| `runtime.poddInjectorImage` | `string` | `ghcr.io/cubeplexai/cubepod-podd:v0.4.0` | Lightweight initContainer image that injects /opt/cubepod/bin/{podd-init,podd} at Pod startup |
| `runtime.defaultSandboxImage` | `string` | `ghcr.io/cubeplexai/cubeplex-sandbox:v0.4.0` | Default workload sandbox image (clean OS/tooling image without podd baked in) |
| `storage.storageClassName` | `string` | `longhorn-v2-block-thin` | — |
| `storage.volumeMode` | `string` | `Block` | "Block" or "Filesystem" |
| `storage.rootfsSize` | `string` | `10Gi` | — |
| `storage.workspaceSize` | `string` | `20Gi` | — |
| `warmPool.enabled` | `boolean` | `true` | — |
| `warmPool.replicas` | `number` | `3` | — |
| `gateway.replicaCount` | `number` | `2` | — |
| `gateway.image.registry` | `string` | `ghcr.io` | — |
| `gateway.image.repository` | `string` | `cubeplexai/cubepod-gateway` | — |
| `gateway.image.tag` | `string` | `v0.4.0` | — |
| `gateway.image.pullPolicy` | `string` | `IfNotPresent` | — |
| `gateway.port` | `number` | `8080` | — |
| `gateway.service.type` | `string` | `ClusterIP` | — |
| `gateway.service.port` | `number` | `8080` | — |
| `gateway.service.nodePort` | `null` | `null` | — |
| `gateway.panelSecret` | `string` | `""` | — |
| `gateway.resources.requests.cpu` | `string` | `100m` | — |
| `gateway.resources.requests.memory` | `string` | `128Mi` | — |
| `gateway.resources.limits.cpu` | `string` | `1000m` | — |
| `gateway.resources.limits.memory` | `string` | `512Mi` | — |
| `controller.replicaCount` | `number` | `1` | — |
| `controller.image.registry` | `string` | `ghcr.io` | — |
| `controller.image.repository` | `string` | `cubeplexai/cubepod-controller` | — |
| `controller.image.tag` | `string` | `v0.4.0` | — |
| `controller.image.pullPolicy` | `string` | `IfNotPresent` | — |
| `controller.healthzPort` | `number` | `8081` | — |
| `controller.workloadNamespace` | `string` | `cubepod-workloads` | — |
| `controller.syncInterval` | `string` | `5s` | — |
| `controller.kubeApi` | `string` | `""` | — |
| `controller.kubeToken` | `string` | `""` | — |
| `controller.resources.requests.cpu` | `string` | `100m` | — |
| `controller.resources.requests.memory` | `string` | `128Mi` | — |
| `controller.resources.limits.cpu` | `string` | `1000m` | — |
| `controller.resources.limits.memory` | `string` | `512Mi` | — |
| `egress.enabled` | `boolean` | `true` | — |
| `egress.image.registry` | `string` | `ghcr.io` | — |
| `egress.image.repository` | `string` | `cubeplexai/cubepod-egress` | — |
| `egress.image.tag` | `string` | `v0.4.0` | — |
| `egress.port` | `number` | `18080` | — |
| `egress.exchangeUrl` | `string` | `https://cubeplex-backend.cubeplex.svc:8443/api/v1/internal/egress/exchange` | — |
| `featureGates.e2bTemplateAPI` | `boolean` | `false` | — |
| `templateBuild.enabled` | `boolean` | `false` | — |
| `templateBuild.buildkit.image` | `string` | `moby/buildkit:rootless` | — |
| `templateBuild.buildkit.address` | `string` | `tcp://cubepod-buildkit.cubepod-system.svc:1234` | — |
| `templateBuild.buildkit.nodeSelector` | `object` | `{}` | — |
| `templateBuild.cacheSize` | `string` | `20Gi` | — |
| `templateBuild.probeTimeout` | `string` | `120s` | — |
| `templateBuild.registry.url` | `string` | `""` | — |
| `templateBuild.registry.pushSecret` | `string` | `cubepod-buildkit-push` | — |
| `templateBuild.registry.pullSecret` | `string` | `cubepod-buildkit-pull` | — |
| `templateBuild.registry.repositoryPrefix` | `string` | `cubepod-templates` | — |

## Default `values.yaml`

```yaml
global:
  imageRegistry: "ghcr.io"
  repository: "cubeplexai"

runtime:
  runtimeClassName: "kata-qemu"
  defaultTemplate: "cubeplex-ubuntu24-desktop"
  # Lightweight initContainer image that injects /opt/cubepod/bin/{podd-init,podd} at Pod startup
  poddInjectorImage: "ghcr.io/cubeplexai/cubepod-podd:v0.4.0"
  # Default workload sandbox image (clean OS/tooling image without podd baked in)
  defaultSandboxImage: "ghcr.io/cubeplexai/cubeplex-sandbox:v0.4.0"

storage:
  # SPDK NVMe-oF Raw Block StorageClass (Longhorn V2 or OpenEBS Mayastor) or Filesystem
  storageClassName: "longhorn-v2-block-thin"
  volumeMode: "Block" # "Block" or "Filesystem"
  rootfsSize: "10Gi"
  workspaceSize: "20Gi"

warmPool:
  enabled: true
  replicas: 3

gateway:
  replicaCount: 2
  image:
    registry: "ghcr.io"
    repository: "cubeplexai/cubepod-gateway"
    tag: "v0.4.0"
    pullPolicy: "IfNotPresent"
  port: 8080
  service:
    type: "ClusterIP"
    port: 8080
    nodePort: null
  panelSecret: ""
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "1000m"
      memory: "512Mi"

controller:
  replicaCount: 1
  image:
    registry: "ghcr.io"
    repository: "cubeplexai/cubepod-controller"
    tag: "v0.4.0"
    pullPolicy: "IfNotPresent"
  healthzPort: 8081
  workloadNamespace: "cubepod-workloads"
  syncInterval: "5s"
  kubeApi: ""
  kubeToken: ""
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "1000m"
      memory: "512Mi"

egress:
  enabled: true
  image:
    registry: "ghcr.io"
    repository: "cubeplexai/cubepod-egress"
    tag: "v0.4.0"
  port: 18080
  exchangeUrl: "https://cubeplex-backend.cubeplex.svc:8443/api/v1/internal/egress/exchange"

featureGates:
  # Turning on changes GET /templates from the wrapped stub to a JSON array
  e2bTemplateAPI: false

templateBuild:
  enabled: false
  buildkit:
    image: "moby/buildkit:rootless"
    address: "tcp://cubepod-buildkit.cubepod-system.svc:1234"
    nodeSelector: {}
  cacheSize: "20Gi"
  probeTimeout: "120s"
  registry:
    url: ""
    pushSecret: "cubepod-buildkit-push"
    pullSecret: "cubepod-buildkit-pull"
    repositoryPrefix: "cubepod-templates"
```

---
# CubePod Enhancement Proposals (CEPs)
URL: https://cubepod.cubeplex.ai/ceps/

CubePod uses **CubePod Enhancement Proposals (CEPs)** modeled after Kubernetes KEPs to specify every kernel/VMM boundary, storage driver, wire protocol, and security invariant before implementation.

> Source of truth: [`docs/enhancements/`](https://github.com/cubeplexai/cubepod/tree/main/docs/enhancements)

| CEP | Title | Status | Area | Milestone |
| :--- | :--- | :--- | :--- | :--- |
| **[CEP-0001](/ceps/0001-in-guest-overlayfs-pivot/)** | In-Guest Persistent OverlayFS Pivot and Loopback Verification (`podd-init`) | `implemented` | `runtime` | `v0.1` |
| **[CEP-0002](/ceps/0002-podd-execution-daemon/)** | In-Guest Execution, Background Process Cursor, and Archive Sync Daemon (`podd`) | `implemented` | `runtime` | `v0.1` |
| **[CEP-0003](/ceps/0003-controller-warmpool-and-fork/)** | Dual-Block-PVC, Pre-Attached WarmPool, and CoW Fork Kubernetes Operator (`cubepod-controller`) | `implemented` | `controller` | `v0.1` |
| **[CEP-0004](/ceps/0004-gateway-and-panel-proxy/)** | Unified E2B-Superset Gateway, Local Loopback Runtime, and Signed Panel Proxy (`cubepod-gateway`) | `implemented` | `gateway` | `v0.1` |
| **[CEP-0005](/ceps/0005-zero-trust-egress-and-sdk/)** | Zero-Trust Egress Secret Injection (`cpodref_` mTLS Exchange) & Python SDK `v0.1.0` | `implemented` | `egress` | `v0.1` |
| **[CEP-0006](/ceps/0006-podd-archive-sync/)** | podd Native Streaming Archive-Sync and Process Output Tail Enhancements | `implemented` | `core` | `—` |
| **[CEP-0007](/ceps/0007-docker-loopback-runtime/)** | Local Docker and Sparse Loopback ext4 Runtime Driver | `implemented` | `core` | `—` |
| **[CEP-0008](/ceps/0008-kube-controller-loop/)** | Kubernetes API Client, CRD Sync Loop, and Background Reap Worker | `implemented` | `core` | `—` |
| **[CEP-0009](/ceps/0009-gateway-egress-sidecar/)** | Gateway Live podd Proxy Engine and Zero-Trust Egress Sidecar Daemon | `implemented` | `core` | `—` |
| **[CEP-0010](/ceps/0010-e2e-integration-suite/)** | End-to-End Real Daemon Integration Suite and CLI Tooling | `implemented` | `core` | `—` |
| **[CEP-0011](/ceps/0011-k8s-dual-storage-and-live-pod-routing/)** | Dual-StorageMode Kubernetes Provisioning (Block + Filesystem), Pod Readiness Polling, and Live Gateway-to-Pod Routing | `implemented` | `core` | `v0.3.0` |
| **[CEP-0012](/ceps/0012-complete-gateway-api-and-openapi/)** | Complete Gateway API Surface and Canonical OpenAPI 3.1 Specification | `implemented` | `core` | `v0.3.0` |
| **[CEP-0013](/ceps/0013-sdk-and-cli-completeness/)** | Full-Featured Python SDK (Sync + Async), Go Client SDK (pkg/client), and cubepod CLI (cmd/cubepod) | `implemented` | `core` | `v0.3.0` |
| **[CEP-0014](/ceps/0014-helm-dockerfiles-and-ci/)** | Production Helm Chart, CRD Manifests, Multi-Component Dockerfiles, and GitHub Actions CI/CD | `implemented` | `core` | `v0.3.0` |
| **[CEP-0015](/ceps/0015-k8s-cluster-live-e2e/)** | Real Kubernetes Cluster (kubectl) Deployment and Live End-to-End Verification Suite | `implemented` | `core` | `v0.3.0` |
| **[CEP-0016](/ceps/0016-k8s-block-csi-and-overlayfs-live-e2e/)** | OpenEBS LVM-LocalPV Block CSI Provisioning and Live In-Guest OverlayFS Pivot Verification | `implemented` | `core` | `v0.3.1` |
| **[CEP-0017](/ceps/0017-longhorn-v2-block-verification/)** | Longhorn V2 SPDK Block CSI Deployment and Live volumeMode Block Verification | `implemented` | `storage` | `v0.3.1` |
| **[CEP-0018](/ceps/0018-e2b-protocol-compatibility/)** | E2B Drop-in Protocol Compatibility and SDK Interoperability Specification | `implemented` | `gateway` | `v0.3.1` |
| **[CEP-0019](/ceps/0019-e2b-template-api/)** | E2B-Compatible Template Catalog and OCI Image Builds | `implemented` | `gateway` | `v0.4.0` |
| **[CEP-0020](/ceps/0020-transparent-zero-trust-egress/)** | Transparent Zero-Trust Egress Interception, Selective HTTPS MITM, and Per-Pod mTLS Secret Lifecycle | `implemented` | `egress` | `v0.4.0` |
| **[CEP-0021](/ceps/0021-interactive-desktop-and-panel-stack/)** | Interactive Desktop & Browser GUI Stack with Lazy Activation and Panel Streaming | `implemented` | `runtime` | `v0.4.0` |
| **[CEP-0022](/ceps/0022-cow-fork-and-stateless-ha-gateway/)** | Crash-Consistent Multi-Generation CoW Fork and Stateless Multi-Replica Gateway HA | `implemented` | `controller` | `v0.4.0` |