agent-compose 命令行使用手册

agent-compose 命令行用于连接 agent-compose daemon，管理 project、agent、sandbox、日志和镜像。它的使用模型接近 Docker Compose：配置文件定义 project，daemon 负责长期状态和运行时生命周期，CLI 负责发起操作和展示结果。

核心概念

• project：一个 agent-compose.yml 或 agent-compose.yaml 对应一个 project。配置文件所在目录是 project root。
• agent：project 中定义的 agent 配置。一个 project 可以包含多个 agent。
• sandbox：agent 的一个运行态隔离环境。一个 agent 可以创建多个 sandbox；无论底层 runtime 是 Docker、BoxLite 还是 Microsandbox，命令行都统一使用 sandbox 概念。
• daemon：agent-compose 的服务端进程，负责 project 状态、scheduler、sandbox 生命周期、日志、镜像和 API。

命令格式

agent-compose [global options] <command> [command options] [arguments]

全局参数位于 agent-compose 和子命令之间，适用于所有 project 相关命令。

示例：

agent-compose -f /path/to/project/agent-compose.yml up
agent-compose -f /path/to/project/agent-compose.yaml ps --all
agent-compose --host http://10.0.0.12:7410 ls --json

使用规则：

• 未指定 -f 和 --project-name 时，project 范围的命令在当前目录查找 agent-compose.yml 或 agent-compose.yaml。
• 指定 --project-name 时，已部署项目命令直接选择 daemon project，不读取 compose 文件；即使同时指定 -f 也是如此。
• 本地编排命令始终使用 compose 文件声明的项目名称（或根据其目录推导）。up 和 project up 会拒绝 --project-name，不再静默忽略；config 也不会用它覆盖 compose project 名称。
• 使用 -f 时，不需要切换到 project root。
• --host 只决定 CLI 连接哪个 daemon；sandbox 实际运行在 daemon 所在环境中。
• --timeout 接受 30s、15m、2h 等 Go duration。它分别作用于每个 unary、server-streaming 或双向流 RPC；设置为 0 时会等待 RPC 完成或用户主动取消。
• 即使 --timeout 为 0，连接建立和显式健康检查仍保留各自的有限超时。
• --timeout 只控制 CLI 请求；AGENT_TIMEOUT、SANDBOX_START_TIMEOUT、SANDBOX_STOP_TIMEOUT 等 daemon 侧限制保持独立。
• JUPYTER_READY_TIMEOUT 控制 daemon 等待 guest Jupyter 就绪的时间，默认 120s，为冷启动留出余量；Jupyter 一旦就绪便立即继续启动。可用正数 Go duration 覆盖；未设置、格式无效或非正数时使用默认值。
• daemon 不再消费浏览器登录用的 AUTH_* / OAUTH_* 配置；UI 浏览器认证由 agent-compose-ui server 处理。
• 自动化场景应使用 --json，不要解析人类可读表格。

Daemon 认证

在 daemon 环境中设置 AGENT_COMPOSE_AUTH_TOKEN 后，HTTP(S) 控制面请求必须 携带共享 Bearer Token；配置为空时认证默认关闭。受信任的本地 Unix Socket 连接不走此认证路径。

为 daemon 站点验证并保存 Token：

agent-compose --host https://compose.example.com auth login --token '<token>'
agent-compose --host https://compose.example.com status

第一条命令会先向 daemon 验证 Token，成功后写入 ~/.config/agent-compose/config.yml（或当前平台的用户配置目录）。后续命令会 根据规范化后的 --host 或 AGENT_COMPOSE_HOST 自动加载对应 Token。配置文件 仅允许当前用户读写。可通过 agent-compose auth ls 查看已保存的站点，通过 agent-compose --host <site> auth logout 删除站点凭据。

当前仍支持 HTTP，包括宿主机访问容器回环映射的场景；但明文 HTTP 中的 Bearer Token 可能被监听并重放。CLI 与 daemon 位于不同机器时，应使用 HTTPS、SSH 隧道、VPN 或其他受保护网络。

Health RPC、runtime LLM facade、Jupyter proxy 和 webhook ingestion 继续使用各自 已有的认证或信任边界，不消费 daemon Token。

GitHub Webhook

通过 PUT /api/webhook-sources/<source-id> 创建启用的 webhook source：将 provider 设为 github，将 topic_prefix 设为 webhook.github.，将 signature_type 设为 github_sha256，并在 signature_secret 中填写准备配置到 GitHub 的同一个 secret。API 响应不会返回 secret 明文。

GitHub 也允许 webhook 的 Secret 留空。若要直接接收这类无签名投递，需要显式将 signature_type 保持为 github_sha256，并同时将 signature_secret 和 source token 留空。未配置 signature secret 时，daemon 会跳过签名校验。该模式不会认证 发送者：任何能够访问此 endpoint 的客户端都可以伪造 GitHub 事件，因此只能在受信任 的反向代理或网络访问控制之后使用。若 source 配置了 token，daemon 仍会要求该 token，便于代理完成认证后注入。无 token 的 unsigned source 不能与另一个启用的 source 共用 webhook URL，否则无法唯一选择 source。

由于 signature secret 是 write-only，更新已有 source 时省略 signature_secret 或传入空值会保留当前 secret。若要将已有的 signed source 切换为 unsigned delivery，必须显式设置 clear_signature=true。

在 GitHub 仓库或组织设置中添加 webhook，并使用以下配置：

• Payload URL：https://<agent-compose-host>/api/webhooks/webhook.github
• Content type：application/json 或 application/x-www-form-urlencoded
• Secret：webhook source 中配置的 signature secret；仅当 source 明确使用无签名 模式时留空
• Events：选择 scheduler 需要消费的事件

daemon 支持 GitHub 的 JSON 请求体，也支持 form 编码的 payload 字段。两种格式都 会先针对未经解码的原始请求体校验 X-Hub-Signature-256，然后根据 X-GitHub-Event 发布 webhook.github.push、webhook.github.pull_request 和 webhook.github.ping 等 topic。GitHub 的 X-GitHub-Delivery 同时作为 delivery ID 和幂等键，因此相同 payload 的 redelivery 会返回成功，但不会创建重复事件。配置 signature secret 后，即使 source 同时保留了旧的静态 token，缺失或无效的签名仍会 被拒绝。未配置 signature secret 时，GitHub source 使用相同的事件路由，但不校验 签名。通用 webhook source（包括 signature type 为空的旧 source）继续使用 URL topic，以及 Bearer、X-WEBHOOK-TOKEN 或自定义 header token。

该 Token 保护的是 daemon 控制面，并非只识别 CLI 程序。任何调用相同控制面 API 的 UI server 或反向代理，也必须先配置注入 Authorization: Bearer <token>，再 开启 daemon 认证。

查看事件 Trace

GET /api/events/{event_id}/trace 返回事件、关联的 scheduler run 和事件，以及 sandbox 关联记录和可选摘要。查询范围包含后代事件及相同 correlation ID 的事件， 总计最多 1,000 个事件。

Sandbox 摘要采用尽力补充策略，查询使用两秒的 context 预算；补充失败或超时时， 响应保留 trace 和已获取的摘要，并设置 sandbox_summaries_incomplete: true。 请求本身被取消时仍会取消整个请求。文件系统回退成功时，不会仅因缓存查询失败 就设置不完整标志。已不存在的 sandbox 可以没有摘要。

