{"id":13439442,"url":"https://github.com/xiaods/k8e","last_synced_at":"2026-05-31T01:00:55.429Z","repository":{"id":37023392,"uuid":"292529340","full_name":"xiaods/k8e","owner":"xiaods","description":"k8e.sh - OpenSource Agentic AI Sandbox Matrix ","archived":false,"fork":false,"pushed_at":"2026-05-30T10:00:40.000Z","size":74897,"stargazers_count":445,"open_issues_count":3,"forks_count":28,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-05-30T10:21:29.865Z","etag":null,"topics":["k8s","kubernetes","sandbox"],"latest_commit_sha":null,"homepage":"https://k8e.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaods.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2020-09-03T09:47:24.000Z","updated_at":"2026-05-30T09:21:46.000Z","dependencies_parsed_at":"2023-11-13T15:03:57.794Z","dependency_job_id":"0e644deb-4dd5-47ac-a6b4-57f08a1351c5","html_url":"https://github.com/xiaods/k8e","commit_stats":null,"previous_names":[],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/xiaods/k8e","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaods%2Fk8e","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaods%2Fk8e/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaods%2Fk8e/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaods%2Fk8e/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaods","download_url":"https://codeload.github.com/xiaods/k8e/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaods%2Fk8e/sbom","scorecard":{"id":1242049,"data":{"date":"2026-01-12","repo":{"name":"github.com/xiaods/k8e","commit":"d7fe92fb41759213a34d4b786cbd461e167105d9"},"scorecard":{"version":"v5.4.1-0.20260109214540-85483c21ffbb","commit":"85483c21ffbb0f125cf1d16aa53f283d574f4ca5"},"score":3,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/10 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/builder-arm64.yaml:1","Warn: no topLevel permission defined: .github/workflows/release.yml:1","Warn: no topLevel permission defined: .github/workflows/testing.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.31.2+k8e1 not signed: https://api.github.com/repos/xiaods/k8e/releases/187134733","Warn: release artifact v1.31.2-rc4+k8e1 not signed: https://api.github.com/repos/xiaods/k8e/releases/186790134","Warn: release artifact v1.31.2-rc3+k8e1 not signed: https://api.github.com/repos/xiaods/k8e/releases/186578859","Warn: release artifact v1.31.2-rc2+k8e1 not signed: https://api.github.com/repos/xiaods/k8e/releases/186569480","Warn: release artifact v1.31.2-rc1+k8e1 not signed: https://api.github.com/repos/xiaods/k8e/releases/186337332","Warn: release artifact v1.31.2+k8e1 does not have provenance: https://api.github.com/repos/xiaods/k8e/releases/187134733","Warn: release artifact v1.31.2-rc4+k8e1 does not have provenance: https://api.github.com/repos/xiaods/k8e/releases/186790134","Warn: release artifact v1.31.2-rc3+k8e1 does not have provenance: https://api.github.com/repos/xiaods/k8e/releases/186578859","Warn: release artifact v1.31.2-rc2+k8e1 does not have provenance: https://api.github.com/repos/xiaods/k8e/releases/186569480","Warn: release artifact v1.31.2-rc1+k8e1 does not have provenance: https://api.github.com/repos/xiaods/k8e/releases/186337332"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/builder-arm64.yaml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/builder-arm64.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/builder-arm64.yaml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/builder-arm64.yaml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/builder-arm64.yaml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/builder-arm64.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/release.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:37: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/testing.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/testing.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/testing.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/testing.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/testing.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/xiaods/k8e/testing.yml/main?enable=pin","Warn: containerImage not pinned by hash: Dockerfile.dapper:2: pin your Docker image by updating golang:1.23.8-alpine3.20 to golang:1.23.8-alpine3.20@sha256:7155e5b534ac02fb85191c51d64f727060a11ae987899f2b60c109c93f2c4777","Warn: goCommand not pinned by hash: Dockerfile.dapper:36","Warn: downloadThenRun not pinned by hash: Dockerfile.dapper:42-44","Warn: goCommand not pinned by hash: .github/workflows/testing.yml:36","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   2 goCommand dependencies pinned","Info:   0 out of   1 downloadThenRun dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":0,"reason":"20 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: https://osv.dev/GO-2025-3829","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3485","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3553","Warn: Project is vulnerable to: https://osv.dev/GO-2024-3218","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3600","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4098","Warn: Project is vulnerable to: https://osv.dev/GO-2024-3302","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4017","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4233","Warn: Project is vulnerable to: https://osv.dev/GO-2024-3321","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3487","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4116","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4134","Warn: Project is vulnerable to: https://osv.dev/GO-2025-4135","Warn: Project is vulnerable to: https://osv.dev/GO-2024-3333","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3503","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3595","Warn: Project is vulnerable to: https://osv.dev/GO-2025-3488","Warn: Project is vulnerable to: https://osv.dev/GO-2024-2978","Warn: Project is vulnerable to: https://osv.dev/GO-2024-2631"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":8,"reason":"SAST tool is not run on all commits -- score normalized to 8","details":["Warn: 24 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/85483c21ffbb0f125cf1d16aa53f283d574f4ca5/docs/checks.md#sast"}}]},"last_synced_at":"2026-01-21T14:11:47.376Z","repository_id":37023392,"created_at":"2026-01-21T14:11:47.376Z","updated_at":"2026-01-21T14:11:47.376Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33715211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["k8s","kubernetes","sandbox"],"created_at":"2024-07-31T03:01:13.959Z","updated_at":"2026-05-31T01:00:55.422Z","avatar_url":"https://github.com/xiaods.png","language":"Go","funding_links":[],"categories":["HarmonyOS","Go","Kubernetes distributions","Cluster"],"sub_categories":["Windows Manager"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026color=0:0f2027,50:203a43,100:2c5364\u0026height=200\u0026section=header\u0026text=K8E%20🚀\u0026fontSize=80\u0026fontColor=ffffff\u0026fontAlignY=38\u0026desc=Open%20Source%20Agentic%20AI%20Sandbox%20Matrix\u0026descAlignY=60\u0026descSize=22\u0026animation=fadeIn\" width=\"100%\"/\u003e\n\u003cbr/\u003e\n\n\u003ca href=\"https://git.io/typing-svg\"\u003e\n  \u003cimg src=\"https://readme-typing-svg.demolab.com?font=Fira+Code\u0026size=22\u0026pause=1000\u0026color=00D4FF\u0026center=true\u0026vCenter=true\u0026width=700\u0026lines=Open+Source+Agentic+AI+Sandbox+Matrix+%F0%9F%A4%96;Secure+Isolated+Agent+Execution+at+Scale+%F0%9F%94%92;Up+and+Running+in+60+Seconds+%E2%9A%A1;Single+Binary+%3C+100MB+%F0%9F%93%A6;CNCF+Conformant+%26+Production+Ready+%E2%9C%85\" alt=\"Typing SVG\" /\u003e\n\u003c/a\u003e\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white)](https://golang.org)\n[![Kubernetes](https://img.shields.io/badge/Kubernetes-v1.35-326CE5?style=for-the-badge\u0026logo=kubernetes\u0026logoColor=white)](https://kubernetes.io)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge\u0026logo=apache\u0026logoColor=white)](https://github.com/xiaods/k8e/blob/main/LICENSE)\n[![Stars](https://img.shields.io/github/stars/xiaods/k8e?style=for-the-badge\u0026logo=github\u0026color=FFD700)](https://github.com/xiaods/k8e/stargazers)\n[![Release](https://img.shields.io/github/v/release/xiaods/k8e?style=for-the-badge\u0026logo=github\u0026color=green)](https://github.com/xiaods/k8e/releases)\n[![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)\n\n\u003cbr/\u003e\n\n\u003e **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).\n\n\u003cbr/\u003e\n\n```bash\ncurl -sfL https://k8e.sh/install.sh | sh -\n```\n*That's it. Your agentic sandbox matrix is ready. 🤖*\n\n\u003c/div\u003e\n\n---\n\n## 📖 Table of Contents\n\n| # | Section |\n|---|---------|\n| 1 | [🤖 What is K8E?](#-what-is-k8e) |\n| 2 | [🏗️ Architecture](#️-architecture) |\n| 3 | [⚙️ Components](#️-components) |\n| 4 | [🚀 Quick Start](#-quick-start) |\n| 5 | [🔒 Sandbox Runtime Setup](#-sandbox-runtime-setup) |\n| 6 | [🤖 Sandbox CLI Skill](#-sandbox-cli-skill) |\n| 7 | [🐍 Python Client SDK](#-python-client-sdk) |\n| 8 | [🟦 TypeScript Client SDK](#-typescript-client-sdk) |\n| 9 | [🖥️ Advanced Installation](#️-advanced-installation) |\n| 9 | [🆚 K8E vs Others](#-k8e-vs-the-alternatives) |\n| 9 | [🤝 Contributing](#-contributing) |\n| 10 | [🙏 Acknowledgments](#-acknowledgments) |\n\n---\n\n## 🤖 What is K8E?\n\n**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.\n\nAs 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.\n\n\u003e 🔒 **One cluster. Many agents. Zero trust between them.**\n\n### Sandbox Capabilities\n\n| Capability | Description |\n|---|---|\n| 🔒 **Hardware Isolation** | Pluggable runtimes: gVisor (default), Kata Containers, Firecracker microVM |\n| 🌐 **Network Policies** | Cilium eBPF `toFQDNs` egress control — per-session, no proxy process needed |\n| ⚖️ **Resource Quotas** | CPU/memory caps per agent session to prevent runaway costs |\n| 🗑️ **Ephemeral Workspaces** | Auto-cleanup after agent session ends |\n| 🧠 **Warm Pool** | Pre-booted sandbox pods for sub-500ms session claim latency |\n| 🤝 **agent-sandbox compatible** | Works with [`kubernetes-sigs/agent-sandbox`](https://github.com/kubernetes-sigs/agent-sandbox) |\n| 🔄 **SKILL + CLI** | AI agents (codex, claude, pi, openclaw) connect via `k8e sandbox` CLI commands |\n\n---\n\n## 🏗️ Architecture\n\n\u003cdiv align=\"center\"\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                          K8E CLUSTER                            │\n│                                                                 │\n│   ┌─────────────────────────────────────────────────────────┐   │\n│   │                CONTROL PLANE (Server Node)              │   │\n│   │  ┌──────────────┐  ┌─────────────┐  ┌──────────┐       │   │\n│   │  │  API Server  │  │  Scheduler  │  │   etcd   │       │   │\n│   │  └──────────────┘  └─────────────┘  └──────────┘       │   │\n│   │  ┌──────────────────┐  ┌──────────────────────────────┐ │   │\n│   │  │  Controller Mgr  │  │  SandboxMatrix Controller    │ │   │\n│   │  └──────────────────┘  └──────────────────────────────┘ │   │\n│   └─────────────────────────────────────────────────────────┘   │\n│                              │                                   │\n│                 ┌────────────┴────────────┐                     │\n│   ┌─────────────▼───────────┐  ┌──────────▼──────────────┐     │\n│   │      WORKER NODE        │  │      WORKER NODE        │     │\n│   │  ┌─────────────────┐    │  │  ┌─────────────────┐    │     │\n│   │  │  sandbox-matrix │    │  │  │  sandbox-matrix │    │     │\n│   │  │  grpc-gateway   │    │  │  │  grpc-gateway   │    │     │\n│   │  │  :50051 (TLS)   │    │  │  │  :50051 (TLS)   │    │     │\n│   │  └────────┬────────┘    │  │  └────────┬────────┘    │     │\n│   │           │             │  │           │             │     │\n│   │  ┌────────▼────────┐    │  │  ┌────────▼────────┐    │     │\n│   │  │  Isolated Pods  │    │  │  │  Isolated Pods  │    │     │\n│   │  │ gVisor/Kata/FC  │    │  │  │ gVisor/Kata/FC  │    │     │\n│   │  └─────────────────┘    │  │  └─────────────────┘    │     │\n│   │  Cilium CNI (eBPF)      │  │  Cilium CNI (eBPF)      │     │\n│   └─────────────────────────┘  └─────────────────────────┘     │\n└─────────────────────────────────────────────────────────────────┘\n         ▲\n         │  gRPC (TLS)\n┌────────┴────────┐\n│  k8e sandbox    │  ← CLI commands\n└────────┬────────┘\n         │  gRPC (TLS)\n         ▼\n│  AI Agent       │  (codex / claude / pi / openclaw)\n└─────────────────┘\n```\n\n\u003c/div\u003e\n\n---\n\n## ⚙️ Components\n\n\u003cdiv align=\"center\"\u003e\n\n| Component | Version | Purpose |\n|---|---|---|\n| ☸️ **Kubernetes** | v1.35.x | Core orchestration engine |\n| 🔷 **Cilium** | Latest | eBPF networking \u0026 per-session egress policy |\n| 📦 **Containerd** | v1.7.x | Container runtime |\n| 🔑 **etcd** | v3.5.x | Distributed key-value store |\n| 🌐 **CoreDNS** | v1.11.x | Cluster DNS |\n| ⚓ **Helm Controller** | v0.16.x | GitOps \u0026 chart management |\n| 📈 **Metrics Server** | v0.7.x | Resource metrics |\n| 💾 **Local Path Provisioner** | v0.0.30 | Persistent storage |\n| 🛡️ **gVisor / Kata / Firecracker** | — | Pluggable sandbox isolation runtimes |\n| 🤖 **Sandbox CLI** | built-in | `k8e sandbox` — agent tool commands |\n\n\u003c/div\u003e\n\n---\n\n## 🚀 Quick Start\n\n### Step 1 — Install a Sandbox Runtime (recommended: before K8E)\n\nInstall the runtime shim **before** K8E so it is auto-detected on first startup. **gVisor is recommended** — no KVM required.\n\n```bash\ncurl -fsSL https://gvisor.dev/archive.key | gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \\\n  https://storage.googleapis.com/gvisor/releases release main\" \\\n  \u003e /etc/apt/sources.list.d/gvisor.list\napt-get update \u0026\u0026 apt-get install -y runsc\n```\n\n\u003e 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.\n\n\u003e Need stronger isolation? See [Sandbox Runtime Setup](#-sandbox-runtime-setup) for Kata Containers and Firecracker.\n\n### Step 2 — Install K8E\n\n```bash\ncurl -sfL https://k8e.sh/install.sh | sh -\n```\n\n### Step 3 — Verify Cluster\n\n```bash\nexport KUBECONFIG=/etc/k8e/k8e.yaml\nkubectl get nodes\nkubectl get runtimeclass              # should show: gvisor\nkubectl -n sandbox-matrix get pods   # Sandbox Matrix starts automatically\n```\n\n### Step 4 — Connect Your AI Agent\n\nInstall the K8E sandbox skill into your AI agent:\n\n```bash\nk8e sandbox-install-skill all   # installs skill files for all supported agents\n```\n\nThen ask your agent naturally:\n\n\u003e \"Run this Python snippet in a sandbox\"\n\nThe agent executes `k8e sandbox run` automatically — no session management needed.\n\nSupported agents: **codex**, **claude**, **pi**, **openclaw**.\n\n---\n\n## 🔒 Sandbox Runtime Setup\n\nK8E auto-detects installed runtimes and registers the corresponding `RuntimeClass`. Choose based on your isolation requirements:\n\n| Runtime | Isolation | Requirement | Boot time |\n|---|---|---|---|\n| **gVisor** | Syscall interception (userspace kernel) | None | ~10ms |\n| **Kata Containers** | VM-backed (QEMU) | Nested virt or bare metal | ~500ms |\n| **Firecracker** | Hardware microVM (KVM) | `/dev/kvm` | ~125ms |\n\n### gVisor — Recommended Default\n\n```bash\ncurl -fsSL https://gvisor.dev/archive.key | gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \\\n  https://storage.googleapis.com/gvisor/releases release main\" \\\n  \u003e /etc/apt/sources.list.d/gvisor.list\napt-get update \u0026\u0026 apt-get install -y runsc\n```\n\n\u003e 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.\n```\n\n### Kata Containers\n\n```bash\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) install-packages\"\nkata-runtime check\n```\n\n### Firecracker (requires `/dev/kvm`)\n\n```bash\nls /dev/kvm   # verify KVM is available\n\n# Install firecracker-containerd shim + devmapper snapshotter\n# See: https://github.com/firecracker-microvm/firecracker-containerd\nmkdir -p /var/lib/firecracker-containerd/runtime\n# Place hello-vmlinux.bin and default-rootfs.img here\n```\n\n### Apply Changes\n\nInstall runtimes **before** starting K8E for zero-restart setup. If K8E is already running, restart it after installing a new runtime shim:\n\n```bash\nsystemctl restart k8e\nkubectl get runtimeclass\n# NAME          HANDLER       AGE\n# gvisor        runsc         10s\n# kata          kata-qemu     10s\n# firecracker   firecracker   10s   ← only if /dev/kvm present\n```\n\n---\n\n## 🤖 Sandbox CLI Skill\n\n`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.\n\n```\nAI Agent (codex / claude / pi / openclaw)\n    │  shell command\n    ▼\nk8e sandbox run \"print('hello')\" --lang python\n    │  gRPC (TLS, auto-discovered)\n    ▼\nsandbox-grpc-gateway:50051\n    │\n    ▼\nIsolated Pod (gVisor / Kata / Firecracker)\n```\n\n### Install the Skill\n\n`sandbox-install-skill` copies skill files to the agent's skills directory:\n\n```bash\n# All supported agents at once\nk8e sandbox-install-skill all\n\n# Or per agent\nk8e sandbox-install-skill claude    # Skills → ~/.claude/skills/k8e-sandbox/\nk8e sandbox-install-skill openclaw  # Skills → ~/.openclaw/skills/k8e-sandbox/\nk8e sandbox-install-skill kiro      # Skills → .kiro/skills/k8e-sandbox/\nk8e sandbox-install-skill gemini    # Skills → ~/.gemini/skills/k8e-sandbox/\n```\n\n### Available Commands\n\n| Command | Description |\n|---|---|\n| `k8e sandbox run \u003ccode\u003e` | Run code or shell command (auto-manages session) |\n| `k8e sandbox status` | Check sandbox service and current session |\n| `k8e sandbox create` | Create a new session (custom runtime, egress) |\n| `k8e sandbox destroy \u003csid\u003e` | Destroy a session |\n| `k8e sandbox write \u003csid\u003e \u003cpath\u003e` | Write file to /workspace (content via stdin) |\n| `k8e sandbox read \u003csid\u003e \u003cpath\u003e` | Read file from /workspace |\n| `k8e sandbox list \u003csid\u003e` | List files in /workspace |\n| `k8e sandbox subagent \u003cparent-sid\u003e` | Spawn child sandbox (max depth 1) |\n| `k8e sandbox confirm \u003csid\u003e \u003caction\u003e` | Gate irreversible action on human approval |\n| `k8e sandbox snapshot save \u003csid\u003e \u003cname\u003e` | Save workspace as named snapshot |\n| `k8e sandbox snapshot restore \u003cname\u003e` | Create new session from saved snapshot |\n| `k8e sandbox snapshot list` | List saved snapshots |\n\nSee [skills/k8e-sandbox/SKILL.md](skills/k8e-sandbox/SKILL.md) for full usage examples.\n\n### Quick Examples\n\n```bash\n# Run Python code\nk8e sandbox run \"print('hello')\" --lang python\n\n# Multi-line code via stdin\nk8e sandbox run --lang python \u003c\u003c'EOF'\nfor i in range(10):\n    print(i)\nEOF\n\n# Write a script then execute\nk8e sandbox write $SID /workspace/script.py \u003c\u003c'EOF'\nimport pandas as pd\nprint(pd.__version__)\nEOF\nk8e sandbox run \"python3 /workspace/script.py\" --session-id $SID\n\n# Create session with custom runtime and egress\nk8e sandbox create --runtime firecracker --allowed-hosts pypi.org,github.com\n\n# Stream long-running output\nk8e sandbox run \"python3 train.py\" --session-id $SID --raw\n\n# Workspace manifest\nk8e sandbox create --manifest workspace.yaml\n\n# Workspace snapshots\nk8e sandbox snapshot save $SID my-checkpoint\nk8e sandbox snapshot restore my-checkpoint\n```\n\n### Configuration Overrides\n\nThe CLI auto-discovers the local cluster via TLS. Override when needed:\n\n```bash\nK8E_SANDBOX_ENDPOINT=10.0.0.1:50051 k8e sandbox run \"echo hello\"\nK8E_SANDBOX_CERT=/path/to/ca.crt k8e sandbox run \"echo hello\"\nk8e sandbox run \"echo hello\" --tenant my-project\n```\n\n---\n\n## 🐍 Python Client SDK\n\nThe Python SDK talks directly to the sandbox gRPC gateway — no process spawn, no stdio handshake (~1–5 ms vs ~500 ms for CLI).\n\n### Install\n\n```bash\npython3 -m pip install grpcio grpcio-tools protobuf\n```\n\n### Generate gRPC Stubs (once)\n\n```bash\npython3 -m grpc_tools.protoc -I proto \\\n  --python_out=sdk/python \\\n  --grpc_python_out=sdk/python \\\n  proto/sandbox/v1/sandbox.proto\n\n# make the generated package importable\ntouch sdk/python/sandbox/__init__.py sdk/python/sandbox/v1/__init__.py\n```\n\n### Usage\n\n**Run code (session auto-managed):**\n\n```python\nfrom sandbox_client import SandboxClient\n\nwith SandboxClient() as client:\n    result = client.run(\"print('hello')\", language=\"python\")\n    print(result.stdout)   # hello\n    print(result.exit_code)  # 0\n```\n\n**Generate 10 random numbers and compute the average:**\n\n```python\nfrom sandbox_client import SandboxClient\n\ncode = (\n    \"import random; nums = [random.randint(1,100) for _ in range(10)]; \"\n    \"print('numbers:', nums); print('average:', sum(nums)/len(nums))\"\n)\n\nwith SandboxClient() as client:\n    result = client.run(code, language=\"python\")\n    print(result.stdout)\n# numbers: [39, 60, 50, 24, 53, 32, 85, 10, 81, 3]\n# average: 43.7\n```\n\n**Multi-step workflow (shared session):**\n\n```python\nwith SandboxClient() as client:\n    client.run(\"pip install pandas\", \"bash\")   # session created\n    result = client.run(\"python3 analyze.py\", \"bash\")  # same session reused\n```\n\n**Explicit session with custom options:**\n\n```python\nfrom sandbox_client import sandbox_session\n\nwith sandbox_session(runtime_class=\"kata\", allowed_hosts=[\"github.com\"]) as (client, sid):\n    client.write_file(sid, \"/workspace/main.py\", code)\n    result = client.exec(sid, \"python3 /workspace/main.py\")\n```\n\n\u003e SDK source: `sdk/python/sandbox_client.py`\n\n---\n\n## 🟦 TypeScript Client SDK\n\nThe TypeScript SDK talks directly to the sandbox gRPC gateway — no process spawn, no stdio handshake (~1–5 ms vs ~500 ms for CLI).\n\n### Install\n\n```bash\nnpm install @grpc/grpc-js @grpc/proto-loader\n```\n\n### Usage\n\n**Run code (session auto-managed):**\n\n```typescript\nimport { SandboxClient } from \"./sandbox_client\";\n\nconst client = new SandboxClient();\nconst result = await client.run(\"print('hello')\", \"python\");\nconsole.log(result.stdout);   // hello\nawait client.close();\n```\n\n**Generate 10 random numbers and compute the average:**\n\n```typescript\nconst client = new SandboxClient();\nconst code = \"import random; nums=[random.randint(1,100) for _ in range(10)]; print('numbers:',nums); print('average:',sum(nums)/len(nums))\";\nconst result = await client.run(code, \"python\");\nconsole.log(result.stdout);\n// numbers: [39, 60, 50, 24, 53, 32, 85, 10, 81, 3]\n// average: 43.7\nawait client.close();\n```\n\n**Multi-step workflow (shared session):**\n\n```typescript\nconst client = new SandboxClient();\nawait client.run(\"pip install pandas\", \"bash\");   // session created\nconst result = await client.run(\"python3 analyze.py\", \"bash\");  // same session reused\nawait client.close();\n```\n\n**Explicit session with custom options:**\n\n```typescript\nconst sid = await client.createSession({ runtimeClass: \"kata\", allowedHosts: [\"github.com\"] });\nawait client.writeFile(sid, \"/workspace/main.py\", code);\nconst result = await client.exec(sid, \"python3 /workspace/main.py\");\nawait client.destroySession(sid);\n```\n\n**Streaming output:**\n\n```typescript\nfor await (const chunk of client.execStream(sid, \"python3 train.py\")) {\n  process.stdout.write(chunk);\n}\n```\n\n**One-shot helper:**\n\n```typescript\nimport { sandboxRun } from \"./sandbox_client\";\nconst { stdout } = await sandboxRun(\"echo hello\");\n```\n\n\u003e SDK source: `sdk/typescript/sandbox_client.ts`\n\n---\n\n## 🖥️ Advanced Installation\n\n### Add a Worker Node\n\n```bash\n# Get token from server node\ncat /var/lib/k8e/server/node-token\n\n# On worker machine\ncurl -sfL https://k8e.sh/install.sh | \\\n  K8E_TOKEN=\u003ctoken\u003e \\\n  K8E_URL=https://\u003cserver-ip\u003e:6443 \\\n  INSTALL_K8E_EXEC=\"agent\" \\\n  sh -\n```\n\n### Disable Sandbox Matrix\n\n```bash\ncurl -sfL https://k8e.sh/install.sh | INSTALL_K8E_EXEC=\"server --disable-sandbox-matrix\" sh -\n```\n\n### Key Environment Variables\n\n```bash\nK8E_TOKEN=\u003csecret\u003e              # cluster join token\nK8E_URL=https://\u003cserver\u003e:6443   # server URL (agent nodes)\nK8E_KUBECONFIG_OUTPUT=\u003cpath\u003e    # kubeconfig output path\n```\n\n---\n\n## 🆚 K8E vs The Alternatives\n\n\u003cdiv align=\"center\"\u003e\n\n| Feature | K8E 🚀 | K3s | K8s (vanilla) | MicroK8s |\n|---|---|---|---|---|\n| Install time | **~60s** | ~90s | ~20min | ~5min |\n| Binary size | **\u003c100MB** | ~70MB | ~1GB+ | ~200MB |\n| Agentic Sandbox | ✅ Native | ❌ No | ⚠️ Manual | ❌ No |\n| eBPF networking | ✅ Cilium | ⚠️ Optional | ⚠️ Optional | ❌ No |\n| Sandbox CLI skill built-in | ✅ Yes | ❌ No | ❌ No | ❌ No |\n| HA embedded etcd | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Limited |\n| CNCF conformant | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |\n| Multi-arch | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |\n\n\u003c/div\u003e\n\n---\n\n## 🤝 Contributing\n\n```bash\ngit clone https://github.com/\u003cyour-username\u003e/k8e.git \u0026\u0026 cd k8e\ngit checkout -b feat/my-feature\nmake \u0026\u0026 make test\ngit push origin feat/my-feature\n```\n\n- 🐛 [Bug Reports](https://github.com/xiaods/k8e/issues/new)\n- 💡 [Feature Requests](https://github.com/xiaods/k8e/issues/new)\n- 🔍 [Open PRs](https://github.com/xiaods/k8e/pulls)\n\n---\n\n## 🛡️ Security\n\nReport vulnerabilities via [GitHub Security Advisories](https://github.com/xiaods/k8e/security/advisories). Do not open public issues for security bugs.\n\n---\n\n## 📄 License\n\nApache License 2.0 — see [LICENSE](https://github.com/xiaods/k8e/blob/main/LICENSE).\n\n---\n\n## 🙏 Acknowledgments\n\n\u003cdiv align=\"center\"\u003e\n\n| Project | Contribution |\n|---|---|\n| 🐄 [**K3s**](https://github.com/k3s-io/k3s) | Lightweight Kubernetes foundation that inspired K8E |\n| ☸️ [**Kubernetes**](https://github.com/kubernetes/kubernetes) | The orchestration engine everything is built on |\n| 🔷 [**Cilium**](https://github.com/cilium/cilium) | eBPF-powered networking and per-session egress control |\n| 🤖 [**agent-sandbox**](https://github.com/kubernetes-sigs/agent-sandbox) | Kubernetes-native agent sandboxing primitives |\n| 🌐 [**CNCF**](https://cncf.io) | Fostering the open-source cloud native ecosystem |\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026color=0:2c5364,50:203a43,100:0f2027\u0026height=120\u0026section=footer\u0026animation=fadeIn\" width=\"100%\"/\u003e\n\n**k8e.sh — Open Source Agentic AI Sandbox Matrix**\n\n[![GitHub](https://img.shields.io/badge/GitHub-xiaods%2Fk8e-181717?style=for-the-badge\u0026logo=github)](https://github.com/xiaods/k8e)\n[![Website](https://img.shields.io/badge/Website-k8e.sh-00D4FF?style=for-the-badge\u0026logo=googlechrome\u0026logoColor=white)](https://k8e.sh)\n[![Docs](https://img.shields.io/badge/Docs-k8e.sh%2Fdocs-green?style=for-the-badge\u0026logo=gitbook\u0026logoColor=white)](https://k8e.sh/docs/)\n\n*If K8E powers your agents, give us a ⭐ — it means the world to us!*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaods%2Fk8e","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaods%2Fk8e","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaods%2Fk8e/lists"}