GitHub - xiaods/k8e: k8e.sh - OpenSource Agentic AI Sandbox Matrix

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

#	Section
1	🤖 What is K8E?
2	🏗️ Architecture
3	⚙️ Components
4	🚀 Quick Start
5	🔒 Sandbox Runtime Setup
6	🤖 Sandbox CLI Skill
7	🐍 Python Client SDK
8	🟦 TypeScript Client SDK
9	🖥️ Advanced Installation
9	🆚 K8E vs Others
9	🤝 Contributing
10	🙏 Acknowledgments

🤖 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

Capability	Description
🔒 Hardware Isolation	Pluggable runtimes: gVisor (default), Kata Containers, Firecracker microVM
🌐 Network Policies	Cilium eBPF `toFQDNs` egress control — per-session, no proxy process needed
⚖️ Resource Quotas	CPU/memory caps per agent session to prevent runaway costs
🗑️ Ephemeral Workspaces	Auto-cleanup after agent session ends
🧠 Warm Pool	Pre-booted sandbox pods for sub-500ms session claim latency
🤝 agent-sandbox compatible	Works with `kubernetes-sigs/agent-sandbox`
🔄 SKILL + CLI	AI agents (codex, claude, pi, openclaw) connect via `k8e sandbox` CLI commands

🏗️ 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 commands
└────────┬────────┘
         │  gRPC (TLS)
         ▼
│  AI Agent       │  (codex / claude / pi / openclaw)
└─────────────────┘

⚙️ Components

Component	Version	Purpose
☸️ Kubernetes	v1.35.x	Core orchestration engine
🔷 Cilium	Latest	eBPF networking & per-session egress policy
📦 Containerd	v1.7.x	Container runtime
🔑 etcd	v3.5.x	Distributed key-value store
🌐 CoreDNS	v1.11.x	Cluster DNS
⚓ Helm Controller	v0.16.x	GitOps & chart management
📈 Metrics Server	v0.7.x	Resource metrics
💾 Local Path Provisioner	v0.0.30	Persistent storage
🛡️ gVisor / Kata / Firecracker	—	Pluggable sandbox isolation runtimes
🤖 Sandbox CLI	built-in	`k8e sandbox` — agent tool commands

🚀 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 — Connect Your AI Agent

Install the K8E sandbox skill into your AI agent:

k8e sandbox-install-skill all   # installs skill files for all supported agents

Then ask your agent naturally:

"Run this Python snippet in a sandbox"

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

Supported agents: codex, claude, pi, openclaw.

🔒 Sandbox Runtime Setup

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

Runtime	Isolation	Requirement	Boot time
gVisor	Syscall interception (userspace kernel)	None	~10ms
Kata Containers	VM-backed (QEMU)	Nested virt or bare metal	~500ms
Firecracker	Hardware microVM (KVM)	`/dev/kvm`	~125ms

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 Skill

k8e sandbox is a built-in CLI command group that gives AI agents direct access to K8E's sandbox infrastructure — no MCP server, no extra processes, no manual endpoint config.

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

Install the Skill

sandbox-install-skill copies skill files to the agent's skills directory:

# All supported agents at once
k8e sandbox-install-skill all

# Or per agent
k8e sandbox-install-skill claude    # Skills → ~/.claude/skills/k8e-sandbox/
k8e sandbox-install-skill openclaw  # Skills → ~/.openclaw/skills/k8e-sandbox/
k8e sandbox-install-skill kiro      # Skills → .kiro/skills/k8e-sandbox/
k8e sandbox-install-skill gemini    # Skills → ~/.gemini/skills/k8e-sandbox/

Available Commands

