zordon

Zordon

为内层开发循环提供的本地技术栈 —— 数据库、消息代理、代理服务器和服务均以快速、可丢弃的 主机进程 运行，只需声明一次并统一监管。无需容器。

Zordon 是一个监管器，为代码运行所需的本地技术栈提供支持——这些数据库、消息代理、代理服务器和服务必须处于运行状态，才能真正测试你的代码。 它将这些组件作为普通的 主机进程 而非容器运行，在 Alphasfile 中声明一次并统一监管，因此启动、复制和丢弃整个技术栈的成本都很低。

每项决策都围绕三个目标展开。 低延迟 —— 启动技术栈和重新运行都属于开发循环，而不是循环之外；迭代不应因基础设施而等待。 资源高效 —— 每个技术栈的开销都足够低，让多个 Agent 可以并行运行；每个 Agent 都拥有足够真实的技术栈进行评估，而不是面对一堆模拟对象。 防护栏 —— Alphasfile 兼作契约，因此 MCP 服务 只向 Agent 提供范围明确的接口：启动技术栈、检查状态、运行你指定的配置，并通过该接口操作，而不是对主机即兴操作。

为什么不用容器？ 代码越来越多地以循环方式编写——做出更改、在真实技术栈上运行、读取结果，再继续，如此每小时重复数百次。 容器通过让每次运行都承担完整的冷启动和空闲开销来换取隔离：适合生产环境，却不适合开发循环。 Zordon 采用另一种方式，通过按运行划分的工作区而非镜像来实现隔离——因此，在你的技术栈旁边再运行第二个，甚至第十个，都不会造成负担。

在一个 Alphasfile 中声明整个技术栈：

service "go" "nats" {
  git {
    url = "github.com/nats-io/nats-server"
    tag = "v2.14.0"
  }

  vars = { client = net::pickport() }   # grab a free port, no clashes
  arguments { values = { main = { p = self.vars.client } } }
}

zordon start   # resolve, build, bring it up, stream logs until everything is READY

功能

• 无需容器，无需守护进程。 数据库、消息代理、代理和服务都以普通的受监管主机进程运行——无需构建镜像、挂载或注册。
• 多语言工具链。 Go、Rust、Ruby、Node.js 和 Java（Maven/Gradle）服务可直接从 git URL 或本地源码构建；Redis、PostgreSQL、etcd 等原生软件包通过 mise 配置。
• 一个清单。 整个技术栈——源码、构建、运行、环境变量、就绪状态、日志——都在单个 Alphasfile 中声明。
• 以图结构组织的动态配置。 值是函数，而非字符串：net::pickport() 会选择空闲端口，fs::tmp()/fs::hash() 会生成每次运行独有的路径，服务之间可相互引用（service.go.caddy.vars.http），无需硬编码连接配置。→ 文档
• 工作区。 zordon workspace create x 会启动整个技术栈的第二个完全隔离副本——使用独立端口和目录——作为 Agent 的沙箱，与你的环境并行运行，无需端口映射。→ 文档
• 联邦。 Alphasfile 根据目录位置串联：项目位于共享基础设施之下，而非导入它。只需在目录树中移动项目，其环境就会重新计算。→ 文档
• 就绪状态感知启动。 基于依赖图执行 HTTP 和命令就绪检查；zordon start 会在所有服务都处于 READY 状态时立即返回，并在后台保持整个技术栈运行。
• 收敛式重运行。 重新运行时只处理实际发生变化的部分——不会一概拆除并重建。
• 初始化任务。 可按服务声明一次性设置任务（迁移、填充数据、创建主题），按需运行，并可使用 zordon clean 清理。
• 适合 Agent 的输出。 --agent 会输出简洁的结构化日志；输出会保持高信号密度，因为模型读取日志时，Token 就是预算。
• MCP 服务。 zordon mcp 会将每条命令和每项初始化任务都作为 MCP 工具开放，让 Agent 能够操控整个技术栈。→ 文档
• 为 Agent 设置防护措施。 Alphasfile 与 MCP 接口共同构成 Agent 和技术栈之间范围明确的接口——它只会运行你定义的具名初始化任务，而不会开放 Shell，因此无法绕过你的设置自行变通。
• 无运行时依赖。 只需三个静态 Go 二进制文件——zordon、alpha、tommy——无需安装、构建镜像或注册其他任何内容。