Sandbox 缓存更新失败时，只将该 sandbox 加入后台修复队列，重试退避从一秒递增到 最多 30 秒。无效 metadata（JSON 格式错误、ID 缺失或不匹配、driver 非法）会被 排除出缓存，成功清除旧缓存行后结束对应重试。metadata 文件保持不变，后续有效 更新或启动校准可以重新建立缓存。文件系统读取错误和数据库错误仍保留重试。 Trace 对待修复的 sandbox 按 ID 直接读取 metadata 文件，不会触发 全量缓存重建。修复期间，sandbox 列表的筛选和总数可能暂时滞后；正常成功的更新 仍然同步完成。启动时仍会根据文件系统 metadata 校准全部缓存。缓存失败日志包含 各阶段耗时和共享数据库连接池统计，用于区分归属查询、更新排队和存储延迟； 连接池等待增量包含同期其他请求的等待。

停止 Webhook 事件触发的运行

提交 webhook 的客户端可以在之后请求取消该事件、其后代事件，以及与该请求事件共享 correlation_id 的全部事件所关联的活跃 run。correlation_id 的停止范围是整个关联 组，而不只是因果后代：同组中更早、更晚和同级的事件都会纳入，即使它们由不同的 webhook source 提交。

POST /api/webhooks/events/<event-id>/stop
Authorization: Bearer <webhook-source-token>
Content-Type: application/json

{"reason":"business canceled"}

JSON 请求体可以省略。该 endpoint 只接受请求事件所属 webhook source 配置的静态 token；source 配置了自定义 token header 时也沿用该 header。停止范围内的后代或 关联事件即使属于其他 source，也不会再分别校验其 source token。GitHub 请求签名只能 证明单次 delivery 的真实性，不是可复用的控制凭据。因此，没有配置静态 source token 的 signed 或 unsigned GitHub source 可以接收事件，但不能调用此停止 endpoint。若这些事件需要支持停止，应另外配置 source token，不能把 GitHub signature secret 当作 token 使用。

对于停止范围内的每个后代或关联事件，该请求同时覆盖已经启动的 run 和尚未启动的 投递。仍在投递队列中等待的事件会被撤回，不会再启动 run，数量记在 canceled_events；已经活跃的 run 会收到异步取消请求，数量记在 requested_runs。

{"event_id":"evt_123","stop_requested":true,"requested_runs":2,"pending_runs":0,
 "canceled_events":1,"pending_events":0,"stale_events":0,"failed_runs":0}

pending_runs 表示记录为活跃、但未在本进程注册，因而本次停不掉的 run。run 写入存储 并把 run ID 盖到 delivery 上，略早于 daemon 接管它，所以调用方读到 run ID 后立即停止 就可能落在这个间隙里，重复调用即可停掉。若某个 run 是崩溃的 daemon 遗留的，它会保持 这个状态直到启动对账把它改成 failed，此时重复调用不会停掉它，也没有 run 仍在执行。 这种情况返回 200，不按失败处理。

pending_events 和 stale_events 都表示请求到达时已经被领取投递的事件，本次请求 停不掉它们。两者的区别在于 run 何时出现，这决定了什么时候重复调用：

• pending_events：认领仍然有效，worker 正在投递，run 马上就会出现。稍后重复调用 一次即可停掉。
• stale_events：认领已过期，原投递方已经失联，事件要等下一轮派发才会被重新领取。 立刻重复调用什么也停不到；应等到 GET /api/events/<event-id>/runs 中出现该 run 之后再调用。

重复调用始终是安全的：已撤回的事件和不再活跃的 run 都不会发生变化。

取消是异步的，因此 stop_requested=true 并不表示所有 run 已经进入最终状态或取消状 态已经持久化；这与同步停止确认的语义不同。需要确认停止完成的调用方必须针对已知 run ID 轮询 GetSchedulerRun，或轮询 ListSchedulerRuns（CLI 命令 agent-compose scheduler runs），直到受影响的 run 报告终态 succeeded、failed、 canceled 或 skipped。

daemon 单次最多处理后代事件树和 correlation group 合并后的 1,000 个不同事件。合并 范围更大时，会在停止任何 run 之前返回 409 和 max_event_count，不会把被截断的 结果当作成功。如果个别停止操作失败，daemon 仍会继续处理其余 run，并返回 500； 响应中的 requested_runs 记录成功请求取消的数量，failed_runs 和 failed_run_ids 记录失败项。重新对整个事件发起请求是安全的，只会重试仍然活跃的 run。Token 缺失或无效时返回 401，非 webhook 事件返回 403，事件不存在时返回 404。

Project 环境文件

配置可以显式指定一个或多个 dotenv 文件；相对路径以 project 配置文件所在目录为基准：

env_file:
  - .env
  - .env.local

未声明 env_file 时，CLI 优先自动加载 project 目录下的 .env；该文件不存在时，再尝试当前工作目录的 .env。显式声明 env_file 后不再自动加载这两个文件。

变量冲突时，后声明的 env 文件覆盖先声明的文件，启动 CLI 时已有的进程环境覆盖所有 env 文件。Project 环境文件只参与 agent-compose.yml 渲染，不会改变 --host、认证等 CLI 连接配置。

Daemon 数据库并发

daemon 在启动 migration 期间只使用一个 SQLite 连接。migration 成功后，文件型 数据库默认最多使用四个运行期连接，使 WAL reader 可以和 writer 并发推进。可以将 SQLITE_MAX_OPEN_CONNS 设置为 1 到 32 之间的整数来覆盖该限制。无论配置值 是多少，内存 SQLite 数据库始终限制为一个连接。

增大连接数可以允许更多数据库操作并发执行，但不会增加 SQLite writer 数量：WAL 仍然只允许一个活跃 writer。因此，只有在连接等待指标表明确有需要，并且已经用部署 环境的写入负载验证后，才应设置高于默认值的连接数。

常见工作流

本地开发：

agent-compose up
agent-compose ps
agent-compose run reviewer --prompt "Review the current diff"
agent-compose logs reviewer --follow
agent-compose down

后台部署：

agent-compose -f /path/to/project/agent-compose.yml up
agent-compose -f /path/to/project/agent-compose.yml ps --all
agent-compose -f /path/to/project/agent-compose.yml logs --follow

远程 daemon：

agent-compose --host http://10.0.0.12:7410 project ls
agent-compose --host http://10.0.0.12:7410 -f /path/to/project/agent-compose.yml up
agent-compose --host http://10.0.0.12:7410 -f /path/to/project/agent-compose.yml logs --follow

project ls：查看 project

查看当前 daemon 管理的所有 project。

agent-compose project ls
agent-compose project ls --limit 20 --offset 40
agent-compose project ls --verbose
agent-compose project ls --json

默认输出字段：

• PROJECT：project name。
• CONFIG FILE：配置文件路径。
• REVISION：当前 project revision。每次应用新的 spec 变更都会递增；连续重复 apply 当前 spec 时保持同一个 revision。
• AGENTS：agent 数量。
• SCHEDULERS：scheduler 数量。
• SERVICES：project 关联服务数量。当前 project spec 尚未定义 service 模型，因此该列显示为 -。

--verbose 显示更多 daemon 已记录的信息，包括 project id、project root、spec hash、创建时间、更新时间和状态摘要。

选项：

agent ls：查看当前 project 的 agents

查看当前已应用 project 下的所有 agents。顶级 ls 是 agent ls 的别名。

