卡塔卡特

面向大规模 AI 计算的自托管安全虚拟机沙箱

📸 📸

卡塔卡特 致力于轻松创建、管理和编排轻量级的安全虚拟机沙箱，以大规模执行不受信任的代码。它基于久经考验的 VM 隔离技术，结合 Kata、Firecracker 和 Kubernetes 构建而成。最初是为了满足需要大规模运行任意代码的 AI 代理而设计，但它也非常适用于：

• 自定义无服务器架构（类似 AWS Fargate，但由您自己掌控）
• 增强型 CI/CD 运行器（无需担心 Docker-in-Docker 的风险）
• 用于 AI dApp 的区块链执行层

100% 开源（Apache‑2.0）。如需技术支持，请发送邮件至：hi@katakate.org

技术栈

卡塔卡特 基于以下技术构建：

• Kubernetes 用于编排，采用 K3s，该版本已具备生产就绪能力，非常适合边缘节点；
• Kata 将容器封装为轻量级虚拟机；
• Firecracker 作为首选的虚拟机管理程序，具有超快启动速度、极小的资源占用和最小化攻击面；
• Devmapper Snapshotter 结合 逻辑卷精简池配置 技术，可高效利用单个节点上数十个虚拟机共享的磁盘空间。

即将推出

• 🛠️ 在 虚拟机沙箱内部 支持 Docker build / run / compose
• 🌐 多节点集群功能，支持分布式工作负载
• 🔍 基于 Cilium FQDN 的 DNS 解析，可安全地白名单域名，而不仅仅是 IP 地址段
• ⚙️ 支持其他 VMM，例如 Qemu，以处理 GPU 工作负载

📋 完整功能路线图及项目优先级，请参阅 ROADMAP.md。

注： 卡塔卡特目前处于 测试阶段，并正在进行安全审查。请谨慎用于高度敏感的工作负载。

使用方法

使用时您需要：

• 承载虚拟机沙箱的 节点
• 发送请求的 客户端

我们提供：

• CLI：直接在节点上使用 --> apt install k7
• API：部署在主节点上 --> k7 start-api
• Python SDK：与 API 通信的同步/异步 Python 客户端 --> pip install katakate

当前要求

对于节点

• 主机操作系统为 Ubuntu（amd64 或 arm64）。
• 必须启用并可访问硬件虚拟化（KVM）。
  • 检查命令：ls /dev/kvm 应显示文件存在。
  • 通常情况下，您自己的 Linux 机器都支持此功能。
  • 在云服务提供商中情况各异：
    • Hetzner（我目前唯一测试过的厂商）仅在其“Robot”专用实例上支持，即 robot.hetzner.com。
    • AWS：仅限 .metal EC2 实例。
    • GCP：大多数实例均支持虚拟化，只需添加 --enable-nested-virtualization 标志即可。
    • Azure：Dv3、Ev3、Dv4、Ev4、Dv5、Ev5（Intel/AMD x86）或 Dpdsv5、Dpldsv5、Epsv5（ARM64）。
    • DigitalOcean：启用嵌套虚拟化的高端 Intel 和 AMD Droplet。
    • 其他云服务商：一般而言，云 VPS 不会暴露硬件虚拟化功能，因此建议选择专用服务器或裸金属服务器。
• 一块原始磁盘（未格式化、未分区），用于 k7 配置的精简池，以实现沙箱的高效磁盘使用。
  • 使用 ./utils/wipe-disk.sh /your/disk 可在配置前将磁盘彻底清空。注意：此操作具有破坏性，会删除数据、分区、格式化信息以及 SWRAID 等内容。
• Ansible（用于安装程序）：

  sudo add-apt-repository universe -y
  sudo apt update
  sudo apt install -y ansible
  

• Docker 和 Docker Compose（用于 API）：

  curl -fsSL https://get.docker.com | sh
  

已验证的部署方案：

• Hetzner Robot 实例，配备 Ubuntu 24.04，架构为 x86_64 或 ARM64，并额外订购了一块空白磁盘 nvme2n1 用于精简池配置。有关设置指南，请参阅 PDF 文件：tutorials/k7_hetzner_node_setup.pdf。

对于客户端

只需最新版 Python 即可。

快速入门

准备您的节点

