Architecture

K8E runs a full Kubernetes control plane with a purpose-built SandboxMatrix Controller that manages isolated agent workloads across worker nodes.

High-Level View

┌─────────────────────────────────────────────────────────────────┐
│                          K8E CLUSTER                            │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                CONTROL PLANE (Server Node)              │   │
│   │  ┌──────────────┐  ┌─────────────┐  ┌──────────┐       │   │
│   │  │  API Server  │  │  Scheduler  │  │  Tandem  │       │   │
│   │  └──────────────┘  └─────────────┘  └──────────┘       │   │
│   │  ┌──────────────────┐  ┌──────────────────────────────┐ │   │
│   │  │  Controller Mgr  │  │  SandboxMatrix Controller    │ │   │
│   │  └──────────────────┘  └──────────────────────────────┘ │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                 ┌────────────┴────────────┐                     │
│   ┌─────────────▼───────────┐  ┌──────────▼──────────────┐     │
│   │      WORKER NODE        │  │      WORKER NODE        │     │
│   │  ┌─────────────────┐    │  │  ┌─────────────────┐    │     │
│   │  │  sandbox-matrix │    │  │  │  sandbox-matrix │    │     │
│   │  │  grpc-gateway   │    │  │  │  grpc-gateway   │    │     │
│   │  │  :50051 (TLS)   │    │  │  │  :50051 (TLS)   │    │     │
│   │  └────────┬────────┘    │  │  └────────┬────────┘    │     │
│   │           │             │  │           │             │     │
│   │  ┌────────▼────────┐    │  │  ┌────────▼────────┐    │     │
│   │  │  Isolated Pods  │    │  │  │  Isolated Pods  │    │     │
│   │  │ gVisor/Kata/FC  │    │  │  │ gVisor/Kata/FC  │    │     │
│   │  └─────────────────┘    │  │  └─────────────────┘    │     │
│   │  Cilium CNI (eBPF)      │  │  Cilium CNI (eBPF)      │     │
│   └─────────────────────────┘  └─────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │  gRPC (TLS)
┌────────┴────────┐
│  k8e-sandbox-cli    │  ← CLI commands
└────────┬────────┘
         │  gRPC (TLS)
         ▼
│  AI Agent       │  (claude code / codex / pi)
└─────────────────┘

Key Components

Control Plane (Server Node): API Server, Scheduler, Tandem (rqlite-backed etcd v3 compatibility layer), Controller Manager, and the SandboxMatrix Controller.
Worker Nodes: run the sandbox-matrix gRPC gateway (:50051, TLS) and isolated pods (gVisor/Kata/Firecracker) over Cilium eBPF networking.
Clients: AI agents (Claude Code / Codex / Pi) connect through k8e-sandbox-cli over gRPC (TLS).

See Components for the full component table.