agent-compose agent ls
agent-compose ls
agent-compose agent ls --json

MODEL 显示在没有请求级或 Session 级覆盖时，新一次运行将选择的模型。MODEL SOURCE 用于区分项目声明（project）、Agent 环境值（agent_env）、daemon 默认值（daemon_default）、provider 自身默认值（provider_default）和缺少必填模型（unresolved）。JSON 输出继续用 model 表示项目声明值，并新增 resolved_model 和 model_source；daemon 默认值不会写回项目配置。

project up：启动或更新 project

读取配置文件，将 project 应用到 daemon，并启动或更新 project 中的 scheduler 和服务。

agent-compose up
agent-compose project up
agent-compose -f /path/to/project/agent-compose.yml up

当前 up 的行为是将 project 应用到 daemon 后返回，project 后续由 daemon 管理。它不会 attach project 日志，也不提供 -d/--detach 参数。

Project 应用通过规范化后的 project name 解析，不再由 compose 文件路径决定。同名 compose 文件移动后再次执行 up，会更新 daemon 中原有 project，并保留其持久 ID 和历史。

如果升级时数据库中已有多个同名 project，系统会保留每个 project，并把其余记录确定性地改为可用的 <name>-N。操作这些 project 前应先查看 project ls，并在对应 compose 文件中使用迁移后分配的名称。

顶级 up 是 project up 的别名。

project down：关闭 project

关闭当前 project，停止 scheduler、服务和运行中的 sandbox。

agent-compose down
agent-compose project down
agent-compose -f /path/to/project/agent-compose.yml down

顶级 down 是 project down 的别名。

注意事项：

• down 只影响当前 project。
• 使用 -f 或 --project-name 时，应确认定位到的是预期 project。
• 如果部分 sandbox 停止失败，命令返回非零退出码并说明失败项，同时保持 project 为 active，以便再次执行 down。

run：运行 sandbox

为指定 agent 启动一个 sandbox，或在已有 sandbox 中继续运行。

agent-compose run <agent> --prompt "..."
agent-compose run <agent> --command "..."
agent-compose run <agent> --sandbox <sandbox> --prompt "..."

输入模式：

prompt 输入必须使用 --prompt；非交互 run 必须选择 --prompt 或 --command。不再支持 positional prompt 参数。 不支持额外的位置参数。

选项：

示例：

agent-compose run reviewer --prompt "Review the staged changes"
agent-compose run builder --command "task build"
agent-compose run tester --command "task test" --keep-running
agent-compose run tester --command "task test" -d
agent-compose run reviewer -i --prompt
agent-compose run tester -i --command
agent-compose run reviewer --sandbox sandbox_123 --prompt "Continue the review"
agent-compose run reviewer --jupyter --jupyter-expose --prompt "Inspect the notebook state"

互斥规则：

• prompt、command 一次只能选择一种。
• 使用 --prompt 或 --command 时，不能再传额外位置参数。
• run -d/--detach 和 run -i/--interactive 互斥。
• run -i/--interactive 必须选择 --prompt 或 --command，不能与 --json 组合。
• REPL 中空行不会创建 run；输入 /exit 或 Ctrl+D 退出。
• REPL 不是 TTY/PTY 或运行中 stdin 透传；每条输入都是一次独立 StreamAgentRun，但复用同一个 sandbox。
• --sandbox 只能复用属于当前 project 和所选 agent 的 sandbox；跨 project 或跨 agent 复用会被拒绝，且不会修改或停止原 sandbox。
• detached run 可通过输出的 agent-compose logs --run <run-id> --follow 命令观察输出，也可继续使用 stop/logs 操作该 run。
• run -i --prompt 仅支持可复用 provider conversation 的 Codex、Claude、OpenCode、Pi 和 DSH（dsh、deepseek、deepseek-harness、deepseek_harness）。
• run 通常只有在 completion cleanup 成功后才进入终态。默认策略停止 sandbox；remove-on-completion 会完整删除由本 run 新建的 sandbox，但复用的 sandbox 只会停止；keep-running 是不执行清理的显式例外。
• cleanup 失败时 run 保持 running 并写入 cleanup_error，daemon 会立即重试并采用有上限的退避，重启后也会继续。重试有上限：达到次数上限后，run 会以首个 completion 写入者选定的终态落终态（成功执行或正常关闭 prompt 会话为 succeeded，中断执行中的 turn 为 canceled）并保留 cleanup_error，未完成的 completion 被放弃而不再无限重试。前台与流式调用在自身的完成等待 deadline 到达后停止等待并返回错误，错误中给出 run 停留的状态；run 本身仍由这些后台重试收敛。detached start 仍立即返回。
• StopRun 可能返回 stop_requested=true 而 run 仍为 running。对于 prompt interactive session，Engine 根据自身 turn 状态决定终态：turn 已完成后的空闲会话正常关闭并提交 succeeded；执行中的 turn 被中断并提交 canceled；执行自身报错则提交 failed。请求中的 reason 只用于审计，不参与状态选择。command 与非交互 run 保持原有取消语义。配置的 cleanup 完成后才提交终态；daemon 重启后遗留的 running/pending run 也通过同一路径在清理后变为 failed，错误为 daemon interrupted。
• 卡住的 cleanup 也可以显式放弃，见 abandon-completion。

abandon-completion：结束 cleanup 无法收敛的 run

结束一条已进入 cleanup 阶段但无法成功的 run，例如集群或 runtime 已永久不可达。当后台 cleanup 重试有上限仍无法完成时，这是操作者的退出路径。

agent-compose abandon-completion <run>
agent-compose abandon-completion <run> --reason "kubeconfig points at a deleted cluster"

规则：

• run 会以首个 completion 写入者选定的终态落终态（succeeded、failed 或 canceled），不再停在 running，同时释放未完成的 completion。
• 记录的 cleanup_error 会说明 cleanup 被操作者放弃、sandbox runtime 可能仍然存在；其中也会保留重试循环最后记录的 cleanup 错误，因为被释放的 completion 不再持有它。
• 该命令不会停止或删除 sandbox runtime。请另行清理，例如 sandbox stop、sandbox rm 或 driver 自带工具。
• 如果该 run 已有一次 cleanup 尝试在进行中，命令会等它返回后再落终态；也就是说响应时间由这次尝试决定，而不是由重试计划决定。
• 仍在执行的 run 请使用 stop，该路径仍会清理 runtime；对这类 run 执行放弃会返回 failed_precondition。
• run 已是终态时命令退出码为 0，并输出 already terminal; nothing was abandoned，因此在响应丢失后重试是安全的。
• 放弃是操作者的决定，而不是修复：runtime 保持原状，run 记录是「它可能仍然存在」的唯一说明。

示例：

agent-compose abandon-completion run_123
agent-compose abandon-completion run_123 --reason "cluster deleted during incident"
agent-compose abandon-completion run_123 --json

scheduler：调用、查看和操作 project scheduler

agent-compose scheduler ls [agent]
agent-compose scheduler invoke <scheduler-ref> [--payload <json>]
agent-compose scheduler trigger <scheduler-ref> <trigger-ref> [--payload <json>] [--detach]
agent-compose scheduler runs [scheduler-ref] [--trigger <trigger-ref>] [--status <status>] [--limit <n>]
agent-compose scheduler logs [run-ref] [--run <run-ref>] [--scheduler <scheduler-ref>] [--trigger <trigger-ref>] [--tail <n>]
agent-compose scheduler prune [--scheduler <scheduler-ref>] [--trigger <trigger-ref>] [--status <terminal-statuses>] [--older-than <duration>] [--force]
agent-compose scheduler inspect <scheduler-or-trigger-or-run-ref> [--scheduler <scheduler-ref>]

