README.md

k8e.sh — Open Source Agentic AI Sandbox Matrix. A CNCF-conformant Kubernetes distribution in a single binary under 100MB, purpose-built for secure, isolated AI agent execution at scale. Up and running in 60 seconds. Inspired by K3s.

curl -sfL https://k8e.sh/install.sh | sh -

That's it. Your agentic sandbox matrix is ready. 🤖

📖 Table of Contents

🤖 What is K8E?

K8E is the Open Source Agentic AI Sandbox Matrix — a Kubernetes-native platform for running secure, isolated AI agent workloads at scale, packaged as a single binary under 100MB.

As autonomous AI agents increasingly generate and execute untrusted code, robust sandboxing infrastructure is no longer optional. K8E ships everything needed to spin up a production-grade cluster in under 60 seconds, with first-class primitives for agent isolation, resource governance, and ephemeral execution environments — purpose-built for the AI era.

🔒 One cluster. Many agents. Zero trust between them.

Sandbox Capabilities

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          K8E CLUSTER                            │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                CONTROL PLANE (Server Node)              │   │
│   │  ┌──────────────┐  ┌─────────────┐  ┌──────────┐       │   │
│   │  │  API Server  │  │  Scheduler  │  │   etcd   │       │   │
│   │  └──────────────┘  └─────────────┘  └──────────┘       │   │
│   │  ┌──────────────────┐  ┌──────────────────────────────┐ │   │
│   │  │  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)
└─────────────────┘

⚙️ Components

🚀 Quick Start

Step 1 — Install a Sandbox Runtime (recommended: before K8E)

Install the runtime shim before K8E so it is auto-detected on first startup. gVisor is recommended — no KVM required.

curl -fsSL https://gvisor.dev/archive.key | gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \
  https://storage.googleapis.com/gvisor/releases release main" \
  > /etc/apt/sources.list.d/gvisor.list
apt-get update && apt-get install -y runsc

K8E detects runsc at startup and automatically injects the gVisor stanza into its containerd config (/var/lib/k8e/agent/etc/containerd/config.toml). Do not run runsc install — K8E manages its own containerd configuration.

Need stronger isolation? See Sandbox Runtime Setup for Kata Containers and Firecracker.

Step 2 — Install K8E

curl -sfL https://k8e.sh/install.sh | sh -

Step 3 — Verify Cluster

export KUBECONFIG=/etc/k8e/k8e.yaml
kubectl get nodes
kubectl get runtimeclass              # should show: gvisor
kubectl -n sandbox-matrix get pods   # Sandbox Matrix starts automatically

Step 4 — Download Sandbox CLI & Connect Your AI Agent

Download the standalone sandbox CLI, authenticate, and install the skill into your agent:

# Download sandbox CLI (~44MB)
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# Create an API key on the server
k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"k8e-abc123..."}

# Authenticate and obtain an mTLS client certificate
./k8e-sandbox-cli-linux-amd64 --endpoint <server-ip>:50051 --apikey k8e-abc123... login

# Install the skill
./k8e-sandbox-cli-linux-amd64 install-skill all

Local usage: If you're on the same machine as the K8E server, the CLI auto-discovers TLS certs and no login is needed — skip straight to install-skill.

Platform binaries: k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64}

Then ask your agent naturally:

"Run this Python snippet in a sandbox"

The agent executes k8e-sandbox-cli run automatically — no session management needed.

Supported agents: claude code, codex, pi.

🔒 Sandbox Runtime Setup

K8E auto-detects installed runtimes and registers the corresponding RuntimeClass. Choose based on your isolation requirements:

gVisor — Recommended Default

curl -fsSL https://gvisor.dev/archive.key | gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \
  https://storage.googleapis.com/gvisor/releases release main" \
  > /etc/apt/sources.list.d/gvisor.list
apt-get update && apt-get install -y runsc

Do not run runsc install — K8E manages its own containerd config at /var/lib/k8e/agent/etc/containerd/config.toml and auto-injects the gVisor stanza on startup.

### Kata Containers

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) install-packages"
kata-runtime check

Firecracker (requires /dev/kvm)

ls /dev/kvm   # verify KVM is available

# Install firecracker-containerd shim + devmapper snapshotter
# See: https://github.com/firecracker-microvm/firecracker-containerd
mkdir -p /var/lib/firecracker-containerd/runtime
# Place hello-vmlinux.bin and default-rootfs.img here

Apply Changes

Install runtimes before starting K8E for zero-restart setup. If K8E is already running, restart it after installing a new runtime shim:

systemctl restart k8e
kubectl get runtimeclass
# NAME          HANDLER       AGE
# gvisor        runsc         10s
# kata          kata-qemu     10s
# firecracker   firecracker   10s   ← only if /dev/kvm present

🤖 Sandbox CLI

k8e-sandbox-cli is a standalone binary (~44MB) that gives AI agents direct access to K8E sandbox infrastructure — no server install needed.

AI Agent (claude code / codex / pi)
    │  shell command
    ▼
k8e-sandbox-cli run "print('hello')" --lang python
    │  gRPC (TLS)
    ▼
sandbox-grpc-gateway:50051
    │
    ▼
