BOWLUNA/dsh-zcode-farm

English | 中文

Let the DeepSeek Harness agent see a whole farm of ComfyUI instances and dispatch each job to the idlest one.

Zero runtime dependencies · Node ≥ 22 · MIT

---

Why this exists

ComfyUI's own docs are explicit: one ComfyUI process executes one workflow at a time. Real concurrency only comes from running one process per GPU and routing each job to the least-busy instance. The ecosystem already has pooling libraries such as comfyui-orchestrator.

But when you wire that up to an AI agent, one piece is missing: the agent can't see the farm.

Measured on a real machine (a single moment on 2026-09-21, taken with this plugin's own probe):

Instance	GPU	Free VRAM	Queue	Verdict
18100 ← the only one dsh-comfyui can see	RTX 5090	0.8 / 33.7 GB	1 running	too full
18300	RTX 5090	0.8 / 33.7 GB	1 running	too full
18301	RTX 5090	0.9 / 33.7 GB	1 running	too full
18302	RTX 5090	0.5 / 33.7 GB	1 running	too full
18303	RTX PRO 6000 Blackwell	99.4 / 102.0 GB	0	✅ idle

dsh-comfyui (77★, the most mature plugin in this space) talks to one endpoint, so every generation request hits the busiest machine — while 102 GB of VRAM sits idle.

This plugin fills exactly that gap: let the agent see, then let it dispatch.

---

What it does

Three tools:

Tool	Purpose
comfyui_farm_status	Full farm view: per-instance GPU, free VRAM, queue depth, what's running, and who should get the next job
comfyui_farm_pick	Choose without executing: filter by VRAM floor / queue ceiling / GPU-name hint / exclude list, and get the reason
comfyui_farm_run	Load-aware dispatch: auto-pick (or force an instance), accepting a raw API workflow or a one-shot "prompt + checkpoint" text-to-image

---

Install

dsh plugin --profile web add dsh-zcode-farm

Restart the app and the agent gets all three tools.

---

Configuration

- id: comfyui-farm
  config:
    primaryUrl: 'http://127.0.0.1:8188'
    instances:
      - { id: gpu-18301, baseUrl: 'http://127.0.0.1:18301', label: '5090 shard' }
      - { id: gpu-18303, baseUrl: 'http://127.0.0.1:18303', label: 'Blackwell 102G' }
    needVramGb: 8
    maxQueueDepth: 3
    queueWeight: 1000
    probeTimeoutMs: 5000
    probeRetries: 1

How an instance is chosen (two stages)

1. Filter — unreachable, or free VRAM < needVramGb, or queue depth > maxQueueDepth → out.
2. Rank — score = freeVramGb − queueDepth × queueWeight

The default queueWeight = 1000 is deliberate: queue depth dominates the ranking and free VRAM only breaks ties. That matches the intuition — an idle small GPU finishes sooner than a busy large one.

Prefer "biggest VRAM wins"? Set queueWeight: 0.

---

Relationship to dsh-comfyui: complementary, not competing

	dsh-comfyui	dsh-zcode-farm
Scope	one endpoint	a whole farm
Strength	workflow library, skill packs, canvas, asset panel	awareness, selection, dispatch
Assembly row id	comfyui	comfyui-farm

The row ids differ, so both can be installed side by side. Neither depends on the other.

---

Design notes

• Zero runtime dependencies. Node's built-in fetch / AbortController only.
• No workflow editing. That's dsh-comfyui's territory; this plugin only answers "who gets it".
• No assumption of locality. Every member is just a URL — SSH tunnels, LAN and remote hosts are treated identically. The 5 tunnels on the test machine are plain ssh -L forwards.
• Probe failures are retried. Tunnel flakiness is real: the same instance once timed out at >3s and answered in 106ms on the very next call. A single failure is not a verdict — we retry, then report attempts so the agent can tell "down" from "hiccup".
• Failure reasons are never overwritten. When filtering by GPU hint, an unreachable instance keeps its "unreachable" reason instead of being relabelled "GPU mismatch", which would hide the actual problem.

---

Development

npm test                              # unit tests (pure functions, no network)
node probes/probe-farm.mjs            # standalone probe: farm status only
node probes/probe-tools.mjs           # load the entry and really execute the tools (read-only)
node probes/probe-tools.mjs --run     # actually dispatch one job (smallest payload: 512² / 12 steps)

During development the host-provided peer deps (@deepseek-ai/schemastery and its deps) must be present in a local node_modules/, otherwise the entry cannot be imported. This is not needed when installed into a real profile — the host supplies them.

---

Known limitations

• The built-in template of comfyui_farm_run covers minimal text-to-image only (KSampler + CheckpointLoaderSimple + EmptyLatentImage + 2× CLIPTextEncode + VAEDecode + SaveImage). For anything richer, pass a workflow.
• Aliases pointing at the same backend are not detected. If you configure both a switchable forwarder (e.g. 127.0.0.1:8188 → "currently focused instance") and its real target, you will see two members with identical readings. That is honest reporting, not a bug — probing cannot distinguish them.
• number returned by /prompt is a server-side cumulative counter, not a queue position (measured: it returns 22 even when the queue is empty). Trust comfyui_farm_status for real queue depth.

---

License

MIT

---

Status

• 1 suite, 15 checks — run node test/run.mjs
• Declared compatibility: >=0.1.5-rc.2 <0.2.0-0 (see engines.dsh and the peer range)
• Pin the version to bypass pnpm's release cooldown: dsh plugin --profile web add dsh-zcode-farm@1.0.1
• Verified against five SSH-tunnelled ComfyUI instances plus one switchable forwarder