• scheduler ls 同时列出声明式 scheduler 配置的 trigger 和 scheduler script 注册到系统中的 trigger。
• scheduler invoke 在前台调用显式脚本型 scheduler 的默认执行入口；它不创建 trigger run 历史、持久化外层日志或 artifacts。原有 scheduler run 命令已直接移除。
• scheduler trigger 手动执行指定 trigger；使用 --detach 时会返回一个可继续 inspect 或 stop 的持久化 trigger run。
• scheduler trigger --payload '{"key":"value"}' 将 JSON payload 传给 scheduler trigger handler。
• scheduler runs 只列出外层 trigger run；scheduler.agent() 创建的内层 agent run 仍由普通 run 命令管理。默认返回全部匹配记录，只有显式设置 --limit 才限制最终数量；status 可选 running、succeeded、failed、canceled、skipped。
• scheduler runs 的 TRIGGER 列会显示声明式 trigger 的名称并附带短 trigger id（hourly-status (8fdd8df0d707)）。脚本式 trigger 仍显示其注册 trigger id（该 id 本身即可读）；trigger 已从当前定义中删除的历史 run 回退显示完整 trigger id。scheduler runs --json 用 trigger_name 输出同一个名称，trigger_id 保持原值不变。
• scheduler logs 默认输出当前所有 scheduler 的全部 trigger run 外层结构化事件。--tail N 选择全局最新 N 条匹配事件并按从旧到新输出；--tail -1 表示全部，--tail 0 表示不输出。这里不包含 Invocation 日志或内层 agent transcript。
• 命令输出中不是合法 UTF-8 的字节，在 scheduler logs 的事件 message 以及持久化的 message 文本中都会以 U+FFFD（�）替换字符呈现。单个坏字节不会导致整条响应失败；run artifacts 仍保留原始字节。
• scheduler runs/logs --trigger 会优先按当前定义解析名称和短 ID。Trigger 被删除或改名后，只要仍有持久化的 trigger run 历史，就可以继续用其精确 ID 查询；同一历史 ID 属于多个 Scheduler 时，runs 需要增加 Scheduler 位置参数，logs 需要增加 --scheduler。
• scheduler prune 清理外层 trigger run 历史及其直属 scheduler event、event delivery/link 和规范 run artifacts。默认匹配当前 project 中全部 succeeded、failed、canceled、skipped 终态 trigger run；可用 --scheduler、--trigger、--status、--older-than 缩小范围。命令默认只 dry-run，只有 --force 才真正删除。running run、Invocation、内层 agent run、topic event、sandbox、scheduler state 和 sticky binding 都会保留。历史 Trigger ID 与 runs/logs 使用相同的“当前定义优先”解析规则。
• daemon 启动时会先把上一次进程中断后遗留的外层 running trigger run 收敛为 failed，并记录 daemon-interrupted scheduler event；之后它才能按普通终态历史参与 prune。
• scheduler inspect 只接受一个 scheduler 名称/ID、trigger 名称/ID 或外层 trigger run ID。多个 scheduler 存在相同 trigger reference 时，使用 --scheduler <scheduler-ref> 消歧；旧双位置参数形式不再支持。
• 当前 scheduler runs 和 scheduler logs 会收齐 unary cursor pages 后一次性渲染；streaming/follow 能力留到单独修改中实现。

ps：查看 sandbox

查看当前 project 下的 sandbox。默认只显示运行中的 sandbox。使用 --all 时仍限定当前 project，但会包含所有状态。 该 project 必须已经存在于 daemon 中；执行 agent-compose down 后，需要先重新执行 agent-compose up，再使用 ps。 使用 --project-name <name> 时，会直接选择 daemon 中已有的 project；即使同时指定 --file，已部署项目选择也不会读取 compose 文件。本地编排命令仍要求 compose 文件；up 和 project up 会拒绝 --project-name，config 也不会用它修改 compose project 名称。

agent-compose ps
agent-compose ps -a
agent-compose ps --all
agent-compose ps --status running
agent-compose ps --status stopped,failed
agent-compose ps --verbose
agent-compose ps --json

选项：

默认输出字段：

• SANDBOX
• AGENT
• STATUS
• RUN
• CREATED
• UPDATED

--verbose 增加 project、driver、image、Jupyter、workspace 和错误摘要等信息。

sandbox：管理 sandbox

使用 sandbox 命令组可以在同一个命名空间下管理当前 project 的 sandbox。兼容入口 ps、stop、resume 和 rm 仍然可用。

agent-compose sandbox ls
agent-compose sandbox ls --all --json
agent-compose sandbox stop <sandbox>
agent-compose sandbox stop --graceful --grace-period 10s <sandbox>
agent-compose sandbox resume <sandbox>
agent-compose sandbox rm <sandbox>
agent-compose sandbox rm --force <sandbox>
agent-compose sandbox prune
agent-compose sandbox prune --older-than 7d
agent-compose sandbox prune --status failed --json
agent-compose sandbox prune --agent worker --driver microsandbox --force
agent-compose sandbox prune --include-orphans

子命令：

sandbox prune 参数：

行为规则：

• 不带 --include-orphans 时，sandbox prune 只处理当前 compose project 的 stopped/failed sandbox 记录，且不会扫描 driver 残留。
• 带 --include-orphans 时，--driver、--older-than 同时过滤记录和残留；--status、--agent 只过滤记录。任何仍关联已知 sandbox 记录的 runtime 资源都不会成为 orphan。
• ownership 不完整、manifest 损坏、路径越界、仍 active 或 schema 未知的残留会显示为不可删除；即使 --force 也只会 skipped。
• sandbox prune 调用 daemon 的 SandboxService.PruneSandboxes use case，删除 sandbox 自有 runtime/data，不删除共享 cache artifact；cache inventory 仍由 cache prune 或 cache rm 管理。
• forced prune 中某个 sandbox 删除失败时，命令会继续处理后续匹配项，输出 skipped 项，并以非零退出码结束。失败的记录会回滚到删除尝试之前的状态，从而保持可见、可重试，而不是停在 deleting；skipped 原因里带有 runtime 报错，因为运行时对象可能仍然存在。

sandbox stop 会应用 sandbox 创建时快照的 stopped-runtime 策略：retain 保留可恢复的 driver state；remove 先确认最近一次启动已经停止，再释放私有 runtime，同时保留 sandbox 的持久数据。为保持兼容，默认行为是立即 force stop。使用 --graceful 时，daemon 会拒绝新的 execution，向每个 active agent-compose-runtime 进程发送 SIGTERM，等待 JS runtime 取消 provider、执行已有的 finally 清理、持久化部分输出并退出。默认 grace period 为 10 秒，可通过 SANDBOX_GRACEFUL_STOP_TIMEOUT 修改；单次请求可用 --grace-period 覆盖，最大 5 分钟。等待超时或发送信号失败时，daemon 会先强制终止已跟踪 execution，再停止 sandbox。文本与 JSON 输出会给出 graceful、forced-after-grace-timeout 或 forced-after-grace-error。只要 sandbox 最终成功停止，升级为 force 仍属于成功的停止操作，因此 API 和 CLI 都返回成功，并保留 outcome 用于观测；只有 sandbox 本身无法停止时才返回错误。

