xiaods/k8e
k8e.sh - OpenSource Agentic AI Sandbox Matrix
安装Install
dsh plugin --profile web add github:xiaods/k8e把 xiaods/k8e 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
k8e.sh — Open Source Agentic AI Sandbox Matrix. A single binary under 100MB that turns any Linux host into a secure, isolated execution platform for AI agents — gVisor, Kata, or Firecracker isolation, warm-pool fast starts, and an E2B-compatible API. Up and running in 60 seconds.
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 self-hosted sandbox 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; allowed_hosts enforced via --cilium-dns-proxy (KIP-16 M10) |
| ⚖️ Resource Quotas | CPU/memory caps per agent session to prevent runaway costs |
| 🗑️ Ephemeral Workspaces | Auto-cleanup after agent session ends; per-session workspace isolation for sub-agents (KIP-16 M1) |
| 🧠 Warm Pool | Pre-booted sandbox pods for sub-500ms session claim latency; application-layer readiness handshake, adaptive sizing, per-session background-run caps |
| 📸 Content-Addressed Snapshots | SHA-256 CAS layerstore with zstd compression, chunked multi-layer manifests, incremental --base restore, server-side registry, autosquash (KIP-16 M2) |
| 📜 Exec Transcripts | File-backed, windowed, offset-resumable command transcripts — k8e-sandbox-cli log (KIP-16 M4) |
| 📊 Observability | Prometheus metrics, disk-only NDJSON event stream, process topology — events / ps CLI (KIP-16 M5) |
| 🔄 Sub-agent Reuse | Sub-agents share the parent pod + workspace; isolated reset (KIP-16 M1) |
| 🧾 CLI Catalog | Machine-readable command/flag surface for SDK generation — catalog (KIP-16 M9) |
| 🤝 agent-sandbox compatible | Works with kubernetes-sigs/agent-sandbox |
| 🔄 SKILL + CLI | AI agents (claude code, codex, pi) connect via k8e-sandbox-cli CLI commands |
🏗️ Architecture
AI Agents (Claude Code / Codex / Pi / dsh)
│ k8e-sandbox-cli / plugin tools (gRPC over mTLS)
▼
┌──────────────────────────────────────────────┐
│ SANDBOX GATEWAY │
│ sessions · exec · files · PTY terminals │
│ expose · allow-hosts · snapshots │
│ warm pool · metrics · event stream │
└──────────────┬───────────────────────────────┘
│ claims ready pods from the warm pool
┌───────────▼───────────┐ ┌────────────────┐
│ SANDBOX POD │ │ SANDBOX POD │
│ gVisor / Kata / FC │ … │ (isolated) │
│ agent's code + fs │ │ │
└───────────────────────┘ └────────────────┘
eBPF per-session network policy between all of them
One gateway fronts every operation — session lifecycle, streaming exec,
filesystem, PTY terminals, service exposure (expose), live egress policy
(allow-hosts) and content-addressed snapshots — so agents get one audited
door instead of raw infrastructure access.
⚙️ Components
| Component | Purpose |
|---|---|
| 🚪 Sandbox Gateway | Single gRPC (mTLS) + E2B-compatible HTTP door: sessions, exec, files, PTY terminals, exposure, snapshots |
| 🛡️ gVisor / Kata / Firecracker | Pluggable sandbox isolation runtimes (user-space kernel / lightweight VMs / microVMs) |
| 🔷 Cilium (eBPF) | Per-session network policy & egress control — no proxy process |
| 🧠 Warm Pool Controller | Pre-booted sandbox pods, adaptive sizing, sub-500ms claims |
| 🤖 k8e-sandbox-cli | Standalone agent CLI — connect, run, expose, snapshots (catalog for SDK generation) |
| 🔌 dsh plugin family | @k8e-sandbox/* npm packages — DeepSeek Harness integration with model-surface tools |
🚀 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.
# Download runsc + containerd-shim-runsc-v1 directly from the gVisor release bucket (requires wget)
ARCH=$(uname -m) # x86_64 on most servers, aarch64 on ARM
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 # both must print OK
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1 # verify both installed
K8E detects
runscat startup and automatically injects the gVisor stanza into its containerd config (/var/lib/k8e/agent/etc/containerd/config.toml). Do not runrunsc 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 the Sandbox
k8e-sandbox-cli status # -> {"available": true, ...}
k8e-sandbox-cli run 'echo hello from the sandbox'
(Optionally, with KUBECONFIG=/etc/k8e/k8e.yaml: kubectl -n sandbox-matrix get pods shows the warm-pool pods.)
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) — pick your platform suffix
# k8e-sandbox-cli-linux-amd64 / linux-arm64 / darwin-amd64 / darwin-arm64 / windows-amd64.exe
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64
# Symlink the plain command name to the downloaded file (do not rename)
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli
# Create an API key on the server (default TTL 30 days; use --ttl never for non-expiring)
k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"k8e-abc123...","ttl_days":30,"expires_at":"..."}
# Connect: authenticate (mTLS) + install /k8e-sandbox skill into agent harnesses
./k8e-sandbox-cli --endpoint <server-ip>:50051 --apikey k8e-abc123... connect
# Optional multi-cluster profiles (~/.k8e/sandbox/profiles.yaml — not server /etc/k8e/config.yaml)
# See docs/kip-17-sandbox-cli-profiles-and-apikey-ttl.md
# ./k8e-sandbox-cli --profile prod connect --apikey k8e-...
Local usage: If you're on the same machine as the K8E server, the CLI auto-discovers TLS certs — just run
k8e-sandbox-cli connect.
Platform binaries: k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64} (Windows: k8e-sandbox-cli-windows-amd64.exe, symlink via mklink k8e-sandbox-cli.exe k8e-sandbox-cli-windows-amd64.exe)
One binary, two names: the downloaded
k8e-sandbox-cli-linux-amd64file is thek8e-sandbox-clicommand the skill uses.connectsymlinks it to~/.local/bin/k8e-sandbox-cli(on PATH) and installs the/k8e-sandboxskill into your agent harnesses, so every skill example (k8e-sandbox-cli run ...) is the same file you just downloaded.
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:
| 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
# Download runsc + containerd-shim-runsc-v1 directly from the gVisor release bucket (requires wget)
ARCH=$(uname -m) # x86_64 on most servers, aarch64 on ARM
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 # both must print OK
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1 # verify both installed
Do not run
runsc install— K8E manages its own containerd config at/var/lib/k8e/agent/etc/containerd/config.tomland auto-injects the gVisor stanza on startup.
Kata Containers
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)
# k8e-sandbox-cli-linux-amd64 / linux-arm64 / darwin-amd64 / darwin-arm64 / windows-amd64.exe
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64
# 2. Symlink the plain command name to the downloaded file (do not rename)
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli
# 3. Connect: mTLS auth + install /k8e-sandbox skill into Claude/Codex/Pi
# Note: --endpoint and --apikey are global flags, placed before the subcommand
./k8e-sandbox-cli --endpoint <server-ip>:50051 --apikey k8e-abc123... connect
Platform binaries: k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64} (Windows: k8e-sandbox-cli-windows-amd64.exe, symlink via mklink k8e-sandbox-cli.exe k8e-sandbox-cli-windows-amd64.exe)
One binary, two names: the downloaded
k8e-sandbox-cli-linux-amd64file is thek8e-sandbox-clicommand the skill uses — the symlink is just a plain-name alias to the same file.connectinstalls the/k8e-sandboxskill, so every skill example (k8e-sandbox-cli run ...) is the same file you just downloaded.
Then in your agent harness:
/k8e-sandbox <goal>
Or ask naturally: "Run this Python snippet in a sandbox" — the skill drives k8e-sandbox-cli run.
Available Commands
| Command | Description |
|---|---|
k8e-sandbox-cli --profile <name> … |
Use named profile from ~/.k8e/sandbox/profiles.yaml (KIP-17; not /etc/k8e/config.yaml) |
k8e-sandbox-cli connect |
Connect local/remote gateway and install /k8e-sandbox agent skill |
k8e-sandbox-cli connect --skill-only |
Re-install agent skill only (no gateway dial) |
k8e-sandbox-cli login |
Authenticate only (mTLS cert; no skill install) |
k8e-sandbox-cli run <code> |
Run code or shell command (auto-creates/manages session) |
k8e-sandbox-cli status |
Check sandbox service availability and current session |
k8e-sandbox-cli create |
Create a new session (custom runtime, egress, manifest, git-repo) |
k8e-sandbox-cli destroy <sid> |
Destroy a session and free resources |
k8e-sandbox-cli write <sid> <path> |
Write file to /workspace (content via stdin) |
k8e-sandbox-cli read <sid> <path> |
Read file from /workspace |
k8e-sandbox-cli list <sid> |
List files in /workspace (filter by --since timestamp) |
k8e-sandbox-cli subagent <parent-sid> |
Spawn child sandbox under parent session (max depth 1) |
k8e-sandbox-cli confirm <sid> <action> |
Gate irreversible action on human approval |
k8e-sandbox-cli approve <approval-id> |
Approve a pending confirm request |
k8e sandbox-apikey create <name> [--ttl 30d|never] |
Create API key (default TTL 30 days) |
k8e sandbox-apikey list |
List API key names + expiry (secrets not shown) |
k8e sandbox-apikey delete <name> |
Delete an API key (server-side) |
See pkg/sandboxcli/skills/k8e-sandbox/SKILL.md and docs/kip-17-sandbox-cli-profiles-and-apikey-ttl.md.
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 Other Sandbox Platforms
How K8E compares to mainstream sandboxes for AI agents:
| K8E 🚀 | E2B | Daytona | agent-sandbox (k8s-sig) | DIY gVisor/Firecracker | |
|---|---|---|---|---|---|
| Self-hosted, single binary | ✅ <100MB | ⚠️ Heavy (per-env VM images) | ✅ | ❌ needs a K8s cluster | ❌ you build it |
| Isolation runtimes | ✅ gVisor / Kata / Firecracker — pluggable | Firecracker microVMs | ✅ microVM/containers | K8s RuntimeClass (gVisor/Kata/…) | one runtime |
| E2B SDK compatibility | ✅ native (official SDKs unmodified) | ✅ native | ❌ own API | ❌ | ❌ build your own API |
| Agent CLI + skill surface | ✅ k8e-sandbox-cli (+ dsh plugin tools) |
SDK only | CLI + SDK | CRDs only | ❌ |
| Warm pool (sub-500ms claims) | ✅ built-in, adaptive sizing | ✅ managed | ⚠️ | ⚠️ manual scaling | ❌ roll your own |
| Expose agent services via gateway URL | ✅ expose + live allow-hosts egress policy |
✅ hosted URLs | ⚠️ | ❌ roll your own Ingress | ❌ |
| Content-addressed snapshots | ✅ incremental restore + registry | ✅ hosted | ⚠️ | ❌ | ❌ |
| Per-session network policy (eBPF) | ✅ Cilium, live-configurable | managed (fixed) | ⚠️ | ⚠️ NetworkPolicy | hand-written |
| PTY terminals for agents | ✅ first-class (spawnTerminal) |
✅ | ✅ | ❌ | ❌ |
| License | Apache 2.0 | Apache 2.0 (hosted core paid) | Apache 2.0 | Apache 2.0 | — |
When to choose K8E
- You want E2B-style sandboxes but self-hosted — same official SDKs, your infrastructure, no per-seat pricing.
- Your agents need a rich tool surface beyond "run code": PTY terminals, snapshots, service exposure, and live egress policy — all through one audited gateway.
- You want pluggable isolation (swap gVisor ↔ Kata ↔ Firecracker per session) instead of being locked to one microVM stack.
🤝 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!
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …