comfyui-mcp
Version:
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),
682 lines (559 loc) • 37 kB
Markdown
# comfyui-mcp RunPod image — FAST RESTART (image-immutable software)
A RunPod image that boots **ready to be driven by the
[comfyui-mcp](https://github.com/artokun/comfyui-mcp) Agent Panel**. Deploy on
RunPod, run **one local command** on your laptop, and the agent drives the pod's
live ComfyUI graph from your Claude/ChatGPT subscription.
It is optimized for **fast stop/start**. All the software — ComfyUI + its venv +
`comfyui_manager` v2 + the Agent Panel custom node — is **baked into the
(immutable) image** at `/opt/ComfyUI` and **run directly from there**. The
`/workspace` network volume holds **only your data** (`user/`, `models/`,
`input/`, `output/`). A warm restart does **no install, no sync, no seed** — it
just `mkdir -p` the data dirs and launches ComfyUI (~**30-60s** ComfyUI init).
> **Testing:** every build ends in an in-Dockerfile integrity gate, and
> [`test_image.sh`](#test-before-you-push-post-build-gate) runs a full boot
> suite (fresh volume → redeploy → corruption self-heal) before any push;
> `deploy-dockerhub.sh` makes that gate mandatory for the official image.
---
## TL;DR
1. **Build & push** the image (a machine with Docker; no GPU needed).
See [Build & push](#build--push).
2. **Deploy** on RunPod: GPU pod (e.g. RTX 5090), **expose HTTP 3000**, attach a
**network volume at `/workspace`**. See [Deploy on RunPod](#deploy-on-runpod).
3. On your laptop:
```bash
npx -y comfyui-mcp@latest connect https://<pod-id>-3000.proxy.runpod.net
```
4. Open the pod's ComfyUI, open the **Agent Panel** sidebar, enable the
external-orchestrator toggle, hit **Connect**, and drive the graph in natural
language.
The agent's brain (the **panel orchestrator**) runs **locally on your machine**
on your own subscription — see [Topology](#topology-where-the-agent-runs).
---
## The fast-restart model (what changed and why)
The previous design **seeded/synced** ComfyUI + its venv onto `/workspace` on the
first boot and re-synced on upgrades. That made the volume the source of truth for
software, which is slow to sync, fragile to upgrade (the `rsync -u` venv caveat),
and couples software to the data volume.
This design **inverts** that:
| Concern | Where it lives | Persists a restart? |
|---------|----------------|---------------------|
| ComfyUI install + venv | **image** `/opt/ComfyUI` (immutable) | n/a (re-pulled with the image) |
| `custom_nodes` (Agent Panel + your installs) | **volume** `/workspace/custom_nodes` (symlinked; image nodes seeded each boot) | **Yes** |
| ComfyUI-Manager | **image** venv (pip package) | n/a (in the image) |
| Custom-node pip cache | **volume** `/workspace/.cache/pip` | **Yes** |
| Other caches (HF / torch / npm) | **container** ephemeral disk | **No** — ephemeral |
| `user/` (workflows + settings + Manager config) | **volume** `/workspace/user` | **Yes** |
| `models/` (incl. Manager downloads) | **volume** `/workspace/models` | **Yes** |
| `input/` | **volume** `/workspace/input` | **Yes** |
| `output/` | **volume** `/workspace/output` | **Yes** |
**Result:** the base ComfyUI + venv boot fast from the immutable image; only your
data **and your custom nodes** live on the volume. A restart is `mkdir -p` the
user-data dirs, symlink + seed `custom_nodes`, reinstall node deps from the
persistent cache, and launch from the baked venv. No full install/sync/seed.
### Custom nodes persist on the volume
`custom_nodes` is **symlinked to `/workspace/custom_nodes`**, so **custom nodes the
agent or Manager install at runtime survive a restart** — while the base ComfyUI +
venv still boot fast from the immutable image.
* **How it works (each boot).** The entrypoint symlinks
`/opt/ComfyUI/custom_nodes` → `/workspace/custom_nodes`, seeds/refreshes the
image's baked nodes (Agent Panel + ComfyUI builtins) into it — so an image
upgrade always ships a current panel while **your** installed nodes are preserved
— then reinstalls each node's `requirements.txt` into the venv from a
**persistent pip cache** on the volume (fast after the first time).
* **Models DO persist** — Manager's install-model writes to `/workspace/models`
(see [Model paths](#model-paths-extra_model_pathsyaml)).
* **First install of a node** downloads its Python deps into the persistent cache;
every restart after re-materializes them from cache (the venv lives in the image,
so its packages are refreshed on boot). Compiled/CUDA-linked deps may rebuild
rather than unpack. To bake a node so it needs **zero** boot-time work, still add
it to the `Dockerfile` and rebuild.
### If the panel (or a node) shows up EMPTY — 0-byte files
A **full network volume** is the classic cause: on ENOSPC, `cp`/`git` still
*create* every file but write 0 bytes into them, so the node's whole file tree
exists as empty husks — ComfyUI lists the node, but nothing loads. Because the
volume persists, this used to survive every redeploy.
The entrypoint now defends itself:
* logs the volume's **free space** at boot and prints a loud warning under 500 MB;
* **skips the ~7 GB spotcheck-model copy** when the volume can't hold it;
* **verifies the Agent Panel** on the volume every boot and **self-heals** a
broken copy (re-clone from GitHub, or restore from the image seed offline);
* names any other custom node whose `__init__.py` is 0 bytes in the boot log
(`WARN: custom nodes with 0-byte __init__.py …`) — reinstall those via Manager.
If you see the ENOSPC warning: free or grow the volume, restart the pod, and the
panel repairs itself on the next boot.
---
## Architecture (multi-stage)
```
ARG BASE_IMAGE = runpod/pytorch:1.0.7-cu1281-torch280-ubuntu2404 (lean, recent)
ARG RUNPOD_SRC_IMAGE = aitrepreneur/comfyui:2.3.5 (donor only)
┌─ STAGE A: runpod-donor ── ARG-gated (INCLUDE_RUNPOD_EXTRAS) ─────────┐
│ FROM aitrepreneur/comfyui:2.3.5 │
│ (built only so runpod-extras-1 can COPY service artifacts out of it;│
│ INCLUDE_RUNPOD_EXTRAS=0 -> runpod-extras-0 (empty), and BuildKit │
│ never builds/pulls this stage at all) │
└─────────────────────────────────────────────────────────────────────┘
┌─ spotcheck-0 / spotcheck-1 (alpine) ─ ARG-gated SDXL model carrier ──┐
│ spotcheck-1 = ADD sd_xl_base_1.0.safetensors ; spotcheck-0 = empty │
└─────────────────────────────────────────────────────────────────────┘
┌─ FINAL: FROM ${BASE_IMAGE} ─────────────────────────────────────────┐
│ apt: git cron nodejs … ; install code-server │
│ git clone ComfyUI (master) -> /opt/ComfyUI (BAKED, run from here) │
│ python -m venv /opt/ComfyUI/venv │
│ pip cu128 torch/vision/audio (NO xformers) │
│ pip -r requirements.txt ; pip comfyui_manager==4.2.2 │
│ rm classic custom_nodes/ComfyUI-Manager │
│ git clone comfyui-mcp-panel -> /opt/ComfyUI/custom_nodes/… │
│ COPY extra_model_paths.yaml -> /opt/ComfyUI/extra_model_paths.yaml │
│ COPY config.ini -> /opt/ComfyUI/config.ini.seed (Manager gate) │
│ COPY --from=spotcheck-src -> /opt/ComfyUI-seed-models │
│ COPY --from=runpod-extras /extras/ / (uploader, croc, app-manager)│
│ COPY nginx.conf (:3000->:3001), starting.html, post_start.sh │
│ (no ENTRYPOINT/CMD override — keep the base's /start.sh chain) │
└─────────────────────────────────────────────────────────────────────┘
```
### Boot sequence (what runs, in order)
The base image's `CMD` is **`/start.sh`** (from `runpod/containers`). On boot it:
1. `service nginx start` — reads our `/etc/nginx/nginx.conf` (**:3000 → :3001**,
websocket-aware, with the "starting" fallback page).
2. runs `/pre_start.sh` if present (we ship none).
3. `setup_ssh` — injects RunPod's `$PUBLIC_KEY` and starts sshd.
4. `start_jupyter` — starts JupyterLab on **:8888** if `$JUPYTER_PASSWORD` is set.
5. runs **our `/post_start.sh`** — `mkdir` the volume data dirs, assert the
Manager gate, start the ancillary services, and **launch ComfyUI from the
baked venv**.
6. `sleep infinity` — keeps the pod alive.
So SSH + Jupyter + nginx come from the base; **our hook adds everything else**.
---
## ComfyUI launch command (the exact flags)
`/post_start.sh` launches (from `cd /opt/ComfyUI`, with the baked venv python):
```bash
/opt/ComfyUI/venv/bin/python main.py \
--listen 0.0.0.0 --port 3001 \
--enable-manager \
--use-pytorch-cross-attention \
--user-directory /workspace/user \
--input-directory /workspace/input \
--output-directory /workspace/output \
--extra-model-paths-config /opt/ComfyUI/extra_model_paths.yaml
```
* **`--user-directory /workspace/user`** — workflows, ComfyUI settings, AND the
Manager config (see [Manager gate](#manager-remote-install-gate)) live on the
volume.
* **`--input-directory` / `--output-directory`** — inputs and generated images on
the volume.
* **`--extra-model-paths-config`** — points every model category at
`/workspace/models` (see below). MODELS persist on the volume.
* **We deliberately do NOT use `--base-directory`.** It would relocate
`custom_nodes` (and temp) onto the volume too — but we want `custom_nodes` to
stay **in the image**. The per-dir flags + `extra_model_paths.yaml` give us
exactly the split we want (data on the volume, software in the image).
> **Flag verification.** These flag names were verified against ComfyUI `master`
> (`comfy/cli_args.py`): `--user-directory`, `--input-directory`,
> `--output-directory`, `--base-directory`, and `--extra-model-paths-config` all
> exist with these exact spellings, and `--base-directory`'s own help text states
> it sets the base for "models, custom_nodes, input, output, temp, and user
> directories" — confirming why we avoid it. **Assumption to confirm at build:**
> the *pinned* `COMFYUI_REF` you bake actually ships these flags (they are present
> on recent `master`; an old pin may not have them). Run
> `"/opt/ComfyUI/venv/bin/python" /opt/ComfyUI/main.py --help` in the built image
> to confirm before publishing.
---
## Model paths (`extra_model_paths.yaml`)
`extra_model_paths.yaml` is baked at `/opt/ComfyUI/extra_model_paths.yaml` and
loaded via `--extra-model-paths-config`. It maps **every** model category to a
subfolder under `/workspace/models`, with `is_default: true` so the volume is the
**primary** (download) location — i.e. Manager's install-model writes there and
the files persist.
```yaml
comfyui_mcp_volume:
base_path: /workspace
is_default: true # insert these paths at the FRONT → default target
checkpoints: models/checkpoints/
configs: models/configs/
loras: models/loras/
vae: models/vae/
text_encoders: | # ComfyUI key "text_encoders" (a.k.a. CLIP)
models/text_encoders/
models/clip/
diffusion_models: | # a.k.a. UNet
models/diffusion_models/
models/unet/
clip_vision: models/clip_vision/
style_models: models/style_models/
embeddings: models/embeddings/
diffusers: models/diffusers/
vae_approx: models/vae_approx/
controlnet: |
models/controlnet/
models/t2i_adapter/
gligen: models/gligen/
upscale_models: models/upscale_models/
latent_upscale_models: models/latent_upscale_models/
hypernetworks: models/hypernetworks/
photomaker: models/photomaker/
classifiers: models/classifiers/
model_patches: models/model_patches/
audio_encoders: models/audio_encoders/
background_removal: models/background_removal/
frame_interpolation: models/frame_interpolation/
geometry_estimation: models/geometry_estimation/
optical_flow: models/optical_flow/
detection: models/detection/
```
Notes:
* **`is_default: true`** is the load-bearing line. ComfyUI's
`add_model_folder_path(..., is_default=True)` **inserts** the path at the front
of each category's list, so `/workspace/models/<cat>` becomes the default
download target. Without it, the image's `/opt/ComfyUI/models/<cat>` (ephemeral)
would stay first and Manager downloads would **not** persist.
* **No `custom_nodes:` key** — on purpose. Mapping `custom_nodes` to the volume
would break the fast-restart contract.
* `base_path: /workspace` with `models/...` relative subpaths mirrors ComfyUI's
own `extra_model_paths.yaml.example` convention.
* The category **keys** match ComfyUI's `folder_names_and_paths` keys (verified
against `master`'s `folder_paths.py`). The category list mirrors the example's
full set; harmless if a future ComfyUI renames one.
* `/post_start.sh` pre-creates the matching subfolders under `/workspace/models`
so they exist on a cold volume.
### Warm model volume (skip the cold HF pull)
A **fresh** network volume has an empty `models/` tree — the first time the
agent (or you) needs a checkpoint, it's a cold download from HuggingFace, which
can be tens of GB and the slowest part of getting a new pod usable.
The fix is the same idea as the image itself: **build once, reuse many times.**
1. **Build a seed volume once.** Spin up a pod with this image + a network
volume, download the checkpoints/LoRAs/VAEs you use most (the exact same
files the [installer packs](../../packs) already fetch — `packs/*/install-runpod.sh`
lists the HF URLs per pack) into that volume's `models/<category>/` tree
matching the layout in `extra_model_paths.yaml` above, then stop the pod.
That volume is now your **warm seed** — keep it around, don't delete it.
2. **Reuse it for new pods**, by whichever mechanism your RunPod plan supports:
- **Volume snapshot/clone** (if available on your account) — instantly fork
a new volume from the seed's current contents instead of attaching the
same volume serially.
- **Attach the seed volume directly** to a new pod deployment (stop any pod
currently using it first) — simplest, but one pod at a time.
- **A shared object store + boot-time sync** — the most portable option, and
the only one that supports many pods pulling concurrently: keep the seed
models in an S3-compatible bucket (RunPod's own network storage, or any
S3-compatible provider) and add an `rclone sync` (or `aws s3 sync`) step to
`post_start.sh` before the model-subfolder `mkdir -p` block, pulling only
what's missing on that pod's volume. This also composes cleanly with
`PANEL_AUTO_UPDATE` above — both are "pull what's missing/changed at boot,
skip what's already there" patterns.
None of this requires a new mechanism in the image itself — `extra_model_paths.yaml`
already treats `/workspace/models` as the single source of truth regardless of
*how* files got there, so a warm volume (or a boot-time sync into one) is
transparent to ComfyUI and the agent.
---
## Manager (remote-install gate)
* **Manager v2 (pip), gated by `--enable-manager`.** `comfyui_manager==4.2.2`
exposes `/v2/manager/queue/task` (the API comfyui-mcp talks to). The classic
`custom_nodes/ComfyUI-Manager` checkout **conflicts** with it and is removed.
* **Where the config lives.** With `--user-directory /workspace/user`,
`comfyui_manager` reads its `config.ini` from **under the user dir** — verified
against the Manager source (`manager_migration.get_manager_path(user_dir)`):
* new ComfyUI (System User API): `…/user/__manager/config.ini`
* older ComfyUI: `…/user/default/ComfyUI-Manager/config.ini`
Because that's on the **volume**, the gate persists. `/post_start.sh` writes/re-
asserts **both** locations on every boot (idempotent), so it's correct on either
Manager build.
* **Gate values** (`config.ini`):
| Key | Value | Why |
|-----|-------|-----|
| `network_mode` | `personal_cloud` | required — the `/v2` install gate only allows remote installs in this mode |
| `security_level` | `normal-` | safe default; set `weak` (env `COMFY_SECURITY_LEVEL=weak`) for no guardrails, trusted pods only |
---
## ComfyUI / torch specifics
* **cu128 torch, no xformers.** The venv gets a clean `torch torchvision
torchaudio` from `https://download.pytorch.org/whl/cu128` (sm_120 kernels for
Blackwell / RTX 5090). xformers is **omitted** — its prebuilt wheels lag the
cu128 ABI — so ComfyUI launches with `--use-pytorch-cross-attention` (PyTorch
SDPA).
* **Caches are ephemeral (in the container), by design.** We do **not** redirect
HF/pip/torch/npm caches to `/workspace`. Model downloads via Manager go to
`/workspace/models` and persist — that's the only persistence we need. (First
use after a restart may re-download small ancillary files into the ephemeral
cache; the big model weights stay on the volume.)
---
## Services (replicating the aitrepreneur set)
| Service | Port | Source | Notes |
|---------|------|--------|-------|
| **nginx** | **3000** (→ ComfyUI 3001) | our `nginx.conf` | websocket-aware; "starting" fallback page |
| **ComfyUI** | 3001 (internal) | baked image venv | launched from `/opt/ComfyUI`; see [launch flags](#comfyui-launch-command-the-exact-flags) |
| **sshd** | 22 | base | RunPod `$PUBLIC_KEY` injection |
| **JupyterLab** | 8888 | base | set `JUPYTER_PASSWORD` |
| **code-server** | 8081 (→ 8080) | installed at build | best-effort |
| **app-manager** | 8001 (→ 8000) | COPY from donor | Node app; best-effort (needs `node`) |
| **runpod-uploader** | — | COPY from donor | file uploader; best-effort |
| **croc** | — | COPY from donor | on-demand P2P transfer |
| **cron** | — | apt | best-effort |
| **dead-man watchdog** | 8189 (heartbeat) | `deadman_server.py` + `deadman_watch.sh` | see below |
All ancillary services are launched **best-effort** — if a binary is absent (e.g.
you dropped the donor COPYs) the entrypoint logs `skip` and carries on, so the
image still boots ComfyUI fine.
### Dead-man switch (#269)
Pods **created via `runpod_pod_create`** carry a billing dead-man switch. The
in-process idle auto-stop dies with the orchestrator (crash / closed laptop);
without a pod-side guard the pod would bill forever. So:
- `deadman_server.py` (:8189, token-gated) receives the orchestrator's
heartbeats (one per watch poll) and refreshes a beat file;
- `deadman_watch.sh` stops the pod **itself** (GraphQL `podStop` — stop, never
terminate, so `/workspace` survives) when the beats stop: 20 min without a
beat once managed, or 45 min after boot with no heartbeat at all
(`DEADMAN_BEAT_GRACE_S` / `DEADMAN_BOOT_GRACE_S`).
The stop is authorized by the **pod-scoped `RUNPOD_API_KEY` RunPod auto-injects
into every pod** — the owner's account-wide key never leaves the orchestrator.
Arming is signaled by the pod env carrying `DEADMAN_TOKEN` (injected by
`runpod_pod_create`; a sha256 of key + unique deploy name, authorizes
heartbeats **only** — it is not an API key and cannot stop the pod).
Console-deployed pods have no token, so their watchdog stays inert. Opt out of
arming with `deadman:false` / `RUNPOD_DEADMAN=0` at create, or
`DEADMAN_DISABLE=1` as a pod env.
---
## Topology: where the agent runs
```
YOUR LAPTOP RUNPOD POD (this image)
┌───────────────────────────┐ ┌───────────────────────────────────┐
│ npx comfyui-mcp connect … │ HTTP/WS ───▶ │ nginx :3000 ─▶ ComfyUI :3001 │
│ └─ panel orchestrator │ │ ├─ Manager v2 (--enable-manager) │
│ (Claude/Codex Agent SDK│ ◀─── events │ └─ Agent Panel (sidebar) │
│ on YOUR subscription) │ │ + sshd / jupyter / code-server │
└───────────────────────────┘ └───────────────────────────────────┘
```
The **panel orchestrator** (the autonomous agent loop, on your Claude **or**
ChatGPT subscription — no API key) runs **on your machine**, not the pod. The pod
only serves ComfyUI + Manager + the panel UI. That's why **Node.js for the agent,
the Agent SDK and any LLM client are intentionally absent** — they'd burn pod
GPU-hours for nothing.
---
## Deploy on RunPod
Create a **Pod template** (or fill these on a one-off GPU pod):
| Template field | Value |
|----------------|-------|
| **Container image** | `<your-registry>/comfyui-mcp-runpod:<tag>` (after build & push) |
| **Container disk** | ≥ 30 GB (the baked ComfyUI + venv + cu128 torch + any runtime-installed nodes/caches, which are ephemeral) |
| **Volume disk** | e.g. 100 GB+ (your **models + workflows + I/O** live here; size for your models) |
| **Volume mount path** | **`/workspace`** |
| **Expose HTTP ports** | **`3000`** (nginx → ComfyUI). Optionally `8081` (code-server), `8001` (app-manager), `8888` (Jupyter). |
| **Expose TCP ports** | `22` (SSH) |
| **GPU** | RTX 5090 / any Blackwell or Ada card (cu128 covers both) |
| **Host driver** | >= 570 (CUDA 12.8) for the default image; >= 580 (CUDA 13) for the `:cu130` perf variant. The entrypoint preflights this (`MIN_DRIVER`) and holds the pod open with a clear message instead of crash-looping. |
**Environment variables** (Pod → Environment):
| Env | Default | Purpose |
|-----|---------|---------|
| `JUPYTER_PASSWORD` | *(unset)* | set to enable JupyterLab on :8888 (base behavior) |
| `PUBLIC_KEY` | *(RunPod injects)* | SSH public key (base behavior) |
| `COMFY_SECURITY_LEVEL` | `weak` | Manager security level — `weak` lets the agent install nodes from git URLs (single-user pod); set `normal-` to restore Manager's guardrails |
| `COMFY_NETWORK_MODE` | `personal_cloud` | must stay `personal_cloud` for remote installs |
| `COMFY_AUTOUPDATE_MANAGER` | `1` | fast-forward `comfyui_manager` (pip) at boot: `1` = latest stable release, `nightly` = ComfyUI-Manager git main, `0` = keep the baked pin. The venv is ephemeral, so this is the only Manager fix that survives a restart short of a new image. Best-effort (180s cap), never blocks boot. |
| `COMFY_EXTRA_ARGS` | *(empty)* | extra ComfyUI flags appended verbatim by the entrypoint |
| `COMFY_HOME` | `/opt/ComfyUI` | baked ComfyUI path (rarely overridden) |
| `WORKSPACE` | `/workspace` | network-volume mount (rarely overridden) |
| `PANEL_AUTO_UPDATE` | `1` | fast-forward the Agent Panel to its latest release on every boot (git fetch + reset --hard, before ComfyUI launches) — reaches pods without a new image build. Automatically a no-op on a `PANEL_REF`-pinned build (detached HEAD). Set `0` to disable. |
| `HF_TOKEN` (or `HUGGINGFACE_TOKEN`) | *(unset)* | HuggingFace token for gated model downloads (exported to ComfyUI + Manager) |
| `ARIA2_DISABLE` | `0` | set `1` to skip the aria2 download sidecar (Manager then uses its slow built-in downloader) |
| `ARIA2_RPC_PORT` | `6800` | loopback port for the aria2 RPC daemon |
| `ARIA2_RPC_SECRET` | *(random per boot)* | RPC secret for the aria2 daemon (auto-generated; set only if you need a fixed one) |
| `HF_HUB_ENABLE_HF_TRANSFER` | `1` (set at boot) | Rust parallel downloader for `huggingface_hub` fetches. **Set `0` as the FIRST troubleshooting step if an HF download fails** — hf_transfer trades resume robustness/proxy support for speed |
| `HF_XET_HIGH_PERFORMANCE` | `1` (set at boot) | high-performance mode for Xet-backed HF repos (newer hub versions) |
### Fast model downloads (aria2 sidecar)
ComfyUI-Manager's built-in model downloader is single-stream with tiny chunks
and collapses to **<1–4 MB/s** against the MooseFS network volume — a 13 GB
model then takes hours, and because Manager's install queue is serial,
everything behind it looks wedged ("downloads don't work"). Measured on a live
pod (2026-07-07): Manager at 792 kB/s while `curl` on the same pod pulled the
same HuggingFace file at 15–80 MB/s and wrote the volume at 60–300 MB/s.
The image therefore bakes **aria2** and runs a loopback, secret-gated RPC
daemon at boot (post_start §4.4), hardened per review:
- **Supervised**: aria2c runs under a respawn loop — a crashed daemon would
otherwise leave Manager hard-failing with *no* fallback (Manager commits to
the aria2 path at import time).
- **Readiness-probed**: `COMFYUI_MANAGER_ARIA2_SERVER`/`SECRET` are exported
only after a real `aria2.getVersion` RPC answers (daemonizing successfully
says nothing about the listener). On probe failure the sidecar is torn down
and Manager keeps its built-in downloader.
- **`/models` → `/workspace/models` symlink**: Manager's aria2 path joins
*relative* model dirs onto `/models` — without the link an edge case would
write models onto the ephemeral container fs and lose them on restart.
- The RPC secret lives in a `0600` conf file (not the process cmdline) and is
length-checked; the live server+secret are written to
`/var/lib/comfyui-mcp/aria2-rpc.env` (root-only) so `test_image.sh` and a
debugging human can make a real RPC call.
Note Manager's aria2 path (like its built-in one) does not attach `HF_TOKEN`
to download requests — gated-model fetches need a token-authenticated URL
either way.
aria2 only covers Manager's install-model route. The **other** fetch path —
custom nodes (Impact, WAS, …) and ComfyUI internals downloading via
`huggingface_hub` — is accelerated separately: the image bakes `hf_transfer`
(HF's Rust parallel downloader) + `hf_xet`, and boot defaults
`HF_HUB_ENABLE_HF_TRANSFER=1` + `HF_XET_HIGH_PERFORMANCE=1` **only after
verifying `hf_transfer` imports** (with the flag set and the package missing,
`huggingface_hub` raises at download time — the integrity gate asserts the
import for the same reason). Both are plain pod env opt-outs (`=0`); flip
`HF_HUB_ENABLE_HF_TRANSFER=0` first when debugging a failing HF download.
> **First boot vs warm restart:** both are fast. First boot additionally creates
> the volume data dirs and copies the spotcheck model (if baked); warm restart
> skips even those. Watch the pod log / the "starting" page; ComfyUI init is
> ~30-60s either way.
---
## Build & push
No GPU is needed at **build** time. On a machine with Docker + BuildKit:
```bash
cd docker/runpod
# Default: baked software + spotcheck model.
docker build -t <your-registry>/comfyui-mcp-runpod:cu128 .
docker push <your-registry>/comfyui-mcp-runpod:cu128
# Omit the baked spotcheck model (the 6.9 GB layer is never downloaded):
docker build --build-arg BAKE_SPOTCHECK_MODEL=0 \
-t <your-registry>/comfyui-mcp-runpod:cu128-noseed .
```
### Test before you push (post-build gate)
The build itself ends in an **integrity gate** (Dockerfile §9.5) that fails on
missing/0-byte panel files, a broken venv, or a `post_start.sh` syntax error.
Before any registry push, run the deeper suite:
```bash
# static checks + a real 2-boot volume test + the ENOSPC self-heal test:
./test_image.sh <image-ref>
# static checks only (~seconds):
./test_image.sh <image-ref> --static
```
For the official Docker Hub image, release **npm-publish style** — one command
that versions, builds, gates, publishes, verifies, and pins the template:
```bash
npm run runpod:release # minor bump: 1.6 -> 1.7
npm run runpod:release:major # major bump: 1.6 -> 2.0
npm run runpod:release -- 2.3 # explicit tag
```
The script (`scripts/runpod-release.mjs`): resolves the next version from
Docker Hub → builds the fat image (extras donor = the previous release, so no
63 GB pull; panel layer cache-busted to the panel repo's main SHA) → runs the
full `test_image.sh` suite via `deploy-dockerhub.sh` (**a failure aborts before
anything is pushed**) → pushes `:<version>` + `:latest` → `verify_image_remote.py`
checks what the registry actually serves → pins the RunPod template to the new
version tag via the GraphQL API (`RUNPOD_API_KEY`; `SKIP_TEMPLATE=1` to skip).
The two lower-level pieces also work standalone:
```bash
docker build -t artokun/comfyui-mcp-runpod:build .
./deploy-dockerhub.sh 1.7 # gate + push :1.7 + :latest + remote verify
```
CI does the same for `ghcr.io/...:cu128-lean` (`verify_image_remote.py`
inspects the pushed manifest + seed layer without pulling the 20 GB image).
> **Pin the RunPod template to the VERSION tag** (`:1.6`), not `:latest`.
> RunPod hosts cache images per-tag — a template on `:latest` can silently
> serve a stale build from a host's cache; a fresh version tag can't. The
> release script does this for you. (Don't use `runpodctl template update`
> for it — it trips a "public templates cannot have Registry Credentials"
> API error on public templates; the script's GraphQL path doesn't.)
Override pins as needed:
```bash
docker build \
--build-arg BASE_IMAGE=runpod/pytorch:1.0.7-cu1281-torch280-ubuntu2404 \
--build-arg COMFYUI_REF=master \
--build-arg COMFYUI_MANAGER_VERSION=4.2.2 \
--build-arg PANEL_REF=<tag-or-branch> \
-t <your-registry>/comfyui-mcp-runpod:cu128 .
```
### The 63 GB donor pull (and how to drop it)
`STAGE A` (`runpod-donor`) pulls `aitrepreneur/comfyui:2.3.5` (~63 GB) **at build
time** purely to copy out `runpod-uploader`, `croc` and `/app-manager`. It does
**not** ship in the final image, but it is a heavy one-time pull on your build
host — and won't fit on a disk-constrained CI runner. If you don't need those
extras:
```bash
docker build --build-arg INCLUDE_RUNPOD_EXTRAS=0 \
-t <your-registry>/comfyui-mcp-runpod:cu128-lean .
```
BuildKit only builds a stage the final target's dependency graph actually
reaches, so `INCLUDE_RUNPOD_EXTRAS=0` skips the donor pull **entirely** — not
just its `COPY` (see `runpod-extras-0`/`runpod-extras-1` in the Dockerfile,
which mirror the `BAKE_SPOTCHECK_MODEL` selector pattern below). The entrypoint
already treats `runpod-uploader`/`croc`/`app-manager` as best-effort and skips
them cleanly when absent; `croc` can instead be installed from its official
release if you want it back without the donor pull.
### Image size note (the duplicate-torch tradeoff)
Because the software is now baked, the image is **larger** than the volume-seed
design — that's the deliberate fast-restart tradeoff (first-pull/image-size no
longer matters per the spec). The lean base `runpod/pytorch:…-cu1281-torch280-…`
**already ships a cu128 torch**, yet we install cu128 torch again into the
isolated venv (~7 GB duplicated) for a guaranteed-correct, isolated environment.
To shave that:
* Build the venv with `python -m venv --system-site-packages /opt/ComfyUI/venv`
and **skip the `pip install torch …` step**, so ComfyUI reuses the base's
cu128 torch. **Verify first** that the base torch is genuinely `+cu128`
(`python -c "import torch;print(torch.__version__, torch.version.cuda)"`) —
some older `cu1281` tags shipped a cu-default torch.
> **First build on a new base tag?** Watch for: (a) the base's
> `/start.sh` actually invokes `/post_start.sh` (it does in `runpod/containers`,
> but confirm for your exact tag); (b) `main.py --help` lists `--user-directory`,
> `--input-directory`, `--output-directory`, `--extra-model-paths-config`,
> `--enable-manager`, `--use-pytorch-cross-attention` for your pinned
> `COMFYUI_REF`; (c) `comfyui_manager 4.2.2` reads the gate from the volume user
> dir (`user/__manager/config.ini` or `user/default/ComfyUI-Manager/config.ini`);
> (d) Manager install-model writes to `/workspace/models/<cat>` (i.e. `is_default`
> took effect); (e) the donor paths `/usr/local/bin/runpod-uploader`,
> `/usr/local/bin/croc`, `/app-manager` exist. Then deploy and verify a real
> stop/start is fast.
---
## The one-command local connect
Once the pod is up and you have its proxy URL, on your laptop:
```bash
npx -y comfyui-mcp@latest connect https://<pod-id>-3000.proxy.runpod.net
```
This starts the comfyui-mcp panel orchestrator pointed at the pod. Because the pod
page is served over `https://`, `connect` automatically opens a secure, token-gated
**`wss://` tunnel** (via Cloudflare) to the agent bridge on your machine and hands
the pod's panel that URL — so the HTTPS page reaches your local agent with **no
browser prompt, in any browser** (a secure page can't open a plain `ws://` socket
to your box). Then open the pod's ComfyUI, open the **Agent Panel**, enable the
**external-orchestrator** toggle, and click **Connect**. (Add **`--insecure-bridge`**
to force the plain `ws://127.0.0.1:9180` loopback instead — e.g. when you reach the
pod via an SSH port-forward.)
If you're on a build that predates the `connect` subcommand, the equivalents are:
```bash
# remote ComfyUI as an MCP server (for Claude Code / Desktop):
npx -y comfyui-mcp --comfyui-url https://<pod-id>-3000.proxy.runpod.net
# panel orchestrator (drives the sidebar agent):
COMFYUI_URL=https://<pod-id>-3000.proxy.runpod.net npx -y comfyui-mcp --panel-orchestrator
```
If the pod sits behind auth, set `COMFYUI_AUTH_TOKEN` (+ `COMFYUI_AUTH_HEADER` /
`COMFYUI_AUTH_SCHEME`) on the local command.
---
## Owner confirmations needed
Draft pins/assumptions — confirm before building/publishing:
1. **Base tag** — `runpod/pytorch:1.0.7-cu1281-torch280-ubuntu2404` (verified on
Docker Hub 2026-06-19). Confirm it's still the one you want at build.
2. **Base `/start.sh` hook** — confirm your exact base tag's `/start.sh` runs
`/post_start.sh` and `service nginx start` reads `/etc/nginx/nginx.conf`
(true in `runpod/containers` `main`).
3. **Launch flags on the pinned ComfyUI** — `--user-directory`,
`--input-directory`, `--output-directory`, `--extra-model-paths-config`,
`--enable-manager`, `--use-pytorch-cross-attention`. Verified present on
`master`; confirm for whatever `COMFYUI_REF` you bake (`main.py --help`).
4. **`is_default` write behavior** — confirm Manager install-model actually lands
in `/workspace/models/<cat>` (it should, since `is_default` front-inserts the
volume paths).
5. **`comfyui_manager` 4.2.2 config path** — reads
`user/__manager/config.ini` (new) or `user/default/ComfyUI-Manager/config.ini`
(older) under `--user-directory`. We write both; confirm one is honored.
6. **Donor artifact paths** — `/usr/local/bin/runpod-uploader`,
`/usr/local/bin/croc`, `/app-manager` in `aitrepreneur/comfyui:2.3.5`.
7. **nginx port convention** — kept **3000 → 3001** (matches your `connect`
flow). We override the base's native ComfyUI proxy block with our
self-contained `nginx.conf`.
8. **Duplicate torch** — keep the isolated cu128 torch (default, ~+7 GB) or reuse
the base's via `--system-site-packages` (see size note).
9. **Panel ref** — cloned from the default branch (nightly HEAD). Pin `PANEL_REF`
for reproducible images?
10. **custom_nodes tradeoff** — confirm you accept that runtime-installed nodes
don't survive a restart (models do). Permanent nodes go in the Dockerfile.
---
## Files
| File | Purpose |
|------|---------|
| `Dockerfile` | Multi-stage: lean `runpod/pytorch` final stage; `aitrepreneur` donor stage for service artifacts; ARG-gated SDXL spotcheck stage. **Bakes** ComfyUI + cu128 venv + Manager v2 + Agent Panel into `/opt/ComfyUI` (run from there; never synced to the volume). |
| `post_start.sh` | Boot hook (installed as `/post_start.sh`): `mkdir` the `/workspace` data dirs, first-boot spotcheck-model copy, Manager-gate write, ancillary services, and ComfyUI launch from the baked venv with the per-dir flags. |
| `extra_model_paths.yaml` | Maps every model category to `/workspace/models/<cat>` with `is_default: true` (volume is the primary/download location). No `custom_nodes:` key (nodes stay in the image). |
| `nginx.conf` | Self-contained reverse proxy (`:3000 → :3001`, websocket-aware, "starting" fallback) + code-server / app-manager fronts. Installed over the base's. |
| `starting.html` | The auto-refreshing "ComfyUI is starting…" page nginx serves until upstreams are up. |
| `config.ini` | Manager v2 gate template (`network_mode = personal_cloud`, `security_level = normal-`), copied to the volume user dir at boot. |
| `README.md` | This document. |