Graceful stop 只覆盖由当前 daemon 进程启动并跟踪的 active guest execution；它不提供持久 cleanup hook、daemon 重启后的进行中 stop 恢复，也不管理 guest 内的 out-of-band process。

可使用 agent-compose inspect sandbox <sandbox> --json 查看有效策略和 release 状态。sandbox rm 在 <SANDBOX_ROOT>/.lifecycle 写入持久 deletion journal；running sandbox 必须显式使用 --force，删除会按可恢复阶段清理 driver resource、sandbox accessories、sandbox 目录和 metadata。处于 DELETING 的 sandbox 不能 resume，也不能接收新的 exec/run；daemon 启动时只继续未完成的 deletion journal，不会猜测或自动删除普通历史残留。删除阶段失败时，sandbox rm 会如实返回错误并把该 sandbox 记录回滚出 DELETING、恢复到删除前的生命周期状态——原本 failed 的仍是 failed，stop 已成功的则回到 stopped——因此删除失败既不会抹掉 sandbox ls -a 中可见的生命周期状态，也不会长期留下一个 DELETING 的 sandbox；只有 daemon 退出导致中断的删除会保持 DELETING，并由 daemon 启动时继续该 journal。

新建 sandbox 的目录位于 <SANDBOX_ROOT>/<年>/<月>/<日>/<sandbox-id>，日期取创建时 daemon 的本地日历时间，metadata 时间戳仍使用 UTC。升级时不会迁移已有的扁平 <SANDBOX_ROOT>/<sandbox-id> 目录，新版本仍可继续使用这些目录。旧版 daemon 不会扫描日期分层布局，因此降级后无法发现升级后新建的 sandbox，恢复新版本后可重新使用。如部署要求稳定的日期边界，应为 daemon 配置一致的 TZ。

stats：查看 sandbox 资源统计

查看运行中 sandbox 的资源统计快照。未指定 sandbox 参数时，显示当前 compose project 下所有 running sandbox 的统计。 project 级 stats 要求该 project 已存在于 daemon 中；执行 agent-compose down 后，需要先重新执行 agent-compose up，再使用不带 sandbox 参数的 stats。

agent-compose stats
agent-compose stats --json
agent-compose stats <sandbox>
agent-compose stats <sandbox> --json

输出字段包括 CPU 百分比、memory usage/limit/percent、network rx/tx、block read/write、uptime、driver 和 sampled_at。不同 runtime driver 无法提供的字段会在文本表格中显示 -，在 JSON 中保留稳定 key，并以 value: null 和 status: unknown 或 status: unavailable 表达。

driver 没有稳定 stats 能力入口时，命令会返回 unsupported，而不是普通 execution failed。

stop：停止 sandbox

停止一个或多个 sandbox。

agent-compose stop <sandbox>
agent-compose stop <sandbox> [<sandbox N>]
agent-compose stop --graceful [--grace-period 10s] <sandbox>
agent-compose stop --force <sandbox>

示例：

agent-compose stop sandbox_123
agent-compose stop sandbox_123 sandbox_456
agent-compose stop --graceful --grace-period 20s sandbox_123

--graceful 与 --force 互斥。不指定模式或显式使用 --force 都保留原有 force 行为。graceful outcome 与限制见上方 sandbox stop 说明。

resume：恢复 sandbox

恢复一个或多个 sandbox 运行。

agent-compose resume <sandbox>
agent-compose resume <sandbox> [<sandbox N>]

示例：

agent-compose resume sandbox_123
agent-compose resume sandbox_123 sandbox_456

rm：删除 sandbox

删除一个或多个 sandbox。

agent-compose rm <sandbox>
agent-compose rm <sandbox> [<sandbox N>]
agent-compose rm --force <sandbox>

选项：

行为规则：

• 删除非 running 状态的 sandbox 时，rm 会删除 sandbox 记录和相关运行态资源。
• 对 running 状态的 sandbox 执行 rm 会失败，并提示 sandbox is running。
• 如果确认要删除 running sandbox，必须显式使用 --force。强制删除会先停止 sandbox，再删除相关资源。
• 删除 sandbox 不会删除 project 配置。

示例：

agent-compose rm sandbox_123
agent-compose rm sandbox_123 sandbox_456
agent-compose rm --force sandbox_789

exec：在 sandbox 中执行命令

在运行中的 sandbox 内执行命令，语义类似 docker compose exec。

agent-compose exec <sandbox> -- <command> [args...]
agent-compose exec <sandbox> --command "..."
agent-compose exec <sandbox> --prompt "..."

选项：

位置参数 <sandbox> 与已弃用的 --run 目标互斥。如果同时提供，exec 会在解析任一目标或发送执行请求之前返回用法错误。

示例：

agent-compose exec sandbox_123 -- pwd
agent-compose exec sandbox_123 -- bash -lc "task test"
agent-compose exec sandbox_123 --command "git status --short"
agent-compose exec sandbox_123 --prompt "总结当前 workspace"
agent-compose exec sandbox_123 --cwd /workspace --command "pwd"

exec 与 run --command 使用同一套 guest agent-compose-runtime exec command output 路径。文本模式把 command stdout 输出到本机 stdout，把 command stderr 输出到本机 stderr，并经过 host 侧 marker filtering；不会额外 echo host wrapper command。--json 不输出流式 output，只输出最终 result。exec 不创建 ProjectRun；需要 run 审计、logs 或 run artifact 时使用 run --command。

logs：查看日志

查看当前 project 下 agent、sandbox 或 run 的日志。默认展示 project 下所有 agent 日志。

当前 logs 基于 agent-compose v2 RunService 返回的 run log artifact 展示。--follow 由服务端按 logs_path 指向的日志文件增量读取；普通查看会使用 run 记录中的输出和 artifact 汇总。它不会默认读取 Codex、Claude 等 provider 的私有日志文件。

agent-compose logs
agent-compose logs <agent>
agent-compose logs <project|agent|run|sandbox-id>
agent-compose logs --agent reviewer
agent-compose logs --run <run-id>
agent-compose logs --sandbox <sandbox>
agent-compose logs --event <evt-id>
agent-compose logs --follow
agent-compose logs -n 100
agent-compose logs -t

选项：

--run 和 --sandbox 是互斥的资源选择器。同时指定二者会返回用法错误，且不会发送日志请求。

--event 只接受完整事件 ID，不支持前缀匹配。daemon 服务端会解析该事件、其子孙事件及共享 correlation id 的事件，返回关联的 agent run，因此 --event 不能与 --run 或 --sandbox 同时使用。--event --follow 只跟随查询时已知的 run，不会自动发现之后新建的 run。logs --json 不能与 --follow 同时使用（用法错误），因此 --event 的 JSON 输出恒为单次快照。事件没有关联 run 时输出提示（JSON 模式输出空文档）并正常退出。--event 与 --agent 组合时由服务端过滤该 agent 的 run；过滤后没有 run 时输出同样的提示。

事件作用域上限为 1000 个事件（与事件 trace 视图一致）。若某事件的子孙事件与其 correlation 关联事件合计超过上限，超出部分事件——以及仅关联到它们的 run——不会出现在结果中；此时 CLI 会在 stderr 输出警告，ListRuns 响应也会通过 event_scope_truncated 字段标记截断。超大规模事件链建议改用事件 trace 视图排查。

