[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Katakate--k7":3,"tool-Katakate--k7":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160015,2,"2026-04-18T11:30:52",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":76,"owner_website":76,"owner_url":77,"languages":78,"stars":91,"forks":92,"last_commit_at":93,"license":94,"difficulty_score":95,"env_os":96,"env_gpu":97,"env_ram":98,"env_deps":99,"category_tags":111,"github_topics":112,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":123,"updated_at":124,"faqs":125,"releases":153},9240,"Katakate\u002Fk7","k7","Your own self-hosted infra for lightweight VM sandboxes to safely execute untrusted code. CLI, API, Python SDK. ⭐ Star it if you like it! ⭐","k7 是一款专为安全执行不可信代码而设计的自托管基础设施工具。它能够帮助用户轻松创建、管理和编排轻量级的虚拟机沙箱，特别适合需要大规模运行未知代码的场景，例如 AI 智能体、自定义无服务器架构或高安全要求的 CI\u002FCD 流程。\n\n传统方案常使用 Docker 容器来隔离代码，但存在“容器逃逸”等安全风险。k7 通过结合 Kata Containers 和 Firecracker 微虚拟机技术，将每个任务封装在独立的轻量级虚拟机中，提供了比容器更严格的内核级隔离，同时保持了极快的启动速度和极低的资源占用。此外，它还利用 Kubernetes（K3s）进行集群编排，并采用高效的磁盘快照技术，让单台机器能稳定承载数十个并发沙箱。\n\n这款工具主要面向开发者、DevOps 工程师以及人工智能研究人员。如果你正在构建需要动态执行用户提交代码的 AI 应用，或者希望搭建一套完全由自己掌控、无厂商锁定的安全计算平台，k7 是一个非常理想的选择。目前项目处于测试阶段，完全开源且免费，为构建下一代安全的分布式计算环境提供了坚实的技术底座。","\u003Cp align=\"center\">\n\u003Cspan style=\"font-family: 'Georgia', sans-serif; font-weight: bold; font-size: 48px; font-style: italic; color: #ef672b; vertical-align: middle; margin-left: 10px;\">\n    KATAKATE\n  \u003C\u002Fspan>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\" style=\"font-weight: bold; font-size: 20px; \">\n  Self-hosted secure VM sandboxes for AI compute at scale\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fkatakate.org\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fwebsite-katakate.org-orange\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FKatakate\u002Fk7\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FKatakate\u002Fk7?style=social\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdocs.katakate.org\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-docs.katakate.org-orange\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fnews.ycombinator.com\u002Fitem?id=45656952\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FShow%20HN-%231%20🔥-FF6600\" alt=\"Show HN #1\">\n  \u003C\u002Fa>\n  \u003Ca href=\"assets\u002Fshow-hn_nb1_post-id-45656952.png\" title=\"Screenshot proof\">📸\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fconsole.dev\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFeatured-Console.dev-4F39F5\" alt=\"Featured on Console.dev\">\n  \u003C\u002Fa>\n  \u003Ca href=\"assets\u002Fk7-console-dev.png\" title=\"Screenshot proof\">📸\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fchangelog.com\u002Fnews\u002F169\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFeatured-Changelog-59B287\" alt=\"Featured on Changelog\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=2tgqzZvmbak\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub%20Trending-Oct%2023%2C%202025-black?logo=github\" alt=\"GitHub Trending (Oct 23, 2025)\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FKatakate_k7_readme_d4280968d629.png\" alt=\"Katakate Logo\" width=\"3600\" style=\"vertical-align: middle;\"\u002F>\n\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fdeepwiki.com\u002FKatakate\u002Fk7\">\n    \u003Cimg src=\"https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg\" \u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Finstall%20with-apt-blue?logo=debian\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fkatakate\">\n\u003C\u002Fp> \n\n\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FKatakate_k7_readme_2f66ab38f83a.gif\" alt=\"K7 Demo\" width=\"900\"\u002F>\n\u003C\u002Fp>\n\n\n\n\n\n\u003Ci>\u003Cb>Katakate\u003C\u002Fb>\u003C\u002Fi> aims to make it easy to create, manage and orchestrate lightweight safe VM sandboxes for executing untrusted code, at scale. It is built on battle-tested VM isolation with Kata, Firecracker and Kubernetes. It is orignally motivated by AI agents that need to run arbitrary code at scale but it is also great for:\n- Custom serverless (like AWS Fargate, but yours)\n- Hardened CI\u002FCD runners (no Docker-in-Docker risks)\n- Blockchain execution layers for AI dApps\n\n> \u003Cb>100% open‑source\u003C\u002Fb> (Apache‑2.0). For technical support, write us at: hi@katakate.org\u003C\u002Fb>\n\n\u003Ch3 align=\"left\">\nThe Tech Stack\n\u003C\u002Fh3>\n\n\u003Ci>\u003Cb>Katakate\u003C\u002Fb>\u003C\u002Fi> is built on:\n- \u003Ci>\u003Cb>Kubernetes\u003C\u002Fb>\u003C\u002Fi> for orchestration, with K3s which is prod-ready and a great choice for edge nodes,\n- \u003Ci>\u003Cb>Kata\u003C\u002Fb>\u003C\u002Fi> to encapsulate containers into light-weight virtual-machines,\n- \u003Ci>\u003Cb>Firecracker\u003C\u002Fb>\u003C\u002Fi> as the chosen VM, for super-fast boots, light footprints and minimal attack surface,\n- \u003Ci>\u003Cb>Devmapper Snapshotter\u003C\u002Fb>\u003C\u002Fi> with \u003Ci>\u003Cb>thin-pool provisioning of logical volumes\u003C\u002Fb>\u003C\u002Fi> for efficient use of disk space shared by dozens of VMs per node.\n\n\n\u003Ch3 align=\"left\">\nComing Soon\n\u003C\u002Fh3>\n\n\n- 🛠️ Docker \u003Ccode>build\u003C\u002Fcode> \u002F \u003Ccode>run\u003C\u002Fcode> \u002F \u003Ccode>compose\u003C\u002Fcode> support \u003Cb>\u003Ci>inside the VM sandbox\u003C\u002Fi>\u003C\u002Fb>\n- 🌐 Multi-node cluster capabilities for distributed workloads\n- 🔍 Cilium FQDN-based DNS resolution to safely whitelist domains, not just IP blocks\n- ⚙️ Support other VMM such as Qemu for GPU workloads\n\n📋 **See [ROADMAP.md](ROADMAP.md) for the complete feature roadmap and project priorities.**\n\n\n\u003Cp align=\"left\" style=\"margin-top: 40px;  font-size: 14px;\">\n   \u003Cstrong>Note:\u003C\u002Fstrong> Katakate is currently in \u003Cem>beta\u003C\u002Fem> and under security review. Use with caution for highly sensitive workloads.\n\u003C\u002Fp>\n\n\n# Usage\n\nFor usage you need:\n- **Node(s)** that will host the VM sandboxes\n- **Client** from where to send requests\n\nWe provide a:\n\n- **CLI**: to use on the node(s) directly --> `apt install k7`\n- **API**: deployed on the (master) node(s) --> `k7 start-api`\n- **Python SDK**: Python client sync\u002Fasync talking to API --> `pip install katakate`\n\n## Current requirements\n\n### For the node(s)\n\n- Ubuntu (amd64 or arm64) host.\n- Hardware virtualization (KVM) available and accessible\n  - Check: `ls \u002Fdev\u002Fkvm` should exist.\n  - This is typically available on your own Linux machine.\n  - On cloud providers, it varies. \n    - Hetzner (the only one I tested so far)  yes for their `Robot` instances only, i.e. \"dedicated\": robot.hetzner.com. \n    - AWS: only `.metal` EC2 instances. \n    - GCP: virtualization friendly, most instances, with `--enable-nested-virtualization` flag.\n    - Azure: Dv3, Ev3, Dv4, Ev4, Dv5, Ev5 (Intel\u002FAMD x86) or Dpdsv5, Dpldsv5, Epsv5 (ARM64).\n    - DigitalOcean: Premium Intel and AMD droplets with nested virtualization enabled.\n    - Others: in general, hardware virtualization is not exposed on cloud VPS, so you'll likely want a dedicated \u002F bare metal.\n- One raw disk (unformatted, unpartitioned) for the thin-pool that k7 will provision for efficient disk usage of sandboxes.\n  - Use `.\u002Futils\u002Fwipe-disk.sh \u002Fyour\u002Fdisk` to wipe a disk clean before provisioning. DANGER: destructive - it will remove data\u002Fpartitions\u002Fformatting\u002FSWRAID.\n- Ansible (for installer):\n  ```bash\n  sudo add-apt-repository universe -y\n  sudo apt update\n  sudo apt install -y ansible\n  ```\n- Docker and Docker Compose (for the API):\n  ```bash\n  curl -fsSL https:\u002F\u002Fget.docker.com | sh\n  ```\n\nAlready tested setups:\n  - Hetzner Robot instance with Ubuntu 24.04, x86_64 or ARM64 arch, booked with 1 extra empty disk `nvme2n1` for the thin-pool provisioning. See the setup guide (PDF): [tutorials\u002Fk7_hetzner_node_setup.pdf](tutorials\u002Fk7_hetzner_node_setup.pdf).\n\n### For the client\n\nJust recent Python.\n\n## Quick Start\n\n\n### Get your node(s) ready\n\nFirst install `k7` on your Linux server that will host the VMs:\n```shell\nsudo add-apt-repository ppa:katakate.org\u002Fk7\nsudo apt update\nsudo apt install k7\n```\n\n\nThen let `k7` get your node ready with everything:\n```console\n$  k7 install\nCurrent task: Reminder about logging out and back in for group changes\n  Installing K7 on 1 host(s)... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:01:41\n✅ Installation completed successfully!\n\n```\n\nOptionally pass `-v` for a verbose output.\n\n> It will also tell you which raw disk was auto-selected for the LVM thin-pool. If you prefer, specify the disk explicitly:\n> ```bash\n> k7 install --disk \u002Fdev\u002Fnvme2n1\n> ```\n\nThis will install and most importantly connect together the following components:\n- Kubernetes (K3s prod-ready distribution)\n- Kata (for container virtualization)\n- Firecracker (as Virtual Machine Manager)\n- Jailer (to secure Firecracker VMs further into a chroot)\n- devmapper snapshotter with thin-pool provisioning of logical volumes for VM efficient disk memory usage\n\n\nCareful design: config updates will not touch your existing Docker or containerd setups. We chose to use K3s' own containerd for minimal disruption. Installation may however overwrite existing installations of K3s, Kata, Firecracker, Jailer. \n\n### CLI Usage\n\nYou can run workloads directly from the node(s) using the CLI. To create a sandbox, just create a yaml config for it. \n\n#### k7.yaml example:\n\n```yaml\nname: my-sandbox-123\nimage: alpine:latest\nnamespace: default\n\n# Optional: restrict egress (safe pattern: whitelist only your own egress proxy IP)\negress_whitelist:\n  - \"10.0.0.5\u002F32\"     # Your private egress proxy\u002Fgateway\n\n# Optional: resource limits\nlimits:\n  cpu: \"1\"\n  memory: \"1Gi\"\n  ephemeral-storage: \"2Gi\"\n\n# Optional: run before_script inside the container once at start. Network restrictions apply after the before-script, so you can install packages here, pull git repos, etc\nbefore_script: |\n  apk add --no-cache git curl\n\n# Optional: load environment variables from a file. These will be available both during the before-script, and in the sandbox\nenv_file: path\u002Fto\u002Fyour\u002Fsecrets\u002F.env\n```\n\n\n#### Running commands\n\n\n```bash\n# Create a sandbox (uses k7.yaml in the current directory by default, but you can also pass: -f myfile.yaml)\nk7 create\n\n# List sandboxes\nk7 list\n\n# Delete a sandbox\nk7 delete my-sandbox-123\n\n# Delete all sandboxes. You can also pass a namespace\nk7 delete-all\n```\n\n### API usage\n\nIf you'd like to manage workloads remotely, just use the API:\n\n```shell\n# Start API server (containerized and SSL support with Cloudflared)\nk7 start-api\n\n# Generate API key\nk7 generate-api-key my-key1\n```\n\nMake sure your user is in the `Docker` group to be allowed to start or stop the API.\n\nAs for generating \u002F listing \u002F revoking keys, you might need `sudo` or `root`. \n\n### Python SDK Usage\n\nAfter your k7 API is up, usage is very simple.\n\nInstall the Python SDK via:\n```shell\npip install katakate\n```\n\nOr if you want async support:\n```shell\npip install \"katakate[async-sdk]\"\n```\n\nThen use with:\n```python\nfrom katakate import Client\n\nk7 = Client(\n  endpoint='https:\u002F\u002F\u003Cyour-endpoint>', \n  api_key='your-key')\n\n# Create sandbox\nsb = k7.create({\n    \"name\": \"my-sandbox\",\n    \"image\": \"alpine:latest\"\n})\n\n# Execute code\nresult = sb.exec('echo \"Hello World\"')\nprint(result['stdout'])\n\n# List all sandboxes\nsandboxes = k7.list()\n\n# Delete sandbox\nsb.delete()\n```\n\n#### Async variant\n```python\nimport asyncio\nfrom katakate import AsyncClient\n\nasync def main():\n    k7 = AsyncClient(\n      endpoint='https:\u002F\u002F\u003Cyour-endpoint>', \n      api_key='your-key'\n    )\n    print(await k7.list())\n    await k7.aclose()\n\nasyncio.run(main())\n```\n\n  \n### Tutorials\n\n- LangChain ReAct agent with a K7 sandbox tool\n  - Path: tutorials\u002Flangchain-react-agent\n  - Setup: copy .env.example to .env and fill K7_ENDPOINT\u002FK7_API_KEY\u002FOPENAI_API_KEY\n  - Run: python agent.py\n  - Try asking it anything! e.g. \"List files from '\u002F'\"\n\n## Build from source\n\n\nFirst install make if not already available:\n```bash\nsudo add-apt-repository universe -y\nsudo apt update\nsudo apt install make\n```\n\n\nTo build the `k7` CLI and API into `.deb` package:\n```shell\nmake build\n```\n\nYou can then install it with:\n```shell\nsudo make install\n```\n\nTo uninstall later:\n```shell\nsudo make uninstall\n```\n\nNote: we recommend running `make uninstall` before reinstalling if it is not your first install, to avoid stale copies of cached files in the .deb package.\n\n### Fast development workflow\n\nFor faster development iterations when working on the CLI, you can use `dev.sh` to run `k7` commands directly without rebuilding the binary:\n\n```shell\n# Basic commands\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh list\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh create\n\n# Install with options\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install -v\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install --disk \u002Fdev\u002Fnvme2n1\n\n\n# Create sandbox with options\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh create --name test --image alpine:latest\n```\n\nThis script uses `uv run` to execute the CLI with all dependencies, so you can test changes immediately without running `make build` every time. This is especially useful when iterating on CLI code changes.\n\n### Build and run the API container\n\nLocal dev image:\n```bash\n# Build the API image locally\nmake api-build-local\n\n# Run API using local image (no pull)\nmake api-run-local\n```\n\n\n### Build the katakate Python SDK from source\n\nPreferred (uv):\n\n```bash\n# create env\nuv venv .venv-build\n. .venv-build\u002Fbin\u002Factivate\n\n# install directly from source in editable mode\nuv pip install -e .\n```\n\n\n## Security\n\nK7 sandboxes are hardened by default with multiple layers of security:\n\n- **VM isolation**: Kata Containers provide hardware-level isolation via lightweight VMs with Firecracker\n  - VMs are further restricted into a chroot using Jailer\n  - Kata's Seccomp restrictions are enabled\n\n- **Linux capabilities**: All capabilities are dropped by default (`drop: ALL`) for defense-in-depth\n  - Only explicitly add back capabilities you need via `cap_add` parameter\n  - `allow_privilege_escalation` is always set to `false`\n  - Seccomp profile: `RuntimeDefault`\n\n- **Non-root execution**: Optionally run containers and pods as non-root user (UID 65532):\n  - `container_non_root`: Run the main container as non-root and disable privilege escalation\n  - `pod_non_root`: Run the entire pod as non-root with consistent filesystem ownership (UID\u002FGID\u002FFSGroup 65532)\n\n- **API security**:\n  - API keys stored as SHA256 hashes with timing-attack-resistant comparison\n  - Expiry enforced; last-used timestamp recorded\n  - File-based storage with 600 permissions (`\u002Fetc\u002Fk7\u002Fapi_keys.json` by default)\n\n- **Network policies**: Complete network isolation for VM sandboxes\n  - **Ingress isolation**: All inter-VM communication is blocked by default to prevent sandbox-to-sandbox access\n  - **Egress lockdown**: Control outbound traffic with CIDR-based restrictions using Kubernetes NetworkPolicies\n  - **DNS is blocked** when egress is locked down; only IPs\u002FCIDRs in `egress_whitelist` are reachable\n  - Administrative access via `kubectl exec` and `k7 shell` is preserved (uses Kubernetes API, not pod networking)\n  - Soon to come: Cilium integration for domain name whitelisting\n\nMore security features are currently on the roadmap, including integrating AppArmor.\n\n## Packaging & Releases\n\n- Layout uses `src\u002F`:\n  - CLI, API, core live under `src\u002Fk7\u002F`\n  - SDK under `src\u002Fkatakate\u002F`\n- Root packaging targets the `katakate` SDK only; assets under `src\u002Fk7\u002F` are not part of the PyPI distribution.\n- `MANIFEST.in` (for the `katakate` SDK) should include essentials like `LICENSE` and `README.md` only; deploy assets from `src\u002Fk7\u002Fdeploy\u002F*` belong to the Debian\u002FCLI packaging flow, not to the PyPI package.\n- `setup.py` for `katakate` lives at repo root; packages from `src\u002F`.\n- The CLI Debian package is built via `src\u002Fk7\u002Fcli\u002Fbuild.sh` and produces `dist\u002Fk7_\u003Cversion>_amd64.deb` and `dist\u002Fk7_\u003Cversion>_arm64.deb`.\n- CI (tags `v*`) can publish the PyPI SDK and upload the `.deb` artifact.\n\n\n\n## Known issues\n\n- Jailer seems to be currently ignored by Kata despite being passed correctly into its configuration, and despite the Jailer process being started. The use of Kubernetes secrets could be a reason of incompatibility. This is under investigation.  ","\u003Cp align=\"center\">\n\u003Cspan style=\"font-family: 'Georgia', sans-serif; font-weight: bold; font-size: 48px; font-style: italic; color: #ef672b; vertical-align: middle; margin-left: 10px;\">\n    卡塔卡特\n  \u003C\u002Fspan>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\" style=\"font-weight: bold; font-size: 20px; \">\n  面向大规模 AI 计算的自托管安全虚拟机沙箱\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fkatakate.org\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fwebsite-katakate.org-orange\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FKatakate\u002Fk7\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FKatakate\u002Fk7?style=social\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdocs.katakate.org\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-docs.katakate.org-orange\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fnews.ycombinator.com\u002Fitem?id=45656952\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FShow%20HN-%231%20🔥-FF6600\" alt=\"Show HN 第一名\">\n  \u003C\u002Fa>\n  \u003Ca href=\"assets\u002Fshow-hn_nb1_post-id-45656952.png\" title=\"截图证明\">📸\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fconsole.dev\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFeatured-Console.dev-4F39F5\" alt=\"Console.dev 推荐\">\n  \u003C\u002Fa>\n  \u003Ca href=\"assets\u002Fk7-console-dev.png\" title=\"截图证明\">📸\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fchangelog.com\u002Fnews\u002F169\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFeatured-Changelog-59B287\" alt=\"Changelog 推荐\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=2tgqzZvmbak\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub%20Trending-Oct%2023%2C%202025-black?logo=github\" alt=\"GitHub 趋势（2025年10月23日）\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FKatakate_k7_readme_d4280968d629.png\" alt=\"Katakate Logo\" width=\"3600\" style=\"vertical-align: middle;\"\u002F>\n\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fdeepwiki.com\u002FKatakate\u002Fk7\">\n    \u003Cimg src=\"https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg\" \u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Finstall%20with-apt-blue?logo=debian\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fkatakate\">\n\u003C\u002Fp> \n\n\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FKatakate_k7_readme_2f66ab38f83a.gif\" alt=\"K7 演示\" width=\"900\"\u002F>\n\u003C\u002Fp>\n\n\n\n\n\n\u003Ci>\u003Cb>卡塔卡特\u003C\u002Fb>\u003C\u002Fi> 致力于轻松创建、管理和编排轻量级的安全虚拟机沙箱，以大规模执行不受信任的代码。它基于久经考验的 VM 隔离技术，结合 Kata、Firecracker 和 Kubernetes 构建而成。最初是为了满足需要大规模运行任意代码的 AI 代理而设计，但它也非常适用于：\n- 自定义无服务器架构（类似 AWS Fargate，但由您自己掌控）\n- 增强型 CI\u002FCD 运行器（无需担心 Docker-in-Docker 的风险）\n- 用于 AI dApp 的区块链执行层\n\n> \u003Cb>100% 开源\u003C\u002Fb>（Apache‑2.0）。如需技术支持，请发送邮件至：hi@katakate.org\u003C\u002Fb>\n\n\u003Ch3 align=\"left\">\n技术栈\n\u003C\u002Fh3>\n\n\u003Ci>\u003Cb>卡塔卡特\u003C\u002Fb>\u003C\u002Fi> 基于以下技术构建：\n- \u003Ci>\u003Cb>Kubernetes\u003C\u002Fb>\u003C\u002Fi> 用于编排，采用 K3s，该版本已具备生产就绪能力，非常适合边缘节点；\n- \u003Ci>\u003Cb>Kata\u003C\u002Fb>\u003C\u002Fi> 将容器封装为轻量级虚拟机；\n- \u003Ci>\u003Cb>Firecracker\u003C\u002Fb>\u003C\u002Fi> 作为首选的虚拟机管理程序，具有超快启动速度、极小的资源占用和最小化攻击面；\n- \u003Ci>\u003Cb>Devmapper Snapshotter\u003C\u002Fb>\u003C\u002Fi> 结合 \u003Ci>\u003Cb>逻辑卷精简池配置\u003C\u002Fb>\u003C\u002Fi> 技术，可高效利用单个节点上数十个虚拟机共享的磁盘空间。\n\n\n\u003Ch3 align=\"left\">\n即将推出\n\u003C\u002Fh3>\n\n\n- 🛠️ 在 \u003Cb>\u003Ci>虚拟机沙箱内部\u003C\u002Fi>\u003C\u002Fb> 支持 Docker \u003Ccode>build\u003C\u002Fcode> \u002F \u003Ccode>run\u003C\u002Fcode> \u002F \u003Ccode>compose\u003C\u002Fcode>\n- 🌐 多节点集群功能，支持分布式工作负载\n- 🔍 基于 Cilium FQDN 的 DNS 解析，可安全地白名单域名，而不仅仅是 IP 地址段\n- ⚙️ 支持其他 VMM，例如 Qemu，以处理 GPU 工作负载\n\n📋 **完整功能路线图及项目优先级，请参阅 [ROADMAP.md](ROADMAP.md)。**\n\n\n\u003Cp align=\"left\" style=\"margin-top: 40px;  font-size: 14px;\">\n   \u003Cstrong>注：\u003C\u002Fstrong> 卡塔卡特目前处于 \u003Cem>测试阶段\u003C\u002Fem>，并正在进行安全审查。请谨慎用于高度敏感的工作负载。\n\u003C\u002Fp>\n\n\n# 使用方法\n\n使用时您需要：\n- 承载虚拟机沙箱的 **节点**\n- 发送请求的 **客户端**\n\n我们提供：\n- **CLI**：直接在节点上使用 --> `apt install k7`\n- **API**：部署在主节点上 --> `k7 start-api`\n- **Python SDK**：与 API 通信的同步\u002F异步 Python 客户端 --> `pip install katakate`\n\n## 当前要求\n\n### 对于节点\n\n- 主机操作系统为 Ubuntu（amd64 或 arm64）。\n- 必须启用并可访问硬件虚拟化（KVM）。\n  - 检查命令：`ls \u002Fdev\u002Fkvm` 应显示文件存在。\n  - 通常情况下，您自己的 Linux 机器都支持此功能。\n  - 在云服务提供商中情况各异：\n    - Hetzner（我目前唯一测试过的厂商）仅在其“Robot”专用实例上支持，即 robot.hetzner.com。\n    - AWS：仅限 `.metal` EC2 实例。\n    - GCP：大多数实例均支持虚拟化，只需添加 `--enable-nested-virtualization` 标志即可。\n    - Azure：Dv3、Ev3、Dv4、Ev4、Dv5、Ev5（Intel\u002FAMD x86）或 Dpdsv5、Dpldsv5、Epsv5（ARM64）。\n    - DigitalOcean：启用嵌套虚拟化的高端 Intel 和 AMD Droplet。\n    - 其他云服务商：一般而言，云 VPS 不会暴露硬件虚拟化功能，因此建议选择专用服务器或裸金属服务器。\n- 一块原始磁盘（未格式化、未分区），用于 k7 配置的精简池，以实现沙箱的高效磁盘使用。\n  - 使用 `.\u002Futils\u002Fwipe-disk.sh \u002Fyour\u002Fdisk` 可在配置前将磁盘彻底清空。注意：此操作具有破坏性，会删除数据、分区、格式化信息以及 SWRAID 等内容。\n- Ansible（用于安装程序）：\n  ```bash\n  sudo add-apt-repository universe -y\n  sudo apt update\n  sudo apt install -y ansible\n  ```\n- Docker 和 Docker Compose（用于 API）：\n  ```bash\n  curl -fsSL https:\u002F\u002Fget.docker.com | sh\n  ```\n\n已验证的部署方案：\n  - Hetzner Robot 实例，配备 Ubuntu 24.04，架构为 x86_64 或 ARM64，并额外订购了一块空白磁盘 `nvme2n1` 用于精简池配置。有关设置指南，请参阅 PDF 文件：[tutorials\u002Fk7_hetzner_node_setup.pdf](tutorials\u002Fk7_hetzner_node_setup.pdf)。\n\n### 对于客户端\n\n只需最新版 Python 即可。\n\n## 快速入门\n\n### 准备您的节点\n\n首先，在将托管虚拟机的 Linux 服务器上安装 `k7`：\n```shell\nsudo add-apt-repository ppa:katakate.org\u002Fk7\nsudo apt update\nsudo apt install k7\n```\n\n\n然后让 `k7` 为您准备好节点及其所有组件：\n```console\n$  k7 install\n当前任务：提醒您注销并重新登录以使组更改生效\n  在 1 个主机上安装 K7... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:01:41\n✅ 安装成功完成！\n\n```\n\n您可以选择添加 `-v` 参数以获取详细输出。\n\n> 系统还会告知您为 LVM 薄池自动选择的原始磁盘。如果您希望明确指定磁盘，可以使用以下命令：\n> ```bash\n> k7 install --disk \u002Fdev\u002Fnvme2n1\n> ```\n\n此操作将安装并连接以下组件：\n- Kubernetes（K3s 生产就绪发行版）\n- Kata（用于容器虚拟化）\n- Firecracker（作为虚拟机管理器）\n- Jailer（进一步将 Firecracker 虚拟机隔离到 chroot 环境中以增强安全性）\n- devmapper 快照程序，配合薄池配置逻辑卷，实现虚拟机高效磁盘存储\n\n\n设计周全：配置更新不会影响您现有的 Docker 或 containerd 配置。我们选择使用 K3s 自带的 containerd，以尽量减少干扰。不过，安装可能会覆盖已有的 K3s、Kata、Firecracker 和 Jailer 安装。\n\n### CLI 使用\n\n您可以通过 CLI 直接在节点上运行工作负载。要创建一个沙箱，只需为其编写一个 YAML 配置文件即可。\n\n#### `k7.yaml` 示例：\n\n```yaml\nname: my-sandbox-123\nimage: alpine:latest\nnamespace: default\n\n# 可选：限制出站流量（安全模式：仅允许您自己的出站代理 IP）\negress_whitelist:\n  - \"10.0.0.5\u002F32\"     # 您的私有出站代理\u002F网关\n\n# 可选：资源限制\nlimits:\n  cpu: \"1\"\n  memory: \"1Gi\"\n  ephemeral-storage: \"2Gi\"\n\n# 可选：在容器启动时运行一次 before_script。网络限制将在 before_script 执行后生效，因此您可以在此处安装软件包、拉取 Git 仓库等。\nbefore_script: |\n  apk add --no-cache git curl\n\n# 可选：从文件加载环境变量。这些变量在 before_script 和沙箱中均可用。\nenv_file: path\u002Fto\u002Fyour\u002Fsecrets\u002F.env\n```\n\n\n#### 运行命令\n\n\n```bash\n# 创建沙箱（默认使用当前目录下的 k7.yaml，也可通过 -f myfile.yaml 指定）\nk7 create\n\n# 列出沙箱\nk7 list\n\n# 删除沙箱\nk7 delete my-sandbox-123\n\n# 删除所有沙箱。您也可以指定命名空间。\nk7 delete-all\n```\n\n### API 使用\n\n如果您希望远程管理工作负载，可以直接使用 API：\n\n```shell\n# 启动 API 服务器（容器化，并通过 Cloudflared 支持 SSL）\nk7 start-api\n\n# 生成 API 密钥\nk7 generate-api-key my-key1\n```\n\n请确保您的用户属于 `Docker` 组，以便有权启动或停止 API。\n\n至于密钥的生成、列出和撤销，可能需要 `sudo` 或 `root` 权限。\n\n### Python SDK 使用\n\n当您的 k7 API 启动后，使用起来非常简单。\n\n通过以下命令安装 Python SDK：\n```shell\npip install katakate\n```\n\n如果您需要异步支持：\n```shell\npip install \"katakate[async-sdk]\"\n```\n\n然后可以这样使用：\n```python\nfrom katakate import Client\n\nk7 = Client(\n  endpoint='https:\u002F\u002F\u003Cyour-endpoint>', \n  api_key='your-key')\n\n# 创建沙箱\nsb = k7.create({\n    \"name\": \"my-sandbox\",\n    \"image\": \"alpine:latest\"\n})\n\n# 执行代码\nresult = sb.exec('echo \"Hello World\"')\nprint(result['stdout'])\n\n# 列出所有沙箱\nsandboxes = k7.list()\n\n# 删除沙箱\nsb.delete()\n```\n\n#### 异步版本\n```python\nimport asyncio\nfrom katakate import AsyncClient\n\nasync def main():\n    k7 = AsyncClient(\n      endpoint='https:\u002F\u002F\u003Cyour-endpoint>', \n      api_key='your-key'\n    )\n    print(await k7.list())\n    await k7.aclose()\n\nasyncio.run(main())\n```\n\n  \n### 教程\n\n- 使用 K7 沙箱工具的 LangChain ReAct 代理\n  - 路径：tutorials\u002Flangchain-react-agent\n  - 设置：将 .env.example 复制到 .env 并填写 K7_ENDPOINT\u002FK7_API_KEY\u002FOPENAI_API_KEY\n  - 运行：python agent.py\n  - 尝试向它提问任何问题！例如：“列出 \u002F 目录下的文件”\n\n## 从源码构建\n\n\n如果尚未安装 `make`，请先安装：\n```bash\nsudo add-apt-repository universe -y\nsudo apt update\nsudo apt install make\n```\n\n\n要将 `k7` CLI 和 API 构建成 `.deb` 包：\n```shell\nmake build\n```\n\n随后可以通过以下命令安装：\n```shell\nsudo make install\n```\n\n若需卸载：\n```shell\nsudo make uninstall\n```\n\n注意：如果不是首次安装，建议在重新安装前先运行 `make uninstall`，以避免 `.deb` 包中残留旧版本的缓存文件。\n\n### 快速开发流程\n\n为了加快 CLI 的开发迭代，您可以使用 `dev.sh` 脚本直接运行 `k7` 命令，而无需每次重新构建二进制文件：\n\n```shell\n# 基本命令\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh list\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh create\n\n# 带选项的安装\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install -v\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install --disk \u002Fdev\u002Fnvme2n1\n\n\n# 带选项创建沙箱\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh create --name test --image alpine:latest\n```\n\n该脚本使用 `uv run` 直接执行 CLI 及其所有依赖项，因此您可以立即测试更改，而无需每次都运行 `make build`。这在迭代 CLI 代码时尤为有用。\n\n### 构建并运行 API 容器\n\n本地开发镜像：\n```bash\n# 在本地构建 API 镜像\nmake api-build-local\n\n# 使用本地镜像运行 API（无需拉取）\nmake api-run-local\n```\n\n\n### 从源码构建 katakate Python SDK\n\n推荐使用 `uv`：\n\n```bash\n# 创建虚拟环境\nuv venv .venv-build\n. .venv-build\u002Fbin\u002Factivate\n\n# 以可编辑模式直接从源码安装\nuv pip install -e .\n```\n\n## 安全性\n\nK7 沙箱默认通过多层安全机制进行加固：\n\n- **虚拟机隔离**：Kata Containers 使用 Firecracker 提供的轻量级虚拟机实现硬件级别的隔离。\n  - 虚拟机进一步被限制在由 Jailer 实现的 chroot 环境中。\n  - 启用了 Kata 的 Seccomp 限制。\n\n- **Linux 功能集**：为增强纵深防御，所有 Linux 功能集默认被丢弃（`drop: ALL`）。\n  - 只能通过 `cap_add` 参数显式添加所需的权限。\n  - `allow_privilege_escalation` 始终设置为 `false`。\n  - Seccomp 配置文件：`RuntimeDefault`。\n\n- **非 root 运行**：可选地以非 root 用户（UID 65532）运行容器和 Pod：\n  - `container_non_root`：以非 root 用户运行主容器，并禁用权限提升。\n  - `pod_non_root`：以非 root 用户运行整个 Pod，确保文件系统所有权一致（UID\u002FGID\u002FFSGroup 为 65532）。\n\n- **API 安全**：\n  - API 密钥以 SHA256 哈希存储，并采用防时序攻击的比较方式。\n  - 强制设置过期时间，并记录最后使用时间戳。\n  - 文件存储权限为 600（默认路径为 `\u002Fetc\u002Fk7\u002Fapi_keys.json`）。\n\n- **网络策略**：虚拟机沙箱实现完全的网络隔离。\n  - **入口隔离**：默认阻止所有虚拟机之间的通信，防止沙箱间访问。\n  - **出口封锁**：通过基于 CIDR 的 Kubernetes NetworkPolicy 控制出站流量。\n  - 当出口被封锁时，DNS 请求将被阻止；仅允许访问 `egress_whitelist` 中的 IP 或 CIDR。\n  - 仍保留通过 `kubectl exec` 和 `k7 shell` 的管理访问权限（这些操作使用 Kubernetes API，而非 Pod 网络）。\n  - 即将集成 Cilium，以支持域名白名单功能。\n\n更多安全特性目前正在规划中，包括集成 AppArmor。\n\n## 打包与发布\n\n- 项目结构使用 `src\u002F` 目录：\n  - CLI、API 和核心代码位于 `src\u002Fk7\u002F` 下。\n  - SDK 位于 `src\u002Fkatakate\u002F` 下。\n- 根据打包目标，仅针对 `katakate` SDK 进行打包；`src\u002Fk7\u002F` 下的资源不属于 PyPI 发布内容。\n- `MANIFEST.in` 文件（用于 `katakate` SDK）应仅包含 `LICENSE` 和 `README.md` 等必要文件。而 `src\u002Fk7\u002Fdeploy\u002F*` 中的部署相关资源则属于 Debian\u002FCLI 打包流程，而非 PyPI 包的一部分。\n- `katakate` 的 `setup.py` 位于仓库根目录，并从 `src\u002F` 目录中打包。\n- CLI 的 Debian 包通过 `src\u002Fk7\u002Fcli\u002Fbuild.sh` 构建，生成 `dist\u002Fk7_\u003Cversion>_amd64.deb` 和 `dist\u002Fk7_\u003Cversion>_arm64.deb`。\n- CI 流水线（标记为 `v*`）可以发布 PyPI 版本的 SDK，并上传 `.deb` 构建产物。\n\n\n\n## 已知问题\n\n- 尽管已正确传递给 Kata 的配置，并且 Jailer 进程也已启动，但目前看来 Jailer 似乎并未生效。这可能是由于使用了 Kubernetes Secrets 导致的兼容性问题。该问题正在调查中。","# Katakate (k7) 快速上手指南\n\nKatakate (k7) 是一个开源的自托管安全 VM 沙箱平台，专为大规模运行不可信代码（如 AI Agent）而设计。它基于 Kubernetes、Kata Containers 和 Firecracker 构建，提供轻量级且硬件隔离的执行环境。\n\n## 1. 环境准备\n\n### 系统要求\n- **操作系统**: Ubuntu (amd64 或 arm64)。\n- **硬件虚拟化**: 必须支持并开启 KVM。\n  - 检查命令：`ls \u002Fdev\u002Fkvm` (文件需存在)。\n  - **云服务器注意**: 大多数普通 VPS 不支持嵌套虚拟化。推荐使用专用服务器（Bare Metal）或特定实例：\n    - AWS: `.metal` 实例\n    - GCP: 开启 `--enable-nested-virtualization` 的实例\n    - 阿里云\u002F腾讯云：需选择支持嵌套虚拟化的专有宿主机或特定规格。\n- **磁盘**: 需要一块**未格式化、未分区**的裸盘（Raw Disk），用于 k7 自动配置 LVM thin-pool 以优化存储。\n  - ⚠️ **警告**: 安装过程会清空该磁盘数据。\n\n### 前置依赖\n在节点上安装以下基础工具：\n\n```bash\n# 更新源并安装 Ansible\nsudo add-apt-repository universe -y\nsudo apt update\nsudo apt install -y ansible\n\n# 安装 Docker 和 Docker Compose (用于运行 API)\ncurl -fsSL https:\u002F\u002Fget.docker.com | sh\n```\n\n> **提示**: 确保当前用户已加入 `docker` 组，以便无需 sudo 运行 Docker 命令：\n> `sudo usermod -aG docker $USER` (需重新登录生效)\n\n## 2. 安装步骤\n\n### 安装 k7 CLI\n通过官方 PPA 源安装命令行工具：\n\n```bash\nsudo add-apt-repository ppa:katakate.org\u002Fk7\nsudo apt update\nsudo apt install k7\n```\n\n### 初始化节点\n运行安装命令，k7 将自动部署 Kubernetes (K3s)、Kata、Firecracker 等组件，并配置存储池。\n\n```bash\n# 自动检测并使用可用的裸盘\nsudo k7 install\n\n# 或者指定具体的裸盘设备（例如 \u002Fdev\u002Fnvme2n1）\n# sudo k7 install --disk \u002Fdev\u002Fnvme2n1\n```\n\n安装完成后，终端会显示 `✅ Installation completed successfully!`。\n\n## 3. 基本使用\n\n### 方式一：使用 CLI 直接管理（单机模式）\n\n1. **创建配置文件** (`k7.yaml`)\n   在当前目录创建 `k7.yaml`，定义沙箱参数：\n\n   ```yaml\n   name: my-sandbox-123\n   image: alpine:latest\n   namespace: default\n\n   # 可选：限制网络出口（白名单模式）\n   egress_whitelist:\n     - \"10.0.0.5\u002F32\"\n\n   # 可选：资源限制\n   limits:\n     cpu: \"1\"\n     memory: \"1Gi\"\n     ephemeral-storage: \"2Gi\"\n\n   # 可选：启动前执行的脚本（可用于安装依赖）\n   before_script: |\n     apk add --no-cache git curl\n   ```\n\n2. **常用命令**\n\n   ```bash\n   # 创建沙箱\n   k7 create\n\n   # 查看沙箱列表\n   k7 list\n\n   # 删除指定沙箱\n   k7 delete my-sandbox-123\n\n   # 删除所有沙箱\n   k7 delete-all\n   ```\n\n### 方式二：使用 Python SDK 远程调用\n\n如果你启动了 API 服务（`k7 start-api`），可以使用 Python 进行编程控制。\n\n1. **安装 SDK**\n   ```bash\n   pip install katakate\n   # 如需异步支持：pip install \"katakate[async-sdk]\"\n   ```\n\n2. **代码示例**\n\n   ```python\n   from katakate import Client\n\n   # 初始化客户端\n   k7 = Client(\n     endpoint='https:\u002F\u002F\u003Cyour-api-endpoint>', \n     api_key='your-generated-api-key'\n   )\n\n   # 创建沙箱\n   sb = k7.create({\n       \"name\": \"my-python-sandbox\",\n       \"image\": \"alpine:latest\"\n   })\n\n   # 执行命令\n   result = sb.exec('echo \"Hello from K7 Sandbox\"')\n   print(result['stdout'])\n\n   # 清理沙箱\n   sb.delete()\n   ```\n\n### 开发调试技巧\n如果在修改 CLI 源码进行开发，可使用 `dev.sh` 避免反复编译：\n```bash\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh install\n.\u002Fsrc\u002Fk7\u002Fcli\u002Fdev.sh create --name test --image alpine:latest\n```","某 AI 初创公司构建了一个代码解释器 Agent，允许用户上传 Python 脚本进行数据分析和可视化，系统需自动执行这些不可信的第三方代码。\n\n### 没有 k7 时\n- **安全风险高**：传统 Docker 容器共享宿主机内核，恶意代码极易通过容器逃逸攻击窃取服务器敏感数据或控制整个集群。\n- **资源隔离差**：多个用户的计算任务在同一节点争抢资源，单个死循环脚本即可导致整个服务响应停滞，影响其他正常业务。\n- **启动速度慢**：为追求安全而采用的重型虚拟机方案启动耗时数秒，无法满足 AI Agent 对代码执行“秒级甚至毫秒级”响应的实时性要求。\n- **运维成本高**：自行搭建和维护基于 Kata Containers 或 Firecracker 的底层架构极其复杂，团队需耗费大量精力处理网络、存储快照等基础设施问题。\n\n### 使用 k7 后\n- **内核级安全隔离**：k7 利用 Firecracker 微虚拟机技术，为每个代码任务提供独立的轻量级内核，彻底阻断容器逃逸风险，确保恶意代码无法触及宿主机。\n- **弹性资源调度**：基于 Kubernetes 编排，k7 能高效管理成千上万个沙箱实例，自动隔离异常消耗资源的任务，保障核心服务稳定运行。\n- **极速冷启动**：得益于优化的镜像快照技术，k7 将沙箱启动时间压缩至亚秒级，让用户感觉代码是即时执行的，大幅提升交互体验。\n- **开箱即用**：通过简单的 CLI 或 Python SDK 即可部署自托管环境，团队无需深究底层虚拟化细节，专注于上层 AI 业务逻辑的开发。\n\nk7 让企业在拥有公有云般安全隔离能力的同时，保留了私有化部署的成本优势与控制权，是大规模运行不可信 AI 代码的理想基石。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FKatakate_k7_d4280968.png","Katakate","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FKatakate_5d5eba27.png","",null,"https:\u002F\u002Fgithub.com\u002FKatakate",[79,83,87],{"name":80,"color":81,"percentage":82},"Python","#3572A5",88.2,{"name":84,"color":85,"percentage":86},"Shell","#89e051",10.7,{"name":88,"color":89,"percentage":90},"Makefile","#427819",1.1,776,21,"2026-04-17T08:34:39","Apache-2.0",4,"Linux (Ubuntu amd64 or arm64)","未说明 (当前主要基于 Firecracker VMM，未来计划支持 Qemu 以运行 GPU 工作负载)","未说明 (需根据运行的 VM 沙箱数量及配置自行规划，示例配置中提及单沙箱可限制为 1Gi)",{"notes":100,"python":101,"dependencies":102},"1. 必须拥有支持硬件虚拟化 (KVM) 的主机，可通过 `ls \u002Fdev\u002Fkvm` 检查。云服务商通常需使用专用裸金属实例或开启嵌套虚拟化的特定机型 (如 AWS .metal, GCP 带标志位实例等)。2. 节点必须配备一块未格式化、未分区的原始磁盘 (Raw Disk)，用于 k7 配置 LVM thin-pool 以高效管理存储。3. 客户端仅需安装 Python 及 katakate SDK 即可通过 API 控制。4. 项目目前处于 Beta 阶段并正在进行安全审查，处理高敏感度工作负载时需谨慎。","较新版本 (Recent Python, 具体版本未指定，SDK 可通过 pip 安装)",[103,104,105,106,107,108,109,110],"Kubernetes (K3s)","Kata Containers","Firecracker","Jailer","Docker & Docker Compose","Ansible","Devmapper Snapshotter (LVM thin-pool)","KVM (硬件虚拟化支持)",[45,35,13],[113,114,115,116,117,118,119,120,121,122],"agents","code","firecracker","kata","kubernetes","virtual-machine","virtualization","sandbox","security","self-hosted","2026-03-27T02:49:30.150509","2026-04-19T03:06:37.714333",[126,131,136,141,145,149],{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},41466,"如何在 M3 MacBook Pro 的 ARM Ubuntu 虚拟机中运行 k7？","要在 M3 Mac 上运行，需要启用嵌套虚拟化。具体步骤如下：\n1. 使用 colima 启动带有嵌套虚拟化的 VM（需要 M3+ 芯片和 macOS Sequoia+）：`colima start --nested-virtualization`。\n2. 或者使用 tart 创建 VM：\n   ```bash\n   dd if=\u002Fdev\u002Fzero of=vdc.img bs=1g count=110\n   tart clone ghcr.io\u002Fcirruslabs\u002Fubuntu:latest ubuntu\n   tart set ubuntu --cpu 11\n   tart set ubuntu --memory 11000\n   tart run ubuntu --nested --disk=vdc.img\n   ```\n3. 由于架构差异，apt 仓库安装可能失败，建议从源码构建。需移除 `debian\u002Frules`、`src\u002Fk7\u002Fcli\u002Fbuild.sh` 和 `Dockerfile.cli` 中的 `--platform=linux\u002Famd64` 标志。\n4. 应用相关 PR 补丁后执行 `make build` 和 `make install`。\n注意：目前主要支持 Linux ARM，原生 Mac ARM 支持仍在开发中。","https:\u002F\u002Fgithub.com\u002FKatakate\u002Fk7\u002Fissues\u002F3",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},41467,"安装时遇到 'No device found for \u002Fdev\u002Fnvme...' 错误怎么办？","该错误通常是因为安装脚本未找到合适的空磁盘。解决方案如下：\n1. 确保系统中有一个可用的空磁盘。如果没有，可以参考官方指南清理磁盘：https:\u002F\u002Fdocs.katakate.org\u002Fguides\u002Futilities#wipe-a-disk-for-thin%E2%80%91pool-provisioning\n2. 使用 `lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,FSTYPE` 查看磁盘情况。\n3. 更新代码到最新版（`git pull`），重新构建并安装：\n   ```bash\n   make uninstall\n   make build\n   make install\n   ```\n4. 使用新增的 `--disk` 参数手动指定磁盘路径进行安装：\n   ```bash\n   k7 install --disk \u002Fdev\u002F[你的磁盘设备名] -v\n   ```\n   加上 `-v` 参数可以查看详细的磁盘选择日志。","https:\u002F\u002Fgithub.com\u002FKatakate\u002Fk7\u002Fissues\u002F1",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},41468,"k7 在哪些云服务商上支持硬件虚拟化？","k7 支持多种提供硬件虚拟化功能的云服务商。目前已确认 DigitalOcean 支持该功能并可用于生产环境。如果您在其他云提供商（如 AWS, GCP, Azure 等）上成功运行，也欢迎反馈以便更新支持列表。","https:\u002F\u002Fgithub.com\u002FKatakate\u002Fk7\u002Fissues\u002F2",{"id":142,"question_zh":143,"answer_zh":144,"source_url":130},41469,"为什么每个 Pod 会有约 50MB 的开销？","这 50MB 的开销主要来源于 Kata Containers 组件（包括 agent 和 rootfs）以及内核部分，而非 Firecracker 虚拟机监控器。Firecracker 本身的内存开销非常小。这是使用 Kata 运行时实现强隔离性的正常代价。",{"id":146,"question_zh":147,"answer_zh":148,"source_url":130},41470,"在 Ubuntu ARM 上通过 apt 安装失败怎么办？","在 Ubuntu ARM 架构上，默认的 apt 源可能不包含 k7 包，或者 `add-apt-repository` 命令未预装。解决方法：\n1. 先安装必要工具：`sudo apt install -y software-properties-common`。\n2. 如果添加仓库后仍找不到包（因架构差异），建议直接从源码构建。\n3. 从源码构建时，务必移除构建脚本中硬编码的 `--platform=linux\u002Famd64` 标志，以确保在 ARM 架构上正确编译。",{"id":150,"question_zh":151,"answer_zh":152,"source_url":135},41471,"如何为 k7 安装指定特定的磁盘或调整存储池大小？","现在 `k7 install` 命令支持 `--disk` 标志，允许用户指定用于 LVM 池的原始磁盘设备。例如：`k7 install --disk \u002Fdev\u002Fsdb`。\n如果需要更细粒度的控制（如调整池大小、元数据池大小等），维护者表示可以添加相应参数。目前对于多节点设置，显式指定磁盘是必需的。如果遇到自动检测磁盘失败的情况，请优先使用此标志手动指定。",[]]