SDK 默认使用托管端点。通过设置 `MITOS_BASE_URL`，相同的代码可以在你自己的集群或独立的沙箱服务器上运行。密钥从参数或 `MITOS_API_KEY` 中解析，并且永远不会被记录。

### 2. 创建沙箱并运行代码```python
import mitos

sb = mitos.create("python")                  # Ready microVM sandbox (~27 ms warm-claim)
print(sb.exec("echo hello").stdout)          # hello

# Files and a stateful code interpreter hang off the same flat handle.
sb.files.write("/workspace/plan.txt", "draft")
print(sb.run_code("import math; math.sqrt(144)").text)   # 12.0

异步客户端暴露了相同的接口：`await mitos.aio.create("python")` 返回一个 `AsyncDirectSandbox`，具有相同的 `exec` / `run_code` / `files` / `create_pty` / `fork` / `terminate`。

阻塞式 `exec` 和 `run_code` 在 husk 默认模式下工作。流式 exec（`sb.exec(..., on_stdout=...)`）、后台进程（`sb.exec_background(...)`）和交互式 PTY（`sb.create_pty()`）目前在 engine 路径上运行，并且正在被引入到 husk 默认模式；`run_code` 返回一个故障关闭的 `KernelUnavailable`，直到 kernel 随 husk 基础镜像一起提供。

### 以你的方式运行

