xiaods/k8e

What is K8E?

K8E (pronounced k‑eight‑e) is an open‑source sandbox platform for AI agents. It packages everything needed to run untrusted code generated by autonomous agents (Claude Code, Codex, Pi, etc.) inside isolated containers or micro‑VMs. The whole system is delivered as a single binary under 100 MB that can turn any Linux host into a secure, multi‑tenant execution matrix.

Core ideas

Agent isolation – each AI‑driven workload runs in its own sandbox (gVisor, Kata Containers, or Firecracker) with strict CPU/memory limits.
Zero‑trust between agents – network policies, eBPF‑enforced egress rules, and per‑session workspaces prevent one agent from affecting another.
Fast start‑up – a warm‑pool of pre‑booted pods lets a new session be claimed in sub‑500 ms.
E2B‑compatible API – the gateway exposes a gRPC/mTLS endpoint that matches the Elastic Engine for Bots (E2B) API, so existing LLM‑agent toolkits can talk to it without changes.
One‑click install – a tiny install script (curl … | sh -) sets up the binary, a minimal Kubernetes‑style control plane, and the sandbox runtime in ~60 seconds.

Architecture at a glance

AI Agent (Claude Code / Codex / Pi) ──► k8e‑sandbox‑cli (gRPC over mTLS)
                                            │
                                            ▼
                                   Sandbox Gateway (E2B‑compatible)
                                            │
               ┌────────────────────────────┼─────────────────────────────┐
               │                            │                             │
        Session manager                Metrics & Events               Warm‑pool
               │                            │                             │
               ▼                            ▼                             ▼
   ┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
   │ Sandbox pod (gVisor│   │ Sandbox pod (Kata   │   │ Pre‑booted pod ready│
   │ / Kata / Firecracker)│   │ / Firecracker)      │   │ to be claimed        │
   └─────────────────────┘   └─────────────────────┘   └─────────────────────┘

Sandbox Gateway – a single gRPC server that handles session lifecycle, file I/O, PTY terminals, command execution, snapshotting, and exposure of services.
Isolation runtimes – pluggable RuntimeClasses: gVisor (userspace kernel, ~10 ms boot), Kata Containers (VM‑backed, ~500 ms), Firecracker (micro‑VM, ~125 ms).
Cilium – the default CNI provides eBPF‑enforced NetworkPolicy enforcement and per‑session egress whitelists.
Warm‑pool controller – keeps a configurable number of pre‑started sandbox pods so new sessions start in < 500 ms.

Main components

Component	What it does
Sandbox Gateway	gRPC + mTLS entry point; implements E2B‑compatible API for sessions, exec, files, PTY, snapshots, and metrics.
Isolation runtimes	gVisor, Kata Containers, Firecracker – chosen at pod creation via `RuntimeClass`.
Cilium (eBPF)	Enforces Kubernetes `NetworkPolicy` and per‑session egress (`allowed_hosts`).
Warm‑pool controller	Maintains a pool of ready sandbox pods; auto‑scales based on demand.
k8e‑sandbox‑cli	Stand‑alone client (~44 MB) that agents use to create sessions, run code, read/write files, and manage snapshots.
API‑key service	Generates short‑lived keys for agents; keys are used for mTLS authentication.

Getting started (quick‑start)

# 1. Install a sandbox runtime – gVisor is the default and needs no KVM.
ARCH=$(uname -m)
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
wget ${URL}/runsc ${URL}/runsc.sha512 \
     ${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
sha512sum -c runsc.sha512 -c containerd-shim-runsc-v1.sha512
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/

# 2. Install K8E (single binary, <100 MB)
curl -sfL https://k8e.sh/install.sh | sh -

# 3. Verify the service
k8e-sandbox-cli status
k8e-sandbox-cli run 'echo hello from the sandbox'

The install script sets up a minimal control plane, starts the gateway, and creates a warm‑pool of sandbox pods.

Using the sandbox from an AI agent

Create an API key on the server:

k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"k8e-abc123..."}

Download the client for your OS (≈44 MB) and make it executable.

Connect (installs the /k8e-sandbox skill into the agent):

./k8e-sandbox-cli --endpoint <host>:50051 \
    --apikey k8e-abc123... connect

Run code – the agent can now issue commands like:
```
k8e-sandbox-cli run "print('hello')" --lang python
```
The CLI automatically creates a session, streams the command into an isolated pod, and returns the output.

Supported agents listed in the README are Claude Code, Codex, and Pi.

Key features for AI‑agent workloads

Secure isolation – choose between lightweight (gVisor) and stronger VM‑based runtimes.
Resource quotas – per‑session CPU/memory caps to avoid runaway costs.
Ephemeral workspaces – each session gets a fresh filesystem that is auto‑cleaned.
Content‑addressed snapshots – fast incremental restores via SHA‑256 CAS layerstore.
Exec transcripts & logs – resumable command logs for debugging.
Observability – Prometheus metrics and an NDJSON event stream.
Sub‑agent reuse – child agents can share the parent pod’s workspace while remaining isolated.
CLI catalog – machine‑readable command description for SDK generation.

When to use K8E

You are building autonomous AI agents that generate and execute code on‑the‑fly.
You need strong isolation (prevent malicious or buggy agent code from affecting the host or other agents).
You want fast, on‑demand execution without provisioning a full VM each time.
You prefer a self‑hosted, single‑binary solution rather than a large cloud‑managed service.

License & community

License: Apache 2.0
Stars / releases: actively maintained with versioned releases; binary available for x86_64, ARM64, and RISC‑V.
Contributions are welcomed via the usual GitHub pull‑request workflow.

TL;DR

K8E is a compact, self‑hosted sandbox matrix that lets you run untrusted AI‑agent code safely at scale. Install a runtime (gVisor is easiest), run the one‑line installer, create an API key, and use the k8e-sandbox-cli binary to let your LLM agents execute code inside isolated pods with sub‑second start‑up, strict resource limits, and built‑in observability.