@roland0511/az-runner

通用 Runner Host 本机管理包，同时提供：

• az-runner：通过本机 Unix Socket 管理 Runner。
• az-runner-daemon：管理 Runtime Provider、Config、ACP Agent、容量和本地恢复。

包中不内置任何项目 Config、Agent 实现或仓库材料。Daemon 从 Runner Home 中已安装的 Config 目录装配运行环境。

安装

npm install --global @roland0511/az-runner@latest
az-runner --version
az-runner-daemon --version

CLI 和 Daemon 必须使用同一版本；npm Registry 只参与安装和升级，不参与本地控制。 当前正式版本为 0.1.19，本地协议为 v10、中央协议为 v6，已完成 M7.4 真机验收；详见 docs/acceptance/M7.4.md。

首次设置

az-runner config init \
  --name runtime-a \
  --image "ghcr.io/example/runtime@sha256:<digest>" \
  --output ./runtime-a
az-runner setup --config ./runtime-a
az-runner acp

setup 安装默认 Config、启动 Daemon，并创建一个临时 Runtime 验证镜像、Workspace 和 Agent 后释放。Config 目录和 TOML 示例见 docs/CONFIGURATION_V3.md。

常用命令

az-runner daemon status
az-runner daemon start
az-runner daemon stop
az-runner daemon restart
az-runner daemon logs
az-runner config add <directory> [--default]
az-runner config list
az-runner config inspect <config-id>
az-runner config explain
az-runner config default <config-id>
az-runner config remove <config-id>
az-runner image list
az-runner image inspect <image-id>
az-runner image prepare [--config <config-id>]
az-runner image remove <image-id>
az-runner build list
az-runner build inspect <build-job-id>
az-runner build logs <build-job-id>
az-runner build retry <build-job-id>
az-runner build cancel <build-job-id>
az-runner build cleanup <build-job-id>
az-runner acp [--config <config-id>]
az-runner start [--config <config-id>] [--attach]
az-runner attach <runtime-id>
az-runner release <runtime-id>
az-runner list
az-runner logs <runtime-id>
az-runner doctor
az-runner provider list
az-runner provider doctor <provider-id>
az-runner runtime list
az-runner runtime inspect <runtime-id>
az-runner runtime logs <runtime-id>
az-runner runtime start --request-id <id> [--alloc <id>] [--config <id>]
az-runner runtime attach <runtime-id>
az-runner runtime release <runtime-id>
az-runner maintenance enable --reason "<原因>"
az-runner maintenance disable
az-runner maintenance status
az-runner reconcile
az-runner cleanup
az-runner register --url <https-url> [--token-stdin] [--name <name>] [--label key=value]
az-runner unregister
az-runner connection status
az-runner connection rotate-token

将 az-runner acp 配置成其他本地 ACP Client 的 Agent executable 时，stdin/stdout 直接承载标准 ACP。该命令会创建并拥有一个 Runtime，在 stdin EOF、连接断开、 SIGINT 或 SIGTERM 后自动释放。stdout 不输出状态或日志。

start --attach 和 attach <runtime-id> 面向人工调试，不自动释放 Runtime；需要显式 执行 az-runner release <runtime-id>。

维护模式拒绝新的 Runtime 和 BuildJob，但不暂停已有 Runtime 或构建；attach、release、状态、 日志、doctor、reconcile、build cancel/cleanup 和 cleanup 继续可用。状态会持久化，Daemon 重启后仍保留。

runtime.start 只接受 requestId、可选透明 allocId 和已安装 configId。 相同请求幂等，同一活跃 Allocation 只能关联一个 Runtime。资源、Workspace、命令和 镜像构建配方必须来自 Config，不能按请求覆盖。

中央协议的 runtime.start 可以额外携带设备绑定、一次性的 credentialGrantId。它只 用于 Runner 以设备身份兑换本次 Allocation 的 Agent 服务凭据，本地 CLI 不接受该字段。 Runner 将 Codex 配置写入本次 Guest 专用 CODEX_HOME（目录 0700、文件 0600），或通过 stdin 执行 codex login --with-api-key，再确认 Grant 消费。Runner 管理链路不把凭据内容 写入 Runner Home、Config、Image、Runtime 状态、transcript 或自身日志；Config [secrets] 与 Provider .az-env 不会被用作 Agent 凭据通道。Agent 能读取被授予的凭据， 因此 Agent 本身及其主动输出仍属于受信边界。

Control Plane 在滚动升级期间仍接受中央协议 v5 Runner，但不会向其下发 v6 BuildJob。 通用 Git/npm/OCI/Runtime Secret 与审计仍属于 M9。

build 命令只用于查看和运维由 Control Plane 下发的受信 BuildJob，不接受任意本地 Recipe。Codex preset revision 1 会在固定 Digest 的 macOS arm64 基础镜像中安装 Node.js 24.19.0、@openai/[email protected] 与 @agentclientprotocol/[email protected]，再验证 /opt/homebrew/bin/codex-acp 和标准 ACP initialize；基础镜像无需预装 Node 或 Agent。Builder 最终生成仅归属当前 Runner 的 不可变 runnerLocal Image 与 Revision Config。

每台 Runner 同时最多执行一个 BuildJob，构建占用一个 Runtime 槽位和声明的 CPU、内存、 磁盘；维护模式拒绝新构建但不会中断已有构建。状态和脱敏日志持久化，Daemon 重启后恢复 可恢复步骤或安全失败。cancel 只有在清理完成并上报 cancelled 后才成为终态；失败且仍 有待清理资源的 BuildJob 继续占用容量，需先通过 build cleanup 完成安全清理。活跃或 cleanupPending BuildJob 同时阻止删除其目标 Config 和本地 Image。

start 会自动准备 Config 引用的固定 Digest OCI Image。显式 Image 命令用于提前拉取、 检查和删除本机缓存；删除 OCI 缓存不影响远端 Image，活跃 Runtime 使用时会被拒绝。 runnerLocal 没有可重新拉取的远端来源，只要仍被任一已安装 Config 或活跃/待清理 BuildJob 引用就拒绝删除；必须先从 Environment/Config 生命周期安全解除引用并完成构建清理。

register 会先确保 macOS 系统级 LaunchDaemon 已安装并运行，再通过隐藏提示读取一次性 注册 Token；自动化只能使用 --token-stdin。不接受 --token 或环境变量 Token。注册 成功后只将设备凭据以 0600 保存到 Runner Home。重复注册到相同地址会复用身份且不再 读取 Token；不同地址返回 already_registered。

统一运维模型

用户入口收敛为 register/unregister 和 daemon start/stop/restart/status/logs，不增加公开 service 命令组。 daemon start 在系统服务缺失时自动安装并启动；register 复用该流程后完成中央 注册，unregister 负责中央注销、设备凭据撤销和本地系统服务移除。本地 Config、 Image 和其他可复用数据不在注销时隐式删除。完整设计与验收门禁见 docs/ROADMAP.md。