首先，在将托管虚拟机的 Linux 服务器上安装 k7：

sudo add-apt-repository ppa:katakate.org/k7
sudo apt update
sudo apt install k7

然后让 k7 为您准备好节点及其所有组件：

$  k7 install
当前任务：提醒您注销并重新登录以使组更改生效
  在 1 个主机上安装 K7... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:01:41
✅ 安装成功完成！

您可以选择添加 -v 参数以获取详细输出。

系统还会告知您为 LVM 薄池自动选择的原始磁盘。如果您希望明确指定磁盘，可以使用以下命令：

k7 install --disk /dev/nvme2n1

此操作将安装并连接以下组件：

• Kubernetes（K3s 生产就绪发行版）
• Kata（用于容器虚拟化）
• Firecracker（作为虚拟机管理器）
• Jailer（进一步将 Firecracker 虚拟机隔离到 chroot 环境中以增强安全性）
• devmapper 快照程序，配合薄池配置逻辑卷，实现虚拟机高效磁盘存储

设计周全：配置更新不会影响您现有的 Docker 或 containerd 配置。我们选择使用 K3s 自带的 containerd，以尽量减少干扰。不过，安装可能会覆盖已有的 K3s、Kata、Firecracker 和 Jailer 安装。

CLI 使用

您可以通过 CLI 直接在节点上运行工作负载。要创建一个沙箱，只需为其编写一个 YAML 配置文件即可。

k7.yaml 示例：

name: my-sandbox-123
image: alpine:latest
namespace: default

# 可选：限制出站流量（安全模式：仅允许您自己的出站代理 IP）
egress_whitelist:
  - "10.0.0.5/32"     # 您的私有出站代理/网关

# 可选：资源限制
limits:
  cpu: "1"
  memory: "1Gi"
  ephemeral-storage: "2Gi"

# 可选：在容器启动时运行一次 before_script。网络限制将在 before_script 执行后生效，因此您可以在此处安装软件包、拉取 Git 仓库等。
before_script: |
  apk add --no-cache git curl

# 可选：从文件加载环境变量。这些变量在 before_script 和沙箱中均可用。
env_file: path/to/your/secrets/.env

运行命令

# 创建沙箱（默认使用当前目录下的 k7.yaml，也可通过 -f myfile.yaml 指定）
k7 create

# 列出沙箱
k7 list

# 删除沙箱
k7 delete my-sandbox-123

# 删除所有沙箱。您也可以指定命名空间。
k7 delete-all

API 使用

如果您希望远程管理工作负载，可以直接使用 API：

# 启动 API 服务器（容器化，并通过 Cloudflared 支持 SSL）
k7 start-api

# 生成 API 密钥
k7 generate-api-key my-key1

请确保您的用户属于 Docker 组，以便有权启动或停止 API。

至于密钥的生成、列出和撤销，可能需要 sudo 或 root 权限。

Python SDK 使用

当您的 k7 API 启动后，使用起来非常简单。

通过以下命令安装 Python SDK：

pip install katakate

如果您需要异步支持：

pip install "katakate[async-sdk]"

然后可以这样使用：

from katakate import Client

k7 = Client(
  endpoint='https://<your-endpoint>', 
  api_key='your-key')

# 创建沙箱
sb = k7.create({
    "name": "my-sandbox",
    "image": "alpine:latest"
})

# 执行代码
result = sb.exec('echo "Hello World"')
print(result['stdout'])

# 列出所有沙箱
sandboxes = k7.list()

# 删除沙箱
sb.delete()

异步版本

import asyncio
from katakate import AsyncClient

async def main():
    k7 = AsyncClient(
      endpoint='https://<your-endpoint>', 
      api_key='your-key'
    )
    print(await k7.list())
    await k7.aclose()

asyncio.run(main())

教程

• 使用 K7 沙箱工具的 LangChain ReAct 代理
  • 路径：tutorials/langchain-react-agent
  • 设置：将 .env.example 复制到 .env 并填写 K7_ENDPOINT/K7_API_KEY/OPENAI_API_KEY
  • 运行：python agent.py
  • 尝试向它提问任何问题！例如：“列出 / 目录下的文件”

从源码构建

如果尚未安装 make，请先安装：

sudo add-apt-repository universe -y
sudo apt update
sudo apt install make