相同的引擎，相同的 API，更多的入口。深入了解只需点击[文档](https://mitos.run/docs)。

**每种语言，两种模式。** 每个 SDK 在 **直接模式**（独立或托管）下使用相同的 sandbox-server REST API，并且每个 SDK 也具有 **集群模式**（一个 `AgentRun`，通过 Kubernetes API 驱动 `mitos.run/v1` CRD）。默认池的命名在所有六种语言中逐字节完全相同。

| 语言 | 安装 | 直接模式 | 集群模式 | SDK 文档 |
|---|---|---|---|---|
| Python | `pip install mitos-run` | 同步 + 异步 | `AgentRun` | [sdk/python](https://github.com/mitos-run/mitos/blob/HEAD/sdk/python) |
| TypeScript | `npm i @mitos/sdk` | 是 | `AgentRun` | [sdk/typescript](https://github.com/mitos-run/mitos/blob/HEAD/sdk/typescript/README.md) |
| Go | `go get github.com/mitos-run/mitos/sdk/go` | 类型化，`errors.Is` 友好 | `AgentRun` | [sdk/go](https://github.com/mitos-run/mitos/blob/HEAD/sdk/go/README.md) |
| Ruby | gem（仅标准库） | 是 | `AgentRun` | [sdk/ruby](https://github.com/mitos-run/mitos/blob/HEAD/sdk/ruby/README.md) |
| Rust | crate（阻塞式） | 是 | `AgentRun` | [sdk/rust](https://github.com/mitos-run/mitos/blob/HEAD/sdk/rust/README.md) |
| Java | JDK 17（仅标准库） | 是 | `AgentRun` | [sdk/java](https://github.com/mitos-run/mitos/blob/HEAD/sdk/java/README.md) |

Go SDK 在自己的嵌套模块（`github.com/mitos-run/mitos/sdk/go`）中提供，因此导入它永远不会将控制器引入你的构建。

**自托管？相同代码。** Helm chart 部署的网关与托管服务运行的是同一个，因此上面的快速入门在您自己的集群上可以原样工作：将 `MITOS_BASE_URL` 指向您的网关，其余保持不变。托管和自托管是同一体验；只有 URL 和运营方不同。

**Kubernetes 原生控制，按需使用。** 对于以声明方式管理池的平台团队（GitOps、RBAC 范围内的自动化、operators），两层 `AgentRun` 路径跳过网关，直接通过 Kubernetes API 驱动 `mitos.run/v1` CRD：```python
from mitos import AgentRun

c = AgentRun()                                   # kubeconfig or in-cluster; autodetected
sb = c.sandbox("python", ready=True)             # claims a warm sandbox, waits Ready
print(sb.exec("python -c 'print(40 + 2)'").stdout)   # 42

fork_a, fork_b = sb.fork(2)                       # fork against shared warmed state
sb.terminate()

`mitos dev up` 在模拟引擎上启动一个单命令本地控制平面，用于
集群模式开发。一个 MCP 服务器（`mitos-mcp`）将沙箱作为 MCP
工具暴露给任何支持 MCP 的代理，并且一个 [Agent Skill](https://github.com/mitos-run/mitos/blob/HEAD/skills/mitos/SKILL.md)
教会支持技能（skill-aware）的代理该工作流。完整的安装矩阵（脚本、
Homebrew、deb/rpm、scoop/winget、校验和）位于
[mitos.run/docs/install](https://mitos.run/docs/install)。

**直接融入你已在使用的代理。** 每个适配器都是同一组原生操作（`exec`、`run_code`、`files`、`fork`）之上的轻量垫片（shim），且不硬依赖框架包：Claude Code 和 opencode（MCP 服务器 + 代理技能）、OpenAI Agents SDK、Claude Agent SDK、LangChain / deepagents、Vercel AI SDK / Pydantic AI / AutoGen / LlamaIndex（标准 MCP），以及为离开 [E2B](https://mitos.run/docs/migrating-from-e2b) 或 [Daytona](https://mitos.run/docs/migrating-from-daytona) 云的团队提供的“修改一处导入”迁移垫片。[集成中心](https://github.com/mitos-run/mitos/blob/HEAD/docs/integrations/README.md) 为每条路径编制了索引。

**安装 operator。**```bash
kubectl apply -k deploy/

**运行位置。** 唯一的节点要求是 `/dev/kvm` 加上标签 `mitos.run/kvm=true`，因此 mitos 可以安装在任何带有裸机或嵌套虚拟化 KVM 节点的 Kubernetes 集群上：

| 平台 | KVM 节点 | 指南 |
|---|---|---|
| 裸机（Talos、Hetzner） | 原生 `/dev/kvm` | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md)（一等参考） |
| AWS / EKS | `*.metal` 或嵌套虚拟化节点组 | 目前使用通用 chart；按云指南见 issue [#919](https://github.com/mitos-run/mitos/issues/919) |
| GKE | 嵌套虚拟化节点池 | 目前使用通用 chart；按云指南见 [#919](https://github.com/mitos-run/mitos/issues/919) |
| Azure / AKS | 支持嵌套虚拟化的 VM 规格 | 目前使用通用 chart；按云指南见 [#919](https://github.com/mitos-run/mitos/issues/919) |

chart 和 CRD 在所有平台上完全相同；只有提供 `/dev/kvm` 的节点池不同。

## 为什么选择 Mitos

Agent 沙箱需要快速、隔离的环境，让 agent 可以读写文件、安装包并运行不受信任的代码。每个现有方案都迫使你做出取舍：速度但没有所有权、隔离但无法分支、Kubernetes 原生但没有热启动、或者持久化被锁定在别人的云里。

- **实时分支一个运行中的 VM。** 对实时 microVM 进行 N 路写时复制（copy-on-write）分支：子 VM 在写入前共享父 VM 的内存页，因此每个分支都落在一个热、就绪的环境中。将一个 agent 分支成多个并行尝试。
- **约 27 ms 热认领激活。** Firecracker microVM 从内存快照恢复的时间在几十毫秒级别：在裸机参考节点上 P50 约 27 ms，可通过 [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh) 复现。
- **开源、可自托管、Kubernetes 原生。** 据我们所知，这是唯一同时具备这三点的运行时。你可以通过声明式 CRD（`mitos.run`）驱动整个生命周期。

两种运行方式：

- **自托管（当前可用）：** 任何带有 KVM 节点的 Kubernetes 集群。你的数据永远不会离开你的基础设施。裸机（Talos + Hetzner）是一等参考平台。
- **托管（进行中）：** 由我们运营的同一引擎和 API，面向希望获得毫秒级体验但不想管理节点的团队。

> 存在两条引擎路径。**husk pod 原生路径是默认路径**：每个 VM 运行在自己的非特权 pod 中，源 husk pod 对其运行中的 VM 做快照，使 N 个子 pod 通过 CoW 恢复该快照。**raw-forkd 路径**在 forkd 的进程内引擎中运行分支。除非明确标注 `engine path`，否则此处所有内容都基于 husk 默认路径运行。

沙箱不是 pod。Pod 作用域的 Kubernetes 机制（NetworkPolicy、ResourceQuota、PSA）管理的是 husk pod，而不是 microVM 内部的工作负载；沙箱是 VM，不是 husk pod，并且在我们提供等效机制的地方，会明确标注为我们的机制。完整的声明（claim）和执行数据路径以及组件图见 [mitos.run/docs/architecture](https://mitos.run/docs/architecture)。

## 基准测试

这里的每个数字都可以在真实 KVM 硬件上通过 [`bench/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/) 复现；任何读者无法重新生成的数字都不会发布（这是项目的“无未经证实声明”规则）。每一行都标明其测量内容以及复现它的确切命令。完整的逐次运行数据和硬件上下文见 [`bench/results/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/)。

### 托管环境下的交互时间（TTI），与 ComputeSDK 同行集合对比

交互时间（TTI）是唯一能与公开 [ComputeSDK benchmark](https://github.com/computesdk/benchmarks) 进行同类比较的指标——每个托管沙箱供应商都以此为衡量标准：时钟从 `create()` 开始，到一条命令真正在沙箱内 RUN 并返回时停止。

| 提供商 | TTI P50 | 衡量方式 |
|---|---|---|
| northflank | 95.9 ms | ComputeSDK 已发布 |
| **mitos** | **96.8 ms** | 我们的测试程序，`api.mitos.run` |
| daytona | 136.2 ms | ComputeSDK 已发布 |
| e2b | 365.6 ms | ComputeSDK 已发布 |

复现我们的数字和同行表格（同行数字读取自 ComputeSDK 发布的不变 commit，而非我们重新运行）：```sh
MITOS_API_KEY=... python3 bench/tti-latency.py 100        # our TTI, N=100
python3 bench/peer-tti.py --date 2026-07-09 \
  --ref 3eddee1a972bd49aea56fd6c16d238ca0a45dece            # the peer table

完整方法与硬件见 [bench/README.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/README.md)；结果见 [2026-06-19-bare-metal-fork-exec.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-19-bare-metal-fork-exec.md) 和 [2026-06-21-kvm-perf-correctness.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-21-kvm-perf-correctness.md)。

### 热认领激活（引擎层面，而非往返全程）

引擎自身的暖沙箱激活（快照加载 + 分支正确性握手 + 来宾就绪）在裸机参考节点上为 P50 ~27 毫秒，可通过 [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh) 复现。这个数字与上文端到端托管 TTI 不同且更小；拿引擎指标去对比竞争对手的 create-API 数字属于范畴错误，因此我们将两者分开陈述。

## 功能特性

husk 的 pod 原生路径是默认选项。目前少数能力仅在原始 forkd 的 `engine path` 上运行，并已标注，附有跟踪 issue 的链接。

### 性能

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 热认领激活 | 裸机参考节点上 P50 ~27 毫秒（快照加载 + 分支正确性握手 + 来宾就绪）；快照恢复约 6-16 毫秒；通过 CoW 页共享每个分支仅增加约 3 MiB 内存 | [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md) |
| 预快照池 | OCI 镜像被展开为 ext4 rootfs，并在快照前按你的 `init` 步骤预热，因此认领时没有冷启动 | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| CoW 内存共享 | 你只需为跨分支的独占页付费，而非为副本付费 | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| 内容寻址分发 | 分支仅通过 mTLS 从持有者处拉取缺失的 sha256 块；重建在版本兼容契约下传输增量 | [docs/snapshot-distribution.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/snapshot-distribution.md) |

### 隔离

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 每会话硬件隔离 | 每个沙箱一个专用内核（KVM/Firecracker）；在 husk 默认配置下，每个 VM 运行在各自的非特权、受 PSA 限制的 pod 中，即每 VM 边界 | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 无静默机密继承 | 持有机密的沙箱的实时分支会被拒绝，除非显式选择加入；凭据在认领时通过 vsock 注入，绝不会烘焙进快照 | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 默认拒绝出口流量 | pod 自身 netns 内的 pod 内 nftables 默认拒绝过滤器（与 CNI 无关），无条件阻断云元数据（169.254.169.254），并通过 pod 内 DNS 代理按 IP:port 和名称提供每模板白名单。已在真实 KVM 集群上端到端验证；来宾无法影响执行 | [mitos.run/docs/networking](https://mitos.run/docs/networking) |
| 静态加密 | 每作用域 LUKS2 容器，支持加密粉碎和 KMS 信封包装（位于 `--enable-encryption` 之后，失败即关闭）；HSM 支持的密钥和每工作区作用域为后续事项 | [docs/encryption.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/encryption.md) |

### Agent 开发体验

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 阻塞式 exec | 通过沙箱 API 返回正确的 stdout 和退出码 | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| 流式 exec 和 PTY | 增量 stdout/stderr、后台进程，以及令牌门控的交互式 WebSocket 终端（`engine path`） | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| 代码解释器 | 在所有 SDK 和 MCP 服务器中提供带状态内核和丰富多 MIME 结果的 `run_code`；在内核随 husk 基础镜像发布前，失败时关闭为 `KernelUnavailable` | [mitos.run/docs/mcp](https://mitos.run/docs/mcp) |
| LLM 可读错误 | 每次失败都携带 `{code, cause, remediation}`，由 SDK 解析为结构化的 `AgentRunError` | [docs/api/errors.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/api/errors.md) |

### Kubernetes 原生

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 声明式 CRD | `mitos.run/v1` 中的 `SandboxPool`、`Sandbox`（poolRef/fromSandbox/fromRevision 来源）、`Workspace`/`WorkspaceRevision`，支持卷拓扑和分支行为 | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Pod 原生执行 | 每个沙箱 VM 运行在非特权 pod 中（`/dev/kvm` 来自设备插件，而非 `privileged`），因此 CPU/内存请求是调度器的依据，PSA 治理 pod | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 容量感知调度 | 将 CoW 装箱调度到热持有者，CoW 感知的超卖预算，带原子槽位预留的 `MaxSandboxes` 主机 DoS 上限，以及类型化的 `NoCapacity` 背压而非让节点 OOM | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| 需求驱动自动扩缩容 | `SandboxPool.spec.autoscale` 将休眠 husk-pod 数量缩放至 `clamp(inUse + targetSpare, minWarm, maxWarm)`，并带防抖动冷却；固定池即 `minWarm == replicas` | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| 失败与 GC 语义 | 认领 TTL、孤儿 VM 清理、控制器重启对账、通过磁盘日志回收 forkd 崩溃、节点丢失处理、饱和背压，均经 CI 验证 | [docs/failure-gc.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/failure-gc.md) |

### 持久状态

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 持久可分支工作区 | `Workspace`/`WorkspaceRevision` CRD：独立于任何沙箱的持久、版本化、可分支的代理状态。`/workspace` 在启动时水合，已提交的修订在终止时通过内容寻址存储脱水。已在真实 KVM 集群上验证 create -> commit -> fork | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| 输出与差异 | `spec.lifetime.onTerminate.outputs` 将脱水收窄至列出的子树；`{diff: true}` 记录相对父 head 的内容哈希差异 | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Git 会合 | `{git}` 输出将每次尝试的分支推送到会合远程仓库（引擎推送；人工或 CI 合并）。目前在 husk 上为尽力而为 | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| 开发环境 URL | `mitos workspace serve <ws> --pool P` 热认领绑定到工作区的分支沙箱，并返回就绪的 `https://<label>.<expose-domain>/` URL；每个分支会话获得自己的 URL | [docs/recipes/dev-environment.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/recipes/dev-environment.md) |

### 可运维性

| 能力 | 你能获得什么 | 文档 |
|---|---|---|
| 指标与追踪 | 节点和控制器 Prometheus 指标、每次认领的 OpenTelemetry 追踪（`--otlp-endpoint`），以及可切换的结构化审计日志（`--audit-log`），记录命令/路径和字节数，绝不记录内容或机密 | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| CoW 感知计量 | 共享模板页集合只计一次，而非每个分支各计一次，因此计费和调度反映真实的物理占用 | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| 运维工具 | `kubectl mitos` 插件（`ls` / `ps`）和运维用 `GET /v1/metering` 报告 | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| 裸机一等公民 | Talos + Hetzner 是参考平台 | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) |
| 单用户首次运行 | 带单用户登录门的 k3s 快速入门（仅限 QA，非生产） | [docs/platforms/k3s-quickstart.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/k3s-quickstart.md) |

## 对比

只有当我们能使用本仓库中的脚本，在相同硬件上针对实际竞争对手重新生成正面对比的数字表格时，这里才适合展示它。该框架见 [#15](https://github.com/mitos-run/mitos/issues/15)。下表数字为**其他厂商发布的数字，针对不同操作、不同硬件、采用不同方法**：并非我们实测，也不构成正面对比声明。

| 运行时 | 已发布数字（他们的，非我们的） | 他们描述的操作 |
|---|---|---|
| Mitos（我们的，实测） | ~27 ms P50 | 裸机参考节点上的热认领激活 |
| E2B | ~150 ms | 沙箱创建 |
| Daytona | 低于 90 ms | 从快照创建 |
| Modal | 亚秒级 | 沙箱创建 |
| CodeSandbox SDK | ~863 ms / ~495 ms | 实时分支 / 内存恢复 |
| Fly Machines | < 1 s | 机器启动 |

当前可比较且真实存在的是定性帕累托图：开源、可自托管、k8s 原生、实时快照分支这四者的组合，正是 Mitos 独占的维度。

| | Mitos | E2B | Modal | Daytona | Morph | Cloudflare | Box | Agent Sandbox | Kata/KubeVirt | raw Firecracker |
|---|---|---|---|---|---|---|---|---|---|---|
| 每会话硬件隔离 | KVM microVM | microVM | gVisor | 容器/VM | microVM | V8 isolate | VM | Kata 选项 | KVM | KVM |
| 运行状态快照分支 | 是，核心原语 | 快照/恢复 | 内存快照 | 否 | 是（Infinibranch） | 否 | 磁盘分支 | 否 | 否 | 自建 |
| 暖池毫秒级认领 | 是（设计中心） | 暖池 | 暖池 | 工作区 | 是 | 即时隔离 | 未公布 | 1-3 秒冷启动 | 秒级 | 自建 |
| 持久可分支工作区 | Workspace CRD | 否 | 卷 | 工作区 | 是，专有 | 是（磁盘） | 否 | PVC | PVC | 否 |
| Kubernetes 原生 API | CRD | SaaS API | SaaS API | SaaS/OSS | SaaS API | SaaS API | 代理原生 CLI | CRD | CRD | 否 |
| 可自托管 | 是，任意 KVM 集群 | 部分 OSS | 否 | OSS 核心 | 否 | 否 | 否 | 是 | 是 | 是 |
| 托管选项 | 已规划（同一引擎） | 是 | 是 | 是 | 是 | 是 | 是（仅托管） | 否 | 否 | 否 |
| 数据留在你的基础设施上 | 是（自托管） | 否 | 否 | 部分 | 否 | 否 | 否 | 是 | 是 | 是 |
| 开源 | Apache 2.0 | 部分 | 否 | 部分 | 否 | 否 | 否 | Apache 2.0 | Apache 2.0 | Apache 2.0 |

SaaS 运行时（E2B、Modal、Daytona、Cloudflare）确实很快，但你的代理代码、数据和凭据运行在别人的基础设施上，且没有同等能力的自托管路径。Morph 以专有云的形式构建了正确的状态模型（分支/恢复）；我们的 Workspace 原语以 fork(2) 的速度、开源方式实现同样的语义。Agent Sandbox（k8s-sigs）在赢得 Kubernetes API 标准之争，但它没有快照分支引擎，因此我们提供一致性门面（`cmd/facade`）来成为其最快的后端，而非与之对抗（[docs/facade-conformance.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/facade-conformance.md)）。Kata、KubeVirt 和原始 Firecracker 为你提供隔离原语，但池、分支、分发和代理 API 层则留给你自己解决。

如果某个替代方案在你关心的某个维度上胜过我们，而我们的路线图中没有一条能弥补这一差距的工作项，那就是我们战略上的缺陷：请提交 issue。

## 架构

Mitos 启动 Firecracker 微虚拟机，通过写时复制快照进行分支，并通过 `mitos.run/v1` API 组中的声明式 CRD（`SandboxPool`、`Sandbox`、`Workspace`）暴露整个生命周期。沙箱是微虚拟机，而非 pod：它通过 KVM 获得硬件隔离，pod 作用域的机制（NetworkPolicy、ResourceQuota、PSA）不适用于它。

组成部分：

- **controller**（Deployment）：对账 CRD、选择节点并驱动 `forkd`。它通过由每节点容量心跳填充的注册表跟踪可用的分支节点。
- **forkd**（DaemonSet）：拥有 VM 的每节点守护进程。它在 `:9090` 上为控制器提供 gRPC 服务（fork、prepare-pool、heartbeat），并在 `:9091` 上提供 HTTP 沙箱 API 以处理 exec 和文件流量。它需要 `/dev/kvm`，因此只在具备 KVM 能力的节点上运行。
- **guest agent**：每个微虚拟机内的 PID 1。它使用 vsock 协议处理 exec、文件、环境和分支通知。
- **sandbox-server**：同一个分支引擎，但提供纯 REST API，无需 Kubernetes，用于本地循环和单主机使用。
- **SDK**（`sdk/python`、`sdk/typescript`、`sdk/go` 等）：面向托管服务、集群或 `sandbox-server` 的客户端。

两条热路径承载整个系统：

- **认领路径**：控制器从注册表中选择一个热节点，并通过 gRPC 调用 `forkd` 的 `Fork`；生成的沙箱通过该节点上 `forkd` 的 HTTP API 报告 Ready。
- **执行路径**：SDK 或 CLI 与 `:9091` 上的 `forkd` 通信，后者通过 vsock 桥接到 VM 内的 guest agent。

分支是核心原语：源 VM 只快照一次，N 个子 VM 通过写时复制从该快照恢复，因此每个兄弟 VM 都能热启动且相互独立，而共享的模板页只存储和计量一次。由于 Firecracker 需要硬件虚拟化，裸机（Hetzner 上的 Talos 是参考平台）是一等公民目标；云控制平面留在普通节点上，而执行则落在具备 KVM 能力的机器上。

## 项目状态

早期开发阶段，pre-1.0（最新版本 `v0.3.0`）。请勿在生产环境运行不受信任的代码：尚未进行外部安全审查，部分隔离控制仍处于开放状态（各边界的确切状态见[威胁模型](https://mitos.run/docs/threat-model)）。控制平面端到端真实可用，已在 CI 中针对 mock 引擎和真实 Firecracker VM 验证，并在单节点 Talos KVM 集群上演练。

**已在真实 KVM 集群上验证（husk 默认）：** 热认领激活、阻塞式 exec、`run_code` 失败关闭为 `KernelUnavailable`、自愈/重新挂起、池预热加需求自动扩缩容、实时沙箱分支（源 husk pod 对其 VM 做快照，N 个子 pod 通过 CoW 恢复它，每个都是独立的 Ready 子节点）、持久可分支工作区（create -> commit -> fork），以及 pod 出口隔离（默认拒绝、云元数据阻断、每模板白名单）。

**已跟踪但尚未在 husk 默认配置中实现的收尾项：** 流式 exec 和交互式 PTY；用于可恢复工作区 head 的实时 VM 内存快照钩子；S3/加密实时存储选择；husk 的 `{git}` 工作区推送；以及多节点 N>1（已设计，单节点验证）。

[ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md) 是已完成、进行中和受门控事项的唯一定义来源。运营准则：本仓库绝不描述不存在的系统。

## 本地开发（无需 KVM）

`mitos dev up` 在 mock 控制平面上启动本地 kind 集群，`mitos` CLI 驱动完整的认领路径；mock 引擎将认领对账为 `Ready` 并演练控制平面调度，但真正的 VM 内 `exec` 需要带 `/dev/kvm` 的节点。对于无集群的 REST 循环，运行 `go run ./cmd/sandbox-server --mock --addr :8080` 并将 Python SDK 指向它。完整的 kind 演练见 [mitos.run/docs/cli](https://mitos.run/docs/cli)。

## 文档

完整文档位于 **[mitos.run/docs](https://mitos.run/docs)**：快速入门、架构、SDK 和 CLI 参考、沙箱生命周期、工作区、网络和威胁模型，全部由本仓库渲染生成。

完整的长尾内容（模板、快照格式与分发、加密与机密、调度与密度、失败与 GC、分支引擎正确性、配方，以及目标 v2 API 规范）位于本仓库的 [`docs/`](https://github.com/mitos-run/mitos/blob/HEAD/docs/)。基准测试方法论见 [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md)。

## 贡献

欢迎贡献。约定见 [CONTRIBUTING.md](https://github.com/mitos-run/mitos/blob/HEAD/CONTRIBUTING.md) 和 [CLAUDE.md](https://github.com/mitos-run/mitos/blob/HEAD/CLAUDE.md)，按 [ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md) 跟踪的工作见[问题页面](https://github.com/mitos-run/mitos/issues)。

## 安全

含各边界状态的威胁模型位于 [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model)；尚未进行外部安全审查，文档明确说明了哪些是开放的。要报告漏洞，请参阅 [SECURITY.md](https://github.com/mitos-run/mitos/blob/HEAD/SECURITY.md)。

## 许可证

[Apache 2.0](https://github.com/mitos-run/mitos/blob/HEAD/LICENSE)。