示例：

agent-compose logs
agent-compose logs reviewer
agent-compose logs --agent reviewer --tail 200
agent-compose logs --sandbox sandbox_123 --follow -t
agent-compose logs --run run_123 --json
agent-compose logs --event evt_0e1c7bd2-8f5a-4c1d-9b3e-2f6a7d8c9e01

inspect：查看资源详情

查看 project 下资源、daemon image 或 runtime cache item 的详细信息。 inspect project 和 inspect agent <agent> 要求该 project 已存在于 daemon 中；执行 agent-compose down 后，需要先重新执行 agent-compose up，再使用它们。

agent-compose inspect project
agent-compose inspect project <project-name|project-id|short-id>
agent-compose inspect <project|agent|run|sandbox|image|cache>
agent-compose inspect agent <agent>
agent-compose inspect run <run-id>
agent-compose inspect sandbox <sandbox>
agent-compose inspect image <image>
agent-compose inspect cache <cache-id>
agent-compose inspect volume <volume>

当唯一参数是完整 ID 或十六进制短 ID 时，inspect 会通过 daemon 自动识别资源类型。名称仍需使用显式类型形式；短 ID 命中多个资源时，命令会报告歧义及候选资源类型。

对于 inspect project <project-ref>，位置参数中的 project ref 优先于 --project-name 和 --file。CLI 会先按精确 project name 解析，再按完整 ID 或唯一 short ID 解析；如果显式 ref 不存在或存在歧义，命令会直接失败，不会回退到 flag 或当前 Compose 文件选中的 project。不提供位置参数时，inspect project 继续使用常规的已部署 project 选择规则。

说明：

• inspect project 查看 project spec、revision、agent、scheduler 等信息。
• inspect agent <agent> 查看 agent 配置和运行摘要。
• inspect run <run-id> 查看一次 run 的详情。
• inspect sandbox <sandbox> 查看 sandbox/runtime 详情。
• inspect image <image> 查看镜像详情。
• inspect cache <cache-id> 查看一个 daemon runtime cache item，包括引用、阻止删除原因和 warnings。
• inspect volume <volume> 查看一个 daemon volume，包括 driver、label、option 和所属 project。

Project 和 agent 的 inspect 输出包含两个独立视图：

• declared_config：daemon 当前 project revision 中保存的完整脱敏配置，或其中被选中 agent 的配置。这是规范化后的已部署声明，不是即时读取的本地 YAML，也不是历史 run 的配置快照。daemon 未提供声明时，此字段为 null，CLI 不会用摘要字段拼装配置。项目级变量和命名资源可通过 inspect project 查看。
• runtime：daemon 当前的资源信息。project 包含 summary、agents、schedulers；agent 包含当前 agent 记录，包括可用性、健康状态、当前/最近 run 摘要、resolved_model、model_source 和当前的 scheduler_enabled。解析后的 model 是新 run 在没有请求或 session 覆盖时的默认选择，不一定是现有 sandbox 使用的 model。多次请求获得的运行状态不构成原子快照。

原有顶层 project、agent、scheduler 摘要以及最近 run、sandbox 字段继续保留以兼容已有使用方式。有效状态应优先读取 runtime；旧顶层 agent 摘要中的调度开关反映 apply 时的声明。新增视图采用 protobuf JSON，字段名使用 snake_case，枚举使用名称。project 和 agent inspect 无论是否指定 --json 都输出 JSON。

脚本默认完整输出，不按长度截断。对 project 或 agent 使用 --omit-scripts，可省略 declared_config 中非空的 scheduler.script 正文；omitted_scripts 数组会列出被省略字段的路径、原始 UTF-8 字节数和 SHA-256。空脚本仍保留为空，其他配置和运行状态不受影响。通过资源 ID inspect 时也支持此选项。例如：

agent-compose inspect agent reviewer --omit-scripts
agent-compose inspect project --json > project-details.json

标记为 secret 的环境变量/header 值，以及 workspace、skill、OctoBus 的结构化凭据会显示为 ********。脚本源码和其他自由文本不扫描内嵌凭据；应使用 secret 配置字段，避免把凭据硬编码到脚本中。

当 sandbox 保存了 workspace 快照时，inspect sandbox 会提供安全的 workspace_delivery 信息。mode 为 copy 或 mount；mount 还会显示 daemon 解析后的源目录 source_path、相对 guest workspace 的 target，以及 read_only。现有 workspace_path 仍指向 sandbox 自有目录。copy 快照不暴露私有源目录，输出中不包含 workspace 凭据或原始配置。缺少交付元数据时省略该字段；损坏的快照显示 mode: unknown。

"workspace_delivery": {
  "mode": "mount",
  "source_path": "/srv/project/source",
  "target": "reference",
  "read_only": true
}

镜像命令

管理 daemon 或当前 project 相关的镜像。

agent-compose image ls
agent-compose image pull
agent-compose image pull <image>
agent-compose image build [agent...]
agent-compose image rm <image>
agent-compose image inspect <image>

命令说明：

• image ls：列出镜像。
• image pull：拉取当前 project 中所有 agent 引用的镜像。
• image pull <image>：拉取指定镜像；如果本地 OCI image backend/store 已存在该镜像，会直接成功并输出 skipped/already exists warning，不会再次 pull。
• image build [agent...]：构建所有 project agent 配置的镜像；提供 agent 名称时只构建指定 agent 的镜像。
• image rm <image>：删除镜像 metadata/store entry。OCI 模式下只删除逻辑 metadata ref；无引用的物理 manifest/blob 由 CacheService 显式回收。该命令不删除 materialized 或 runtime-derived cache。
• image inspect <image>：查看镜像详情。

以下顶层命令是对应 image 子命令的快捷别名：

常用选项：

Cache 命令

查看并显式清理 daemon runtime cache inventory。只有 daemon 会扫描 cache path 并执行删除；CLI 只发送过滤条件并展示结果。

agent-compose cache ls
agent-compose cache inspect <cache-id>
agent-compose cache prune
agent-compose cache rm <cache-id>
agent-compose inspect cache <cache-id>

Cache domain 在 CLI 中用 --type 表示：

• oci：daemon OCI image store 中的物理 manifest、blob 和中断项。
• materialized：从镜像派生出的 runtime 输入，例如 BoxLite OCI layout 或不可变的 Microsandbox qcow2 母盘。
• runtime：driver home 下可跨 sandbox 复用的 runtime-derived image。
• skill：content-addressed skill artifact 及中断的临时/lock 项。

保护状态：

• active：正在被 running/resuming runtime 使用，永不删除。
• referenced：存在 REQUIRED 引用，例如 OCI metadata 或 running/stopped sandbox dependency。即使带 --force 也不可删除。ADVISORY 引用只用于展示，不阻止删除。
• unused、expired、orphaned：设置 --force 后可删除。
• unknown：引用或安全检查不完整，永不删除。

常用选项：

示例：

agent-compose cache ls --type materialized
agent-compose cache inspect <cache-id>
agent-compose cache prune --driver boxlite --unused
agent-compose cache prune --type skill --orphaned --force
agent-compose cache prune --expired --force
agent-compose cache prune --older-than 7d --force
agent-compose cache rm <cache-id> --force

