Orchestrator 与 Sandbox

以 CLI Host 运行 iPolloWork、解析已验证 sidecar，并在任务需要时加入明确的 Docker 或 Apple container 边界。

ipollowork-orchestrator 是 iPolloWork Server 与 OpenCode 的 CLI-first Host。当产品需要不带 Electron UI 的 Host 运行时、远程客户端需要配对到工作区，或操作员需要用一个状态界面观察两个 sidecar 时使用它。

Host 拓扑Orchestrator 负责进程组装；Server 负责工作区访问

不要把 sidecar 下载策略、工作区权限与 sandbox 挂载混成一个无限制的 Host 进程。

Orchestrator CLI

进程组装与操作员输出

Start / serve

启动 iPolloWork Server 与 OpenCode，并统一观察健康与生命周期。

状态 / 配对

默认输出连接信息时会隐藏实时凭据。

Sidecar 解析

已验证的运行时来源

Server 与 OpenCode

从 bundled、downloaded 或显式 external 来源解析。

Manifest 检查

下载 sidecar 使用 SHA-256 manifest；开发覆盖必须显式开启。

执行边界

Host 或 container

工作区挂载

目标工作区是核心文件系统边界。

可选 Sandbox

Docker 或 Apple container sidecar 可增加 Linux 执行边界。

有意识地启动 Host

需要独立 Host 部署单元时，可以全局安装 CLI：

npm install -g ipollowork-orchestrator
ipollowork start --workspace /path/to/workspace --approval auto

需要纯日志模式时，使用 ipollowork serve --workspace /path/to/workspace 或 --no-tui。在已检出的仓库内进行源码开发时，可使用包的开发命令并显式选择本地 sidecar：

pnpm --filter ipollowork-orchestrator dev -- \
  start --workspace /path/to/workspace --approval auto --allow-external

--allow-external 是开发覆盖，不是中性的生产默认值。它会让 sidecar 来源可见，而不是无声地接受机器上的任意二进制文件。

Sidecar 策略是发布决策

Sidecar 解析在接受进程边界之前先解析运行时来源

Host 应报告实际解析结果，然后对完整路径进行 health check。

01选择来源
使用自动、bundled、downloaded 或显式 external 的来源策略。
02验证产物
下载的 sidecar 通过 Orchestrator manifest 使用 SHA-256 验证。
03启动配对
启动 iPolloWork Server 与 OpenCode，并始终显式传入工作区目录。
04证明使用
运行 Host status，并执行真正要使用该运行时的客户端路径。

CLI 支持通过 --sidecar-dir 或 IPOLLOWORK_SIDECAR_DIR 指定缓存位置，通过 --sidecar-base-url 与 --sidecar-manifest 指定批准的产物来源，通过 --sidecar-source 选择 iPolloWork Server 来源，并用 --opencode-source 选择 OpenCode 来源。使用 --verbose 或 IPOLLOWORK_VERBOSE=1 可查看解析后的二进制诊断信息。

当任务需要 container 边界时使用 Sandbox

# 自动选择受支持的后端
ipollowork start --sandbox auto --workspace /path/to/workspace --approval auto

# 有意识地选择一种
ipollowork start --sandbox docker --workspace /path/to/workspace --approval auto
ipollowork start --sandbox container --workspace /path/to/workspace --approval auto

--sandbox auto 会在受支持的 arm64 Mac 上优先选择 Apple container，其他环境选择 Docker。Docker 需要 docker CLI，Apple container 模式需要 container CLI。Sandbox 模式下会解析 Linux 目标的 downloaded sidecar，并且不支持任意自定义 --*-bin 覆盖。

额外挂载需要在 allowlist 中声明。只添加任务需要的数据，并在合适时显式声明名称和只读模式：

ipollowork start --sandbox auto \
  --sandbox-mount "/path/on/host:datasets:ro" \
  --workspace /path/to/workspace

除非 IPOLLOWORK_SANDBOX_MOUNT_ALLOWLIST 指定其他 allowlist，Host 会按 ~/.config/ipollowork/sandbox-mount-allowlist.json 验证额外挂载。容器不是任意挂载主机数据的权限。

多工作区 Router 模式

多个工作区需要同一智能体 Host 时，使用 daemon，而不是为每个目录启动一个未管理的 OpenCode 进程：

ipollowork daemon start
ipollowork workspace add /path/to/workspace-a
ipollowork workspace add /path/to/workspace-b
ipollowork workspace list --json

Router 保持一个 OpenCode 进程，并按请求的 directory 即时切换工作区。测试时用 IPOLLOWORK_DATA_DIR 或 --data-dir 隔离 Router 状态；工作区实例结束生命周期时，应显式 dispose。

运维检查

使用 ipollowork status --ipollowork-url http://<host>:8787 --opencode-url http://<host>:4096 检查配对运行时。Smoke check 可以启动服务、验证 health 与 SSE event，并干净退出：

ipollowork start --workspace /path/to/workspace --check --check-events

需要可关联的 JSON 日志时，设置 IPOLLOWORK_LOG_FORMAT=json，并在运维系统需要稳定关联值时提供 --run-id。发布门禁和故障路径请继续阅读 可观测性与恢复。