Isolated Pod (gVisor / Kata / Firecracker)

Install the Skill

On the server, create an API key for secure remote access:

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

On the client, download the standalone CLI, log in, and install the skill:

# 1. Download the platform-specific binary (~44MB)
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# 2. Authenticate and obtain an mTLS client certificate
#    Note: --endpoint and --apikey are global flags, placed before the subcommand
./k8e-sandbox-cli-linux-amd64 --endpoint <server-ip>:50051 --apikey k8e-abc123... login

# 3. Install the skill
./k8e-sandbox-cli-linux-amd64 install-skill all

Platform binaries: k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64}

Then ask your agent naturally:

"Run this Python snippet in a sandbox"

The agent executes k8e-sandbox-cli run automatically — no session management needed.

Available Commands

See skills/k8e-sandbox/SKILL.md for full usage examples.

Quick Examples

# Run Python code (auto-creates session)
k8e-sandbox-cli run "print('hello')" --lang python

# Shell command (default lang=bash)
k8e-sandbox-cli run "ls -la /workspace"

# TypeScript — type annotations run via tsx
k8e-sandbox-cli run "const nums: number[] = [1, 2, 3]; console.log(nums.reduce((a, b) => a + b, 0))" --lang ts

# Multi-line TypeScript via stdin (interfaces, async/await)
k8e-sandbox-cli run --lang ts <<'EOF'
interface User { name: string; age: number }

async function oldest(users: User[]): Promise<User> {
  return users.reduce((a, b) => (a.age > b.age ? a : b));
}

const users: User[] = [{ name: "Ada", age: 36 }, { name: "Linus", age: 54 }];
oldest(users).then((u) => console.log(`Oldest: ${u.name} (${u.age})`));
EOF

# Multi-line via stdin
k8e-sandbox-cli run --lang python <<'EOF'
for i in range(10):
    print(i)
EOF

# Default egress: pypi.org, files.pythonhosted.org, registry.npmjs.org,
#   objects.githubusercontent.com, github.com, raw.githubusercontent.com
SID=$(k8e-sandbox-cli create | jq -r .session_id)
k8e-sandbox-cli write $SID /workspace/script.py <<'PYEOF'
import pandas as pd
print(pd.__version__)
PYEOF
k8e-sandbox-cli run "pip install pandas" --session-id $SID
k8e-sandbox-cli run "python3 /workspace/script.py" --session-id $SID

# Create session with custom runtime and egress
SID=$(k8e-sandbox-cli create --runtime firecracker --allowed-hosts pypi.org,github.com | jq -r .session_id)

# Clone git repo at session creation
SID=$(k8e-sandbox-cli create --git-repo https://github.com/user/repo.git --git-ref main | jq -r .session_id)

# Stream long-running output
k8e-sandbox-cli run "python3 train.py" --session-id $SID --raw

# Tenant-based cross-process session reuse
k8e-sandbox-cli run "echo hello" --tenant my-project

Configuration Overrides

The CLI auto-discovers the local cluster via TLS. For remote clusters, use k8e-sandbox-cli login once to set up mTLS credentials. Override when needed:

# Remote cluster: log in once (creates ~/.k8e/sandbox/{client.crt,client.key,ca.crt})
k8e-sandbox-cli --endpoint 10.0.0.1:50051 --apikey k8e-abc123... login

# After login, subsequent commands work without --apikey:
k8e-sandbox-cli run "echo hello"

# Or via environment variables:
K8E_SANDBOX_ENDPOINT=10.0.0.1:50051 K8E_SANDBOX_APIKEY=k8e-abc123... k8e-sandbox-cli login

# Override endpoint per-command:
K8E_SANDBOX_ENDPOINT=10.0.0.2:50051 k8e-sandbox-cli run "echo hello"

🖥️ Advanced Installation

Add a Worker Node

# Get token from server node
cat /var/lib/k8e/server/node-token

# On worker machine
curl -sfL https://k8e.sh/install.sh | \
  K8E_TOKEN=<token> \
  K8E_URL=https://<server-ip>:6443 \
  INSTALL_K8E_EXEC="agent" \
  sh -

Disable Sandbox Matrix

curl -sfL https://k8e.sh/install.sh | INSTALL_K8E_EXEC="server --disable-sandbox-matrix" sh -

Key Environment Variables

K8E_TOKEN=<secret>              # cluster join token
K8E_URL=https://<server>:6443   # server URL (agent nodes)
K8E_KUBECONFIG_OUTPUT=<path>    # kubeconfig output path

🆚 K8E vs The Alternatives

🤝 Contributing

git clone https://github.com/<your-username>/k8e.git && cd k8e
git checkout -b feat/my-feature
make && make test
git push origin feat/my-feature

• 🐛 Bug Reports
• 💡 Feature Requests
• 🔍 Open PRs

🛡️ Security

Report vulnerabilities via GitHub Security Advisories. Do not open public issues for security bugs.

📄 License

Apache License 2.0 — see LICENSE.

🙏 Acknowledgments

k8e.sh — Open Source Agentic AI Sandbox Matrix

If K8E powers your agents, give us a ⭐ — it means the world to us!