文档

完整文档：https://zordon.io （源码位于 docs/，使用 MkDocs Material 构建）。

• Alphasfile — 清单：服务、源码指针、就绪状态、日志
• 动态配置 — DAG、辅助函数、self、跨服务引用
• 工作区 — 整个技术栈的并行隔离副本
• 联邦 — 串联的 Alphasfile、共享基础设施、zordon sudo
• MCP 服务 — 通过 MCP，让 Agent 操控 zordon（及其初始化任务）
• 安装 Claude Code 插件 — 通过 /plugin install 零配置安装

安装

Homebrew（macOS）：

brew install piotrkowalczuk/tap/zordon

从 Releases 下载发布压缩包（适用于 macOS 和 Linux，支持 arm64 和 amd64）：

tar -xzf zordon_<version>_<os>_<arch>.tar.gz -C ~/.local/bin zordon alpha tommy

或者，如果你有 Go 工具链，也可以从源码安装：

go install github.com/piotrkowalczuk/zordon/cmd/...@latest

所有安装方式都会安装相同的三个二进制文件——zordon、alpha 和用于清理进程的 tommy。将它们放在同一个目录中，并确保该目录位于 $PATH 中：zordon 通过 $PATH 查找 alpha，而 alpha 只会在其可执行文件所在目录中查找 tommy。参见二进制文件和目录布局。

快速开始

创建一个 Alphasfile（参见 examples/simple），然后：

zordon start              # spawn alpha, push config, stream bringup logs
zordon status             # what's running across the whole chain right now?
zordon stop               # ask alpha to shut its children down and exit
zordon clean              # run each provision's clean teardown (stack stopped)
zordon workspace create x  # a parallel, isolated copy of the stack

其余内容请参见文档。

与 Claude 配合使用（MCP）

zordon mcp 会运行一个 MCP 服务，默认通过 stdio 运行，也可以使用 --transport=http 通过 HTTP 运行。 它会将每个 zordon 命令和每个 provision 都作为工具公开，让 Agent 能够驱动你的技术栈，并按需运行 provision。

最快的方式是使用 Claude Code 插件，无需手动配置：

/plugin marketplace add piotrkowalczuk/zordon
/plugin install zordon@zordon

这会注册 zordon mcp 服务，并添加一个 skill，自动引导 Agent 使用它；请参阅安装指南。

对于其他 MCP 客户端，或不使用插件时：

MCP 客户端会启动服务；你无需自行运行 zordon mcp。 使用 Claude Code 时，请在项目目录中注册它：

claude mcp add zordon -- zordon mcp

或者将其添加到客户端的 MCP 配置中（例如 .mcp.json）：

{ "mcpServers": { "zordon": { "command": "zordon", "args": ["mcp"] } } }

服务会从其工作目录解析链，因此请从项目目录树中启动客户端（或传入 -e ZORDON_HOME=…）。 Provision 会在运行中的 alpha 内执行，因此请先运行 zordon start，或者让 Agent 调用 start 工具。

若要让受限于容器或沙盒中的 Agent 驱动主机上的技术栈，请改为通过 HTTP 提供服务；这样客户端只需要一个 URL，无需在容器内安装 zordon 二进制文件：

zordon mcp --transport=http --listen 127.0.0.1:7391

请参阅操作指南；注意，该端点目前尚未经过身份验证。

服务会通过 MCP instructions 向 Agent 说明自身用途（何时使用这些工具），因此 Agent 应该能自行选择使用它们。 若要在由 zordon 管理的仓库中进一步引导 Agent，可在 CLAUDE.md（或 AGENTS.md）中添加一行："this project's local stack is managed by zordon — use the zordon MCP tools to bring it up, inspect it, and run provisions."

请参阅 zordon mcp 参考文档和操作指南。

许可证

GNU 通用公共许可证 v3.0， 请参阅 LICENSE.md。