要将 k7 CLI 和 API 构建成 .deb 包：

make build

随后可以通过以下命令安装：

sudo make install

若需卸载：

sudo make uninstall

注意：如果不是首次安装，建议在重新安装前先运行 make uninstall，以避免 .deb 包中残留旧版本的缓存文件。

快速开发流程

为了加快 CLI 的开发迭代，您可以使用 dev.sh 脚本直接运行 k7 命令，而无需每次重新构建二进制文件：

# 基本命令
./src/k7/cli/dev.sh install
./src/k7/cli/dev.sh list
./src/k7/cli/dev.sh create

# 带选项的安装
./src/k7/cli/dev.sh install -v
./src/k7/cli/dev.sh install --disk /dev/nvme2n1


# 带选项创建沙箱
./src/k7/cli/dev.sh create --name test --image alpine:latest

该脚本使用 uv run 直接执行 CLI 及其所有依赖项，因此您可以立即测试更改，而无需每次都运行 make build。这在迭代 CLI 代码时尤为有用。

构建并运行 API 容器

本地开发镜像：

# 在本地构建 API 镜像
make api-build-local

# 使用本地镜像运行 API（无需拉取）
make api-run-local

从源码构建 katakate Python SDK

推荐使用 uv：

# 创建虚拟环境
uv venv .venv-build
. .venv-build/bin/activate

# 以可编辑模式直接从源码安装
uv pip install -e .

安全性

K7 沙箱默认通过多层安全机制进行加固：

• 虚拟机隔离：Kata Containers 使用 Firecracker 提供的轻量级虚拟机实现硬件级别的隔离。

  • 虚拟机进一步被限制在由 Jailer 实现的 chroot 环境中。
  • 启用了 Kata 的 Seccomp 限制。

• Linux 功能集：为增强纵深防御，所有 Linux 功能集默认被丢弃（drop: ALL）。

  • 只能通过 cap_add 参数显式添加所需的权限。
  • allow_privilege_escalation 始终设置为 false。
  • Seccomp 配置文件：RuntimeDefault。

• 非 root 运行：可选地以非 root 用户（UID 65532）运行容器和 Pod：

  • container_non_root：以非 root 用户运行主容器，并禁用权限提升。
  • pod_non_root：以非 root 用户运行整个 Pod，确保文件系统所有权一致（UID/GID/FSGroup 为 65532）。

• API 安全：

  • API 密钥以 SHA256 哈希存储，并采用防时序攻击的比较方式。
  • 强制设置过期时间，并记录最后使用时间戳。
  • 文件存储权限为 600（默认路径为 /etc/k7/api_keys.json）。

• 网络策略：虚拟机沙箱实现完全的网络隔离。

  • 入口隔离：默认阻止所有虚拟机之间的通信，防止沙箱间访问。
  • 出口封锁：通过基于 CIDR 的 Kubernetes NetworkPolicy 控制出站流量。
  • 当出口被封锁时，DNS 请求将被阻止；仅允许访问 egress_whitelist 中的 IP 或 CIDR。
  • 仍保留通过 kubectl exec 和 k7 shell 的管理访问权限（这些操作使用 Kubernetes API，而非 Pod 网络）。
  • 即将集成 Cilium，以支持域名白名单功能。

更多安全特性目前正在规划中，包括集成 AppArmor。

打包与发布

• 项目结构使用 src/ 目录：
  • CLI、API 和核心代码位于 src/k7/ 下。
  • SDK 位于 src/katakate/ 下。
