Handbook

Fleet dispatch operator guide

Program D: bounded parallel campaign fan-out to Forge Fleet nodes. Design contract: docs/design/FLEET-DISPATCH.md.

Updated 2026-07-06

When to use

Set FORGE_DARK_FACTORY_DISPATCH=fleet on the host running pdca.run_campaign. Each eligible campaign item becomes a docker_argv job on a healthy Fleet node; the container runs one item via the lmeta driver; the host ingests artifacts and re-runs assay + freeze gates.

Rollback: unset FORGE_DARK_FACTORY_DISPATCH → existing sequential local path.

Host flags

Variable	Default	Meaning
`FORGE_DARK_FACTORY_DISPATCH`	unset	`fleet` enables fan-out
`FORGE_DARK_FACTORY_DISPATCH_MAX_PARALLEL`	`2`	Max in-flight remote items
`FORGE_DARK_FACTORY_DISPATCH_REQUIRE_REMOTE`	unset	`1` → hard error when zero eligible nodes
`FORGE_FLEET_SERVERS_FILE`	—	Path to `fleet-servers.json` (see below)
`FORGE_FLEET_BASE_URL` / `FORGE_FLEET_BEARER_TOKEN`	—	Single-node fallback when no file

Items whose worker_ladder includes cursor are not dispatched (host-local only).

Fleet servers config

Copy config/fleet-servers.json.example and edit. Node shape matches Lenses Studio fleet-settings.json nodes[].

{
  "nodes": [
    {
      "id": "granite-host",
      "base_url": "http://127.0.0.1:18766",
      "bearer_token": "YOUR_TOKEN",
      "enabled": true,
      "priority": 100,
      "max_cpu_percent": null,
      "max_memory_percent": null
    }
  ]
}

Never commit bearer tokens. Traces record node_id, job_id, and base_host only.

Container template

Build the agent worker image from the repo root:

docker build -f docker/agent-worker/Dockerfile -t forge-agent-worker:latest .

PUT /v1/container-templates — requirement id forge-agent-worker
POST /v1/container-templates/build — or set build_template_if_missing in job meta (dark-factory does this by default)

Image bundles vendored forge-lcdl, forge-workcells, and forge_dark_factory (editable installs). No Fleet bearer or Cursor credentials in the image.

Local smoke

Ensure Fleet listens (user install often 127.0.0.1:18766).
Point FORGE_FLEET_SERVERS_FILE at your config.
Run a small offline campaign with worker_ladder: [fake] and dispatch enabled.

export FORGE_DARK_FACTORY_DISPATCH=fleet
export FORGE_FLEET_SERVERS_FILE="$PWD/config/fleet-servers.json"
PYTHONPATH="forge-lcdl/src:forge-workcells/src:src" python3 -m forge_dark_factory.pdca_cli campaigns/your-campaign.yaml

Traces

After ingest, machine/run.json includes:

"dispatch": {
  "mode": "fleet",
  "node_id": "granite-host",
  "job_id": "…",
  "base_host": "127.0.0.1:18766"
}

Human report.md includes one Fleet dispatch line (regenerated from machine records).

LCDL client

Host code uses forge_lcdl.dispatch.fleet (leaf module). See forge-lcdl/docs/dispatch/fleet.md.

Forge Dark Factory