Werk1112 supports two distinct ComfyUI integrations:
These choices are complementary. Neither turns werk serve into a ComfyUI
workflow server.
Start Werk with an image model and a configured API key:
werk auth api-key generate --name comfyUI
werk serve --image-model IMAGE_MODEL
Start ComfyUI with Werk as the hosted API base:
python main.py --comfy-api-base http://127.0.0.1:11434
The base is the Werk server root, without /v1, because ComfyUI calls:
POST /proxy/openai/images/generations
Set ComfyUI’s api_key_comfy_org value to the generated Werk key. The hosted
node sends it as X-API-Key, which Werk accepts. Its generation request uses
the same handler as POST /v1/images/generations and receives the expected
data[].b64_json output.
The hosted integration is intentionally narrow:
501 Not Implemented;werk serve --image-model;When ComfyUI runs in Docker, WSL, a VM or another host, replace 127.0.0.1 with
an address reachable from that environment and bind Werk accordingly. Do not
expose the unauthenticated service to an untrusted network.
Use the custom-node package when a workflow needs Werk-native behavior such as:
IMAGE, VIDEO and AUDIO values;IMAGE batches sent to POST /v1/chat/completions for visual QA and
image understanding;/werk/v1 capability and memory discovery;STRING or JSON socket.The text path uses WERK Text Models, optional WERK Text Config, and
WERK Text Generate. Text Config can enable oMLX expert offload with a MiB
budget and enable or disable thinking per request. Inherited controls omit the
extension; explicit controls require the server’s api.chat.omlx_options
capability. Connect Text Generate’s model_id output to runtime expert nodes
to ensure the model loads first. See the
text and expert-preview example.
The vision path uses WERK Vision Models, WERK Vision Config, and
WERK Vision Analyze. It is intended for inspecting rendered HTML, slides,
documents, generated images, and UI screenshots for missing elements,
overflow, clipping, alignment, spacing, and similar visual defects. Werk must
report the selected model/runtime as available for image-understanding;
text-only execution of a multimodal repository is not sufficient. See the
ready API-prompt example.
Installation, node sockets, workflow examples, limits and troubleshooting are maintained beside the package in the ComfyUI Werk1112 node documentation. That page is the source of truth for the custom nodes and is not duplicated here.
The custom nodes call Werk over HTTP. They do not load Werk models from ComfyUI’s own model directories, and they do not require Werk to implement a Comfy workflow graph.
The runtime nodes are additive. Existing inference nodes retain their /v1
requests and compatibility with older Werk servers. Runtime nodes deliberately
fail closed if the versioned /werk/v1 envelope, protocol version, capability
status, or typed response is missing or invalid. State prune defaults to dry
run and never removes models, artifacts, outputs, jobs, authentication data,
backend installations, or external output paths. Prefill returns an opaque
WERK_STATE_HANDOFF consumed only by Decode; it is excluded from visible JSON,
strings, representations, and error messages. Expert nodes are gated by
runtime.experts.residency; they expose all six capability statuses without
turning route presence into a support claim. The list permits read-only
externally_managed telemetry, while control requires supported or an
explicitly opted-in experimental capability. The oMLX SSD expert cache is
enabled per request in WERK Text Config, or by the server default
WERK_OMLX_EXPERT_CACHE_MB; once Text Generate has loaded the worker and it
confirms offload, expert nodes can use the experimental capability.
For oMLX, external means checkpoint-backed outside the cache and ram means
cached in Apple unified memory. Prefetch uses ram. Existing node fields and
other adapters’ capability checks remain compatible. See the custom-node guide
for activation and memory-budget details.
The ordinary image, video and audio nodes use Werk’s media execution workers
and their process-local model/pipeline LRUs. Vision Analyze uses the selected
text or multimodal backend’s normal /v1/chat/completions path. Neither path
creates named Prefill state. Only the explicit Prefill and Decode runtime nodes
use the opaque state-handoff protocol. werk serve --persistence supplies
defaults omitted by Prefill requests and, for a local Werk-started vLLM process,
supplies the native APC default unless explicit vLLM arguments override it.
For local oMLX 0.6.4, auto/disk mode with reuse enabled also enables verified
short exact-prefix caching for the worker, including the normal Text node
path. These backend-native caches never become named Werk state.
The live runtime.model_residency capability describes loaded-weight or
pipeline reuse only. Werk-owned in-process backends and resident Python workers
can report supported; remote vLLM reports externally_managed; MLX/MLX-VLM
and an opaque external ONNX runner remain one-shot and report no resident model
cache. The embedded ONNX GenAI CPU fallback has its own bounded model/tokenizer
LRU, but creates a new generator for every request. Restarting Werk makes
locally owned model and pipeline caches cold; durable job records do not
restore computation.
The runtime-node client sends Accept: application/json and
X-Werk-Protocol-Version: 1.0. It requires the versioned JSON envelope and
checks an HTTP protocol-version response header against it when present. A
missing response header remains accepted for compatibility with an earlier 1.0
server; malformed, newer or contradictory version declarations fail closed.
Werk does not implement ComfyUI’s native:
/prompt/history/viewContinue to run a real ComfyUI server for those facilities. ComfyUI remains responsible for workflow execution, previews, history and saved workflow media; Werk performs model discovery, inference routing and the requested model call.
For the hosted proxy contract and its authentication/error behavior, see the HTTP API reference. For model layout and media runtime requirements, see Media inference. For the runtime nodes’ server contract and backend limits, see Werk Protocol 1.0 and the runtime capability matrix.