• 根据打包目标，仅针对 katakate SDK 进行打包；src/k7/ 下的资源不属于 PyPI 发布内容。
• MANIFEST.in 文件（用于 katakate SDK）应仅包含 LICENSE 和 README.md 等必要文件。而 src/k7/deploy/* 中的部署相关资源则属于 Debian/CLI 打包流程，而非 PyPI 包的一部分。
• katakate 的 setup.py 位于仓库根目录，并从 src/ 目录中打包。
• CLI 的 Debian 包通过 src/k7/cli/build.sh 构建，生成 dist/k7_<version>_amd64.deb 和 dist/k7_<version>_arm64.deb。
• CI 流水线（标记为 v*）可以发布 PyPI 版本的 SDK，并上传 .deb 构建产物。

已知问题

• 尽管已正确传递给 Kata 的配置，并且 Jailer 进程也已启动，但目前看来 Jailer 似乎并未生效。这可能是由于使用了 Kubernetes Secrets 导致的兼容性问题。该问题正在调查中。

Katakate (k7) 快速上手指南

Katakate (k7) 是一个开源的自托管安全 VM 沙箱平台，专为大规模运行不可信代码（如 AI Agent）而设计。它基于 Kubernetes、Kata Containers 和 Firecracker 构建，提供轻量级且硬件隔离的执行环境。

1. 环境准备

系统要求

• 操作系统: Ubuntu (amd64 或 arm64)。
• 硬件虚拟化: 必须支持并开启 KVM。
  • 检查命令：ls /dev/kvm (文件需存在)。
  • 云服务器注意: 大多数普通 VPS 不支持嵌套虚拟化。推荐使用专用服务器（Bare Metal）或特定实例：
    • AWS: .metal 实例
    • GCP: 开启 --enable-nested-virtualization 的实例
    • 阿里云/腾讯云：需选择支持嵌套虚拟化的专有宿主机或特定规格。
• 磁盘: 需要一块未格式化、未分区的裸盘（Raw Disk），用于 k7 自动配置 LVM thin-pool 以优化存储。
  • ⚠️ 警告: 安装过程会清空该磁盘数据。

前置依赖

在节点上安装以下基础工具：

# 更新源并安装 Ansible
sudo add-apt-repository universe -y
sudo apt update
sudo apt install -y ansible

# 安装 Docker 和 Docker Compose (用于运行 API)
curl -fsSL https://get.docker.com | sh

提示: 确保当前用户已加入 docker 组，以便无需 sudo 运行 Docker 命令： sudo usermod -aG docker $USER (需重新登录生效)

2. 安装步骤

安装 k7 CLI

通过官方 PPA 源安装命令行工具：

sudo add-apt-repository ppa:katakate.org/k7
sudo apt update
sudo apt install k7

初始化节点

运行安装命令，k7 将自动部署 Kubernetes (K3s)、Kata、Firecracker 等组件，并配置存储池。

# 自动检测并使用可用的裸盘
sudo k7 install

# 或者指定具体的裸盘设备（例如 /dev/nvme2n1）
# sudo k7 install --disk /dev/nvme2n1

安装完成后，终端会显示 ✅ Installation completed successfully!。

3. 基本使用

方式一：使用 CLI 直接管理（单机模式）

1. 创建配置文件 (k7.yaml) 在当前目录创建 k7.yaml，定义沙箱参数：

   name: my-sandbox-123
   image: alpine:latest
   namespace: default
   
   # 可选：限制网络出口（白名单模式）
   egress_whitelist:
     - "10.0.0.5/32"
   
   # 可选：资源限制
   limits:
     cpu: "1"
     memory: "1Gi"
     ephemeral-storage: "2Gi"
   
   # 可选：启动前执行的脚本（可用于安装依赖）
   before_script: |
     apk add --no-cache git curl
   

2. 常用命令

   # 创建沙箱
   k7 create
   
   # 查看沙箱列表
   k7 list
   
   # 删除指定沙箱
   k7 delete my-sandbox-123
   
   # 删除所有沙箱
   k7 delete-all
   

方式二：使用 Python SDK 远程调用

如果你启动了 API 服务（k7 start-api），可以使用 Python 进行编程控制。

1. 安装 SDK

   pip install katakate
   # 如需异步支持：pip install "katakate[async-sdk]"
   

2. 代码示例

   from katakate import Client
   
   # 初始化客户端
   k7 = Client(
     endpoint='https://<your-api-endpoint>', 
     api_key='your-generated-api-key'
   )
   
   # 创建沙箱
   sb = k7.create({
       "name": "my-python-sandbox",
       "image": "alpine:latest"
   })
   
   # 执行命令
   result = sb.exec('echo "Hello from K7 Sandbox"')
   print(result['stdout'])
   
   # 清理沙箱
   sb.delete()
   

开发调试技巧

如果在修改 CLI 源码进行开发，可使用 dev.sh 避免反复编译：

./src/k7/cli/dev.sh install
./src/k7/cli/dev.sh create --name test --image alpine:latest