CACHE_TTL 默认 168h，设为 0 会禁用 expired 判定；TTL 不会触发后台或启动时删除，必须显式执行 cache prune --expired --force。--older-than 仍是独立过滤条件。cache prune 和 cache rm 默认 dry-run；--force 只授权执行，不能绕过 active、referenced 或 unknown 保护。BoxLite v0.10.4 ABI 不提供安全 image remove/prune，因此 runtime image inventory 只读；Microsandbox 共享 image 使用 SDK inventory/remove API。sandbox prune 不删除 cache artifact。

Microsandbox 根文件系统使用 DATA_ROOT/image-cache 下的不可变 qcow2 母盘，并为每个 sandbox 在 MICROSANDBOX_HOME/rootfs-disks 下创建私有 qcow2 子盘。只要任何 rootfs sidecar 仍指向母盘，该母盘就会被标记为 referenced 且不可删除。stop/resume 保留私有子盘；sandbox remove/prune 删除子盘及其 ownership sidecar。母盘与子盘记录的是 daemon 挂载命名空间中的路径，因此备份和迁移必须同时移动两棵目录树，并保持 daemon 可见路径不变。一个 DATA_ROOT 只能由一个 daemon 实例独占，不能并发共享。只有当 sidecar 指向该 image cache 内合法的母盘路径时，母盘才会被计入引用；sidecar 无法读取或指向其他位置时会输出 warning，并把所有母盘标记为 unknown 直到它被修复或删除——因为此时已无法确认它保护的是哪一块母盘。

