Bach Docker

Bach Docker is the standalone agent/legion Docker package system.

The current truth source is a YAML package plus blob resources:

• package.yml is the compose-like index.
• legion.yml or *.agent.yml is the pre-materialization runtime spec.
• resources/** carries skills, scripts, wiki, docs, hooks, and other diffable assets.
• Hub package responses expose materialized manifest.genome, blob files, lineage, and specDiff.

CLI

After install/build, the user-facing commands are:

legion list
legion search gstack
legion pull @official/gstack-squad
legion run @official/gstack-squad --workspace-mode isolated

For local QA without npm install:

CARGO_TARGET_DIR=/tmp/bach-docker-codex-target cargo build -p agent-docker-cli --bins
BACH_DOCKER_HUB_URL=http://127.0.0.1:3116 PATH=/tmp/bach-docker-codex-target/debug:$PATH /tmp/bach-docker-codex-target/debug/legion search gstack

Model Routing

Claude runtime keeps allowlisted CLI model names in the image, then rewrites the provider config per agent before launch. 中文规则：image 声明角色要走哪个 provider；runtime 只接受显式 route 配置，不做 provider/model fallback。

Public official packages must not embed router URLs or API keys. They declare a modelRouter.route.provider; runtime reads provider settings from env or ~/.agent-docker/settings.json. bach-docker gstack 默认使用 isolated workspace，避免从 ~ 启动时把 image 内的 .agent-docker/settings.json 写回用户全局配置。

Required setting keys are derived from provider ids:

{
  "BACH_DOCKER_ROUTE_KIMI_VISION_BASE_URL": "https://...",
  "BACH_DOCKER_ROUTE_KIMI_VISION_AUTH_TOKEN": "...",
  "BACH_DOCKER_ROUTE_GLM_5_1_BASE_URL": "https://...",
  "BACH_DOCKER_ROUTE_GLM_5_1_AUTH_TOKEN": "...",
  "BACH_DOCKER_ROUTE_ANTHROPIC_OPUS_POOL_BASE_URL": "https://...",
  "BACH_DOCKER_ROUTE_ANTHROPIC_OPUS_POOL_AUTH_TOKEN": "..."
}

Structured settings are also accepted. The runtime flattens only explicit provider pools; generic ANTHROPIC_BASE_URL is not used as a provider fallback for a routed legion member.

{
  "modelRoutes": {
    "kimi-vision": {
      "baseUrl": "https://kimi.example/coding",
      "authToken": "redacted"
    }
  },
  "routes": {
    "anthropic-opus-pool": {
      "routerUrl": "https://opus.example",
      "apiKey": "redacted"
    }
  },
  "modelRouter": {
    "providers": {
      "glm-5.1": {
        "url": "https://glm.example",
        "token": "redacted"
      }
    }
  }
}

Missing route settings hard-fail with SDK_ENV_MISSING_REQUIRED. No provider or model fallback is allowed.

如果 ~/.agent-docker/settings.json 已经有 modelRoutes.kimi-vision，日常使用只需要：

bach-docker gstack

Hub

Run the standalone Hub service locally:

BACH_DOCKER_HUB_SEED_DIR=$PWD/services/bach-docker-hub/seeds \
BACH_DOCKER_HUB_HOST=127.0.0.1 \
BACH_DOCKER_HUB_PORT=3116 \
node services/bach-docker-hub/src/server.mjs

Docker compose target:

docker compose -f deploy/bach-docker-hub/compose.yml up -d --build

Docker QA 需要 Docker Desktop 或其他可用 Docker daemon。如果 Docker 没有运行，该 gate 必须标记为 blocked，不能用本地 Node smoke 替代。

最新真实 image QA 证据：docs/qa/docker-image-real-qa-2026-05-06.md。当前状态是 partial pass：CLI 与 Hub images 可构建、可运行；Hub search/pull 可用；缺 route settings 会 hard fail；GLM/Kimi 真实 route 返回 QA_OK；Anthropic pool 真实失败为连接重置；AHA MCP 不可用。

Fallback Policy

Fallback 不能掩盖 bug。任何必要例外都必须记录到 docs/architecture/fallback-registry.md。