Overview

DeepSeek Harness (DSH) uses a plugin-based architecture. The way agent capabilities are extended is through toolsets provided by plugins. When deploying ComfyUI in local or cluster environments, running multiple ComfyUI processes is usually required to improve throughput, with each process corresponding to a GPU.

The existing mature plugin dsh-comfyui is mainly designed for a single endpoint. When an agent interacts with this single interface, it cannot perceive the load status of other nodes in the cluster. This causes all tasks to pile up on the most heavily loaded node, while idle GPUs remain unscheduled. The dsh-zcode-farm plugin fills this gap by allowing agents to “see” the entire ComfyUI cluster and providing load-aware scheduling capabilities.

Plugin Introduction

dsh-zcode-farm is a DeepSeek Harness plugin, belonging to the “Workflow” category and maintained by BOWLUNA.

Its core purpose is to allow agents to detect the real-time status of all instances in a ComfyUI cluster (GPU utilization, available VRAM, queue depth) and schedule tasks to the most idle instance according to preset rules, rather than blindly sending tasks to a single already saturated node.

Core Features

The plugin provides three core tools:

  1. comfyui_farm_status
    View the real-time status of the entire cluster. The returned data includes GPU information for each machine, remaining VRAM, current queue depth, running tasks, and the system’s suggested next task assignment target.
  2. comfyui_farm_pick
    Select an instance only, without executing a task. Supports filtering by minimum VRAM, maximum queue depth, GPU name, and exclusion list, and returns the specific reasons for selecting that instance (for example: sufficient VRAM and an empty queue).
  3. comfyui_farm_run
    Execute load-aware scheduling. It can automatically select the optimal instance (default behavior), or an instance can be forced. It supports receiving a raw API workflow or a simple text generation request.

Installation and Enabling

Install the plugin through the DSH command-line tool. After installation, restart the application so that the agent can access the new tools.

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

Configuration Notes

Declare the plugin instance and its parameters in the DSH configuration file (YAML format). You must configure primaryUrl as the base address and list the addresses of all ComfyUI nodes in the instances list.

Configuration example:

- 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

Node Selection Logic

The system uses a two-stage filtering mechanism:
1. Filtering: Remove unreachable instances, instances with remaining VRAM below needVramGb, and instances whose queue depth exceeds maxQueueDepth.
2. Sorting: Among candidate instances, calculate a score using the formula:
score = freeVramGb - queueDepth × queueWeight
The default queueWeight = 1000, meaning queue depth has a much greater impact on ranking than VRAM size. If you want to prioritize “larger VRAM first”, set queueWeight: 0.

Usage Examples

After installation and configuration, the agent can invoke the following commands:

# 查看全站状态
comfyui_farm_status

# 挑选一个空闲实例
comfyui_farm_pick

# 执行任务（自动调度）
comfyui_farm_run

Technical Features and Dependencies

  • Zero runtime dependencies: The plugin uses only Node.js built-ins such as fetch and AbortController, so no additional Python or C++ dependencies are needed.
  • No workflow editing capability: It is not responsible for editing ComfyUI workflow graphs; that is the responsibility of dsh-comfyui. It is only responsible for “who runs the job”.
  • No locality assumptions: The plugin treats all instances as a list of URLs. Whether they are behind an SSH tunnel, on the local network, or on remote hosts, the processing logic is completely identical.
  • Probe retry mechanism: To handle potential jitter in SSH tunnels, failed probes are retried automatically, and the number of attempts is returned in the result, making it easier for the agent to determine whether a node is truly unavailable.

Ecosystem Relationship

This plugin has a complementary, not competitive, relationship with dsh-comfyui (77★).

  • dsh-comfyui: Focuses on workflow management, skill packs, and canvas editing, while communicating with a single endpoint.
  • dsh-zcode-farm: Focuses on cluster awareness, instance selection, and load scheduling.

The two can coexist and do not depend on each other. dsh-comfyui handles the workflow logic, while dsh-zcode-farm is responsible for distributing the generated workflow to specific physical nodes for execution.

Notes

  1. Node.js version: Node.js >= 20 is required (according to the README) or >= 22 (according to the package.json reference).
  2. Permissions and security: The plugin runs with the permissions of the DSH process. Please inspect the source code and license (MIT) before installation.
  3. Engineering standards: This project follows some engineering conventions from the ZCode community (such as bilingual documentation validation and pre-commit checks), but the code itself is developed in-house and has no code inheritance relationship.

Summary

dsh-zcode-farm solves the scheduling blind spot for agents in multi-GPU environments. By providing status viewing, instance filtering, and load-aware scheduling tools, it enables DeepSeek Harness agents to efficiently utilize local or remote ComfyUI cluster resources and avoid task pileups on a single node.