新建 Microsandbox sandbox 会把 /var/lib/docker 直接放在这块私有 ext4 根盘中，不再创建独立的 docker-disks/*.raw mount。因此 SANDBOX_DISK_SIZE_GB 是系统文件与 Docker 数据共享的一份逻辑容量，默认 6 GiB，不会自动翻倍。该变更不兼容旧版本创建的 Microsandbox sandbox：agent-compose 不再识别、迁移或删除旧 Docker raw 盘。升级前必须使用旧版本排空并删除这些 sandbox；确认数据不再需要后，再手工归档或删除 <MICROSANDBOX_HOME>/docker-disks。升级后不要依赖 sandbox remove 或 managed-resource prune 清理该目录。

Microsandbox 解析 guest 镜像时优先使用可达的 Docker daemon，daemon 不可用时改用 agent-compose 自己的 image cache，顺序与 BoxLite driver 一致；Microsandbox 自身始终不访问任何 registry。两条路径的认证方式不同：Docker daemon 使用它自己的凭据，image cache 使用 daemon 进程的 keychain 以及 IMAGE_REGISTRY、IMAGE_INSECURE_REGISTRIES，因此没有 Docker daemon 的部署需要配置 image cache 一侧。发生回退时会输出 warning，且来源会写入母盘的 cache identity，cache ls 可以看出每块母盘由哪条路径产出。pull policy 失败不触发回退，pull_policy=never 不会被另一条路径绕过。两条路径使用不同的解包实现，因此各自持有独立母盘；同一镜像若两条路径都解析过会构建两份。

首次升级到 disk-image rootfs 时需要一次性切换：先排空 Microsandbox workload，删除现有 Microsandbox runtime sandbox，再仅删除各镜像 cache 中旧的 rootfs/ 目录和 .rootfs.ready 标志。不要删除整个镜像目录，因为 BoxLite 的 oci/ cache 和新的 Microsandbox 母盘共用该目录；/data 下的 workspace 与 agent state 必须保留。daemon 镜像会提供 qemu-img 和支持 -d 的 mkfs.ext4；原生部署需要安装这两个工具。该方案不要求支持 reflink 的文件系统、loop device 或特权 mount。

daemon 可以选择启用两条相互独立的定时保留策略。WORKSPACE_CLEANUP_TTL 保持原有的 workspace-only 行为：最新一次 sandbox stop 被确认并达到期限后，agent-compose 删除 workspace，但保留 metadata、logs、state 和其他审计数据。SANDBOX_RETENTION_TTL 控制完整的 stopped-sandbox 保留流程：必要时先回收 workspace，再把剩余的 sandbox 自有数据和 lifecycle ownership record 打成归档。两者都接受非负 Go duration，默认值均为 0，表示禁用对应策略；同时启用时可以先回收 workspace，之后再由 sandbox retention 归档并删除其余数据。

sandbox retention 归档包含 metadata、VM/proxy 状态、logs、home、state、context 和 guest runtime 目录，并跳过 workspace 与顶层 volumes bridge 目录。archive 与 manifest 提交并重新校验身份、大小和 SHA-256 后，正式的 sandbox removal coordinator 才会删除 runtime、volume bridge、附件、列表索引、ownership record 和整个原 sandbox 目录。workspace 删除或归档失败时，尚存的原件会保留用于后续重试。

归档以 tar.zst 和 SHA-256 JSON sidecar 写入 SANDBOX_ARCHIVE_ROOT，默认位置为 <data-root>/archives/sandboxes。daemon 会拒绝与 SANDBOX_ROOT 相同、位于其下或经 symlink 解析后进入其中的归档根目录。归档位于 sandbox ownership tree 之外并在自动删除后继续存在；当前版本不提供归档 list、download、restore、retention 或 delete API。归档可能包含 provider 状态、凭据、prompt 和日志，运维方必须保护并显式管理该目录。workspace source、声明的外部 volume（包括 BoxLite bind-mounted volume bridge）和 driver 私有 runtime 磁盘不会复制进归档；归档完成后由各 runtime 所有者的正式边界删除 driver 资源。

IMAGE_CACHE_CLEANUP_TTL 独立清理 IMAGE_CACHE_ROOT 自有且未被引用的 OCI 与 materialized 数据，优先使用最后使用时间，没有时回退到拉取时间或文件修改时间；默认 0，即关闭该 cleaner。CLEANUP_INTERVAL 默认 1h，因此 duration 清理最多可能延迟一个 interval。自动清理不会处理 Docker daemon 镜像、BoxLite home 或 Microsandbox SDK cache，也不实现磁盘空间水位策略。

兼容说明：

• image 命令组是规范形式：image ls、image pull、image build、image rm 和 image inspect。
• 顶层 images、pull、build 和 rmi 命令是对应 image 子命令的快捷入口。两种写法都受支持，且都不会输出 deprecated warning。

Volume 命令

管理 daemon 拥有的 volume。

agent-compose volume ls
agent-compose volume create <name>
agent-compose volume inspect <name>
agent-compose volume rm <name>
agent-compose volume prune

命令：

常用参数：

LLM Provider 命令

管理 daemon 上由 API 拥有的上游 LLM provider。

agent-compose llm provider ls
agent-compose llm provider create <id> --base-url <url> --protocol <protocol> --api-key <key>
agent-compose llm provider inspect <id>
agent-compose llm provider update <id> --name <name>
agent-compose llm provider rm <id>

命令：

参数：

status：检查 daemon 状态

检查当前选择的 daemon 状态和版本。

agent-compose status
agent-compose --host http://127.0.0.1:7410 status
agent-compose status --json

默认输出字段：

• STATUS：daemon 响应状态。
• UPTIME：daemon 返回的时间戳；如果 daemon 返回了时区信息，则按 daemon 时区展示。
• VERSION：daemon 构建版本。

status 请求的超时时间为五秒。自动化场景使用 --json 输出 daemon 原始 status 响应。

其他命令

agent-compose daemon
agent-compose status
agent-compose version
agent-compose config
agent-compose config --quiet

• daemon：启动 agent-compose daemon。
• status：检查 daemon 状态。
• version：输出 CLI 构建版本。
• config：解析、校验并输出 normalized project 配置。
• config --quiet：只校验配置，不输出 normalized config。

暂缓命令

以下命令或能力尚未作为稳定 CLI 发布：

• push：image push 暂缓。
• up -d/--detach：当前 up 本身就是 apply project 后返回，不提供 detach 参数。
• up 前台 attach 和 Ctrl+C 停止整个 project：暂缓。

使用建议

• 使用 up 将 project 应用到 daemon 后，通过 ps、logs 观察状态。
• 跨目录操作 project 时使用 -f /path/to/project/agent-compose.yml 或 -f /path/to/project/agent-compose.yaml。
• 操作远程 daemon 时显式传入 --host，并确认目标 daemon 上的 project 名称和配置文件路径符合预期。
• 脚本和自动化系统使用 --json，避免依赖表格列宽或文本排版。

Agent 原生遥测

在 daemon 环境（部署时的 .env 文件）中配置后重启 daemon。新的执行，包括恢复的 sandbox 中的新执行，都会收到当前设置；已经运行的 provider 进程仍使用启动时的设置。

AGENT_TELEMETRY_OTLP_ENDPOINT=http://collector.example:4318
# 可选认证；值使用百分号编码，例如空格写成 %20。
# AGENT_TELEMETRY_OTLP_HEADERS=Authorization=Bearer%20your-token
# AGENT_TELEMETRY_CAPTURE_CONTENT=true

地址是 OTLP/HTTP 基础 URL，runtime 按信号追加 /v1/logs、/v1/traces 或 /v1/metrics。支持 URL 路径前缀；信号路径后缀、URL 用户凭证、查询参数和 fragment 会在启动时被拒绝。collector 必须支持 Codex、Claude 和 OpenCode 使用的 OTLP/HTTP JSON； DSH 使用其原生 OTLP/HTTP logs exporter。此集成不支持仅接受 gRPC 的 collector。 地址必须从 sandbox 内部可达，不能仅从 daemon 可达；localhost 指向 guest 自身。 daemon 也会把自身 span 与 metrics 导出到同一地址，因此在启用（endpoint 非空）时 collector 还必须从 daemon 主机可达。系统不会自动部署 collector 或开放端口。

此初版同时启用表中 provider 支持的信号，没有单独的信号选择器。同一地址还使 daemon 导出 自身的 OTLP/HTTP traces 与 metrics：每个 daemon RPC 一个 server span，每次执行（流式与 attach）一个 invoke_agent span，runtime driver 操作的 sandbox.ensure、sandbox.stop、 sandbox.remove、sandbox.exec、sandbox.interaction span，guest 镜像解析的 image.pull span，以及 run volume 解析的 volume.prepare span。这些 span 会按可用情况携带 agent_compose.run.id、agent_compose.project.id、agent_compose.agent.name、 agent_compose.sandbox.id、agent_compose.driver 和 gen_ai.* 属性。invoke_agent 及其 gen_ai.* 属性遵循 OpenTelemetry GenAI 语义约定，该约定仍标记为 Development：名称可能在后续 版本变化，不构成兼容性承诺。daemon 不记录 invoke_workflow 或 execute_tool span，因为 workflow 与工具执行都发生在 guest 内；provider 自行导出的 span 会挂在 daemon 的 invoke_agent span 之下。

daemon 还向同一地址导出以下 metrics：agent_compose.run.duration 与 agent_compose.run.count（按终态的 run 时长与成功率）、 agent_compose.sandbox.create.duration，以及 agent_compose.driver.operation.count （按操作与结果统计的 driver 错误率）。metric 标签保持低基数（driver、operation、outcome、 run 状态）；run、project、agent 标识只保留在 span 与事件中，因此 metrics 不会成为逐 run 的 身份存储。

daemon 插桩只记录操作状态：daemon 不把 agent-compose 事件流转换为 spans，也不导出 prompt、工具或错误文本。Pi 1.3.0 没有已集成的 OTLP exporter；其 环境变量参考 说明 PI_TELEMETRY 控制安装与更新统计，不是 OTLP 开关。

endpoint 为空时关闭 daemon 管理的导出，但不会删除用户在 guest 中自行配置的原生遥测设置。 启用时，受支持 provider 继承的 OTEL_* 地址、headers 和 beta tracing 地址会被替换， 避免旧的分信号环境变量把 collector 凭证发往其他地址。Codex 的 header 名不能包含点， OpenCode 的 header 值不能包含逗号；常见的 Authorization=Bearer%20... 在各 provider 中均可用。 collector 凭证不会写入共享 provider 文件或 sandbox 持久化配置，但运行中的 guest 进程能读取 这些凭证；这不是对 guest 内执行代码的凭证隔离机制。

AGENT_TELEMETRY_CAPTURE_CONTENT 默认 false：关闭 Codex/Claude 支持的 prompt 和工具内容开关， 关闭 OpenCode LLM spans，并跳过 DSH FULL 导出。它不是通用脱敏器：原生诊断日志、错误和 provider 特有字段仍可能包含内容，需要按实际要求在 collector 配置脱敏。设置为 true 可能导出 prompt、回答、工具参数/结果和文件内容。DSH 检查实际安装的 backend，而不是仅看 CLI 版本：rc.6 backend 支持 FULL，较新 backend 可能不支持。不兼容时提示并跳过导出，不阻塞 agent，也不会 静默退回反馈上传或厂商地址。

Resource attributes 包含 agent_compose.sandbox.id、agent_compose.provider，以及可获得的 run/project ID；DSH 通过原生记录钩子将这些属性附加到 log records。原生 session ID 仍由 provider 定义，关联属性不会自动形成跨 provider 的统一分布式 trace。

若调用方已有分布式 trace，可在启动执行的 daemon RPC 上携带 W3C trace context 的 traceparent（以及可选的 tracestate）header。启用 daemon 插桩时，daemon 自身的 server、 run 与 runtime driver span 会作为调用方上下文的子 span 接入该 trace，使一次请求的 daemon 操作与 guest provider span 共享同一 trace ID。daemon 校验这两个值后，通过 agent telemetry 载荷转发给支持入站父上下文的 provider，使其导出的 span 接入调用方的 trace，而不是新起一个 根；从载荷继承 daemon run span 的 provider 则挂在该 invoke_agent span 之下。Codex 与 Claude Code 会采纳该 trace context；在当前受支持的版本中，OpenCode 与 DSH 不提供入站父 上下文机制，因此仍会各自新建 trace 根。该中继复用承载 collector 设置的每次执行 telemetry 载荷，因此需要启用 agent telemetry（AGENT_TELEMETRY_OTLP_ENDPOINT）才能到达 guest；header 本身既不开启导出也不改变导出目标。header 缺失或格式非法时会被忽略：执行与 引入该字段前完全一致地以自身为根，且不会向 sandbox 或其配置持久化任何内容。

普通 prompt、交互式 prompt session 和 workflow 子 agent 使用同一配置。 exporter 自行管理批处理与重试，collector 不可达不属于 agent 健康检查。正常退出可以刷新 缓冲数据，强制终止仍可能丢失数据；用于审计前应使用实际 guest 版本验证收包。