Command	Description
`k8e sandbox run <code>`	Run code or shell command (auto-manages session)
`k8e sandbox status`	Check sandbox service and current session
`k8e sandbox create`	Create a new session (custom runtime, egress)
`k8e sandbox destroy <sid>`	Destroy a session
`k8e sandbox write <sid> <path>`	Write file to /workspace (content via stdin)
`k8e sandbox read <sid> <path>`	Read file from /workspace
`k8e sandbox list <sid>`	List files in /workspace
`k8e sandbox subagent <parent-sid>`	Spawn child sandbox (max depth 1)
`k8e sandbox confirm <sid> <action>`	Gate irreversible action on human approval
`k8e sandbox snapshot save <sid> <name>`	Save workspace as named snapshot
`k8e sandbox snapshot restore <name>`	Create new session from saved snapshot
`k8e sandbox snapshot list`	List saved snapshots

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

Quick Examples

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

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

# Write a script then execute
k8e sandbox write $SID /workspace/script.py <<'EOF'
import pandas as pd
print(pd.__version__)
EOF
k8e sandbox run "python3 /workspace/script.py" --session-id $SID

# Create session with custom runtime and egress
k8e sandbox create --runtime firecracker --allowed-hosts pypi.org,github.com

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

# Workspace manifest
k8e sandbox create --manifest workspace.yaml

# Workspace snapshots
k8e sandbox snapshot save $SID my-checkpoint
k8e sandbox snapshot restore my-checkpoint

Configuration Overrides

The CLI auto-discovers the local cluster via TLS. Override when needed:

K8E_SANDBOX_ENDPOINT=10.0.0.1:50051 k8e sandbox run "echo hello"
K8E_SANDBOX_CERT=/path/to/ca.crt k8e sandbox run "echo hello"
k8e sandbox run "echo hello" --tenant my-project

🐍 Python Client SDK

The Python SDK talks directly to the sandbox gRPC gateway — no process spawn, no stdio handshake (~1–5 ms vs ~500 ms for CLI).

Install

python3 -m pip install grpcio grpcio-tools protobuf

Generate gRPC Stubs (once)

python3 -m grpc_tools.protoc -I proto \
  --python_out=sdk/python \
  --grpc_python_out=sdk/python \
  proto/sandbox/v1/sandbox.proto

# make the generated package importable
touch sdk/python/sandbox/__init__.py sdk/python/sandbox/v1/__init__.py

Usage

Run code (session auto-managed):

from sandbox_client import SandboxClient

with SandboxClient() as client:
    result = client.run("print('hello')", language="python")
    print(result.stdout)   # hello
    print(result.exit_code)  # 0

Generate 10 random numbers and compute the average:

from sandbox_client import SandboxClient

code = (
    "import random; nums = [random.randint(1,100) for _ in range(10)]; "
    "print('numbers:', nums); print('average:', sum(nums)/len(nums))"
)

with SandboxClient() as client:
    result = client.run(code, language="python")
    print(result.stdout)
# numbers: [39, 60, 50, 24, 53, 32, 85, 10, 81, 3]
# average: 43.7

Multi-step workflow (shared session):

with SandboxClient() as client:
    client.run("pip install pandas", "bash")   # session created
    result = client.run("python3 analyze.py", "bash")  # same session reused

Explicit session with custom options:

from sandbox_client import sandbox_session

with sandbox_session(runtime_class="kata", allowed_hosts=["github.com"]) as (client, sid):
    client.write_file(sid, "/workspace/main.py", code)
    result = client.exec(sid, "python3 /workspace/main.py")

SDK source: sdk/python/sandbox_client.py

🟦 TypeScript Client SDK

The TypeScript SDK talks directly to the sandbox gRPC gateway — no process spawn, no stdio handshake (~1–5 ms vs ~500 ms for CLI).

Install

npm install @grpc/grpc-js @grpc/proto-loader

Usage

Run code (session auto-managed):

import { SandboxClient } from "./sandbox_client";

const client = new SandboxClient();
const result = await client.run("print('hello')", "python");
console.log(result.stdout);   // hello
await client.close();

Generate 10 random numbers and compute the average:

const client = new SandboxClient();
const code = "import random; nums=[random.randint(1,100) for _ in range(10)]; print('numbers:',nums); print('average:',sum(nums)/len(nums))";
const result = await client.run(code, "python");
console.log(result.stdout);
// numbers: [39, 60, 50, 24, 53, 32, 85, 10, 81, 3]
// average: 43.7
await client.close();

Multi-step workflow (shared session):

const client = new SandboxClient();
await client.run("pip install pandas", "bash");   // session created
const result = await client.run("python3 analyze.py", "bash");  // same session reused
await client.close();

Explicit session with custom options:

const sid = await client.createSession({ runtimeClass: "kata", allowedHosts: ["github.com"] });
await client.writeFile(sid, "/workspace/main.py", code);
const result = await client.exec(sid, "python3 /workspace/main.py");
await client.destroySession(sid);

Streaming output:

for await (const chunk of client.execStream(sid, "python3 train.py")) {
  process.stdout.write(chunk);
}

One-shot helper:

import { sandboxRun } from "./sandbox_client";
const { stdout } = await sandboxRun("echo hello");

SDK source: sdk/typescript/sandbox_client.ts

🖥️ 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

Feature	K8E 🚀	K3s	K8s (vanilla)	MicroK8s
Install time	~60s	~90s	~20min	~5min
Binary size	<100MB	~70MB	~1GB+	~200MB
Agentic Sandbox	✅ Native	❌ No	⚠️ Manual	❌ No
eBPF networking	✅ Cilium	⚠️ Optional	⚠️ Optional	❌ No
Sandbox CLI skill built-in	✅ Yes	❌ No	❌ No	❌ No
HA embedded etcd	✅ Yes	✅ Yes	✅ Yes	⚠️ Limited
CNCF conformant	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Multi-arch	✅ Yes	✅ Yes	✅ Yes	✅ Yes

🤝 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

🛡️ Security

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

📄 License

Apache License 2.0 — see LICENSE.

🙏 Acknowledgments

Project	Contribution
🐄 K3s	Lightweight Kubernetes foundation that inspired K8E
☸️ Kubernetes	The orchestration engine everything is built on
🔷 Cilium	eBPF-powered networking and per-session egress control
🤖 agent-sandbox	Kubernetes-native agent sandboxing primitives
🌐 CNCF	Fostering the open-source cloud native ecosystem

k8e.sh — Open Source Agentic AI Sandbox Matrix

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

Name		Name	Last commit message	Last commit date
Latest commit History 1,304 Commits
.github/workflows		.github/workflows
cmd		cmd
contrib		contrib
docs		docs
hack		hack
manifests		manifests
pkg		pkg
proto/sandbox/v1		proto/sandbox/v1
sandbox		sandbox
sandboxd		sandboxd
sdk		sdk
skills/k8e-sandbox		skills/k8e-sandbox
tests		tests
.deepsource.toml		.deepsource.toml
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.json		.golangci.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
build.zig		build.zig
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

📖 Table of Contents

🤖 What is K8E?

Sandbox Capabilities

🏗️ Architecture

⚙️ Components

🚀 Quick Start

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

Step 2 — Install K8E

Step 3 — Verify Cluster

Step 4 — Connect Your AI Agent

🔒 Sandbox Runtime Setup

gVisor — Recommended Default

Firecracker (requires /dev/kvm)

Apply Changes

🤖 Sandbox CLI Skill

Install the Skill

Available Commands

Quick Examples

Configuration Overrides

🐍 Python Client SDK

Install

Generate gRPC Stubs (once)

Usage

🟦 TypeScript Client SDK

Install

Usage

🖥️ Advanced Installation

Add a Worker Node

Disable Sandbox Matrix

Key Environment Variables

🆚 K8E vs The Alternatives

🤝 Contributing

🛡️ Security

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 88

Contributors

Uh oh!

Languages

Firecracker (requires `/dev/kvm`)