https://github.com/xiaods/k8e

k8e.sh - OpenSource Agentic AI Sandbox Matrix
https://github.com/xiaods/k8e
k8s kubernetes sandbox
Last synced: 4 days ago
JSON representation
k8e.sh - OpenSource Agentic AI Sandbox Matrix
Host: GitHub
URL: https://github.com/xiaods/k8e
Owner: xiaods
License: apache-2.0
Created: 2020-09-03T09:47:24.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2026-05-30T10:00:40.000Z (5 days ago)
Last Synced: 2026-05-30T10:21:29.865Z (5 days ago)
Topics: k8s, kubernetes, sandbox
Language: Go
Homepage: https://k8e.sh
Size: 71.4 MB
Stars: 445
Watchers: 10
Forks: 28
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project

stars - xiaods/k8e - Kubernetes Easy Engine (HarmonyOS / Windows Manager)
awesome-k8s - k8e - The k8e 🚀 (said 'kuber easy') project builds on upstream project K3s as codebase, remove Edge/IoT features and extend enterprise features with best practices. (Kubernetes distributions)
awesome-cloud-native - K8e - Simple Enterprise Kubernetes. (Cluster)
README

          









  







[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://golang.org)

[![Kubernetes](https://img.shields.io/badge/Kubernetes-v1.35-326CE5?style=for-the-badge&logo=kubernetes&logoColor=white)](https://kubernetes.io)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge&logo=apache&logoColor=white)](https://github.com/xiaods/k8e/blob/main/LICENSE)

[![Stars](https://img.shields.io/github/stars/xiaods/k8e?style=for-the-badge&logo=github&color=FFD700)](https://github.com/xiaods/k8e/stargazers)

[![Release](https://img.shields.io/github/v/release/xiaods/k8e?style=for-the-badge&logo=github&color=green)](https://github.com/xiaods/k8e/releases)

[![Arch](https://img.shields.io/badge/Arch-x86__64%20%7C%20ARM64%20%7C%20RISC--V-blueviolet?style=for-the-badge)](https://github.com/xiaods/k8e/releases)




> **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](https://github.com/k3s-io/k3s).




```bash

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?](#-what-is-k8e) |

| 2 | [🏗️ Architecture](#️-architecture) |

| 3 | [⚙️ Components](#️-components) |

| 4 | [🚀 Quick Start](#-quick-start) |

| 5 | [🔒 Sandbox Runtime Setup](#-sandbox-runtime-setup) |

| 6 | [🤖 Sandbox CLI Skill](#-sandbox-cli-skill) |

| 7 | [🐍 Python Client SDK](#-python-client-sdk) |

| 8 | [🟦 TypeScript Client SDK](#-typescript-client-sdk) |

| 9 | [🖥️ Advanced Installation](#️-advanced-installation) |

| 9 | [🆚 K8E vs Others](#-k8e-vs-the-alternatives) |

| 9 | [🤝 Contributing](#-contributing) |

| 10 | [🙏 Acknowledgments](#-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`](https://github.com/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.

```bash

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](#-sandbox-runtime-setup) for Kata Containers and Firecracker.

### Step 2 — Install K8E

```bash

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

```

### Step 3 — Verify Cluster

```bash

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:

```bash

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

```bash

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`)

```bash

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:

```bash

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:

```bash

# 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 ` | 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 ` | Destroy a session |

| `k8e sandbox write  ` | Write file to /workspace (content via stdin) |

| `k8e sandbox read  ` | Read file from /workspace |

| `k8e sandbox list ` | List files in /workspace |

| `k8e sandbox subagent ` | Spawn child sandbox (max depth 1) |

| `k8e sandbox confirm  ` | Gate irreversible action on human approval |

| `k8e sandbox snapshot save  ` | Save workspace as named snapshot |

| `k8e sandbox snapshot restore ` | Create new session from saved snapshot |

| `k8e sandbox snapshot list` | List saved snapshots |


See [skills/k8e-sandbox/SKILL.md](skills/k8e-sandbox/SKILL.md) for full usage examples.

### Quick Examples

```bash

# 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:

```bash

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

```bash

python3 -m pip install grpcio grpcio-tools protobuf

```

### Generate gRPC Stubs (once)

```bash

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):**

```python

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:**

```python

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):**

```python

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:**

```python

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

```bash

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

```

### Usage

**Run code (session auto-managed):**

```typescript

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:**

```typescript

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):**

```typescript

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:**

```typescript

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:**

```typescript

for await (const chunk of client.execStream(sid, "python3 train.py")) {

  process.stdout.write(chunk);

}

```

**One-shot helper:**

```typescript

import { sandboxRun } from "./sandbox_client";

const { stdout } = await sandboxRun("echo hello");

```

> SDK source: `sdk/typescript/sandbox_client.ts`

---

## 🖥️ Advanced Installation

### Add a Worker Node

```bash

# Get token from server node

cat /var/lib/k8e/server/node-token

# On worker machine

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

  K8E_TOKEN= \

  K8E_URL=https://:6443 \

  INSTALL_K8E_EXEC="agent" \

  sh -

```

### Disable Sandbox Matrix

```bash

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

```

### Key Environment Variables

```bash

K8E_TOKEN=              # cluster join token

K8E_URL=https://:6443   # server URL (agent nodes)

K8E_KUBECONFIG_OUTPUT=    # 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

```bash

git clone https://github.com//k8e.git && cd k8e

git checkout -b feat/my-feature

make && make test

git push origin feat/my-feature

```

- 🐛 [Bug Reports](https://github.com/xiaods/k8e/issues/new)

- 💡 [Feature Requests](https://github.com/xiaods/k8e/issues/new)

- 🔍 [Open PRs](https://github.com/xiaods/k8e/pulls)

---

## 🛡️ Security

Report vulnerabilities via [GitHub Security Advisories](https://github.com/xiaods/k8e/security/advisories). Do not open public issues for security bugs.

---

## 📄 License

Apache License 2.0 — see [LICENSE](https://github.com/xiaods/k8e/blob/main/LICENSE).

---

## 🙏 Acknowledgments



| Project | Contribution |

|---|---|

| 🐄 [**K3s**](https://github.com/k3s-io/k3s) | Lightweight Kubernetes foundation that inspired K8E |

| ☸️ [**Kubernetes**](https://github.com/kubernetes/kubernetes) | The orchestration engine everything is built on |

| 🔷 [**Cilium**](https://github.com/cilium/cilium) | eBPF-powered networking and per-session egress control |

| 🤖 [**agent-sandbox**](https://github.com/kubernetes-sigs/agent-sandbox) | Kubernetes-native agent sandboxing primitives |

| 🌐 [**CNCF**](https://cncf.io) | Fostering the open-source cloud native ecosystem |



---





**k8e.sh — Open Source Agentic AI Sandbox Matrix**

[![GitHub](https://img.shields.io/badge/GitHub-xiaods%2Fk8e-181717?style=for-the-badge&logo=github)](https://github.com/xiaods/k8e)

[![Website](https://img.shields.io/badge/Website-k8e.sh-00D4FF?style=for-the-badge&logo=googlechrome&logoColor=white)](https://k8e.sh)

[![Docs](https://img.shields.io/badge/Docs-k8e.sh%2Fdocs-green?style=for-the-badge&logo=gitbook&logoColor=white)](https://k8e.sh/docs/)

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

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/xiaods/k8e

Awesome Lists containing this project

README
