Spec-first ComfyUI deployment for Modal and Beam. The application logic is
three sealed cells (settings, argv, launcher) plus a composition root
(main). deploy/ contains the zero-inference image and platform envelopes.
dist/settingsparses the environment into an immutableSettings.dist/argvrenders--listen 0.0.0.0 --port 8188 --disable-mmap ....dist/launcherchdirs to ComfyUI and replaces the process.dist/mainis the only cell that readsos.environ.
--disable-mmap is mandatory: ComfyUI's default safetensors mmap is 30–50x
slower on FUSE and can deadlock under concurrent page faults.
gs://<bucket>/checkpoints/ clip/ clip_vision/ controlnet/
embeddings/ loras/ text_encoders/ unet/
upscale_models/ vae/
uv sync --frozen
uv run pyright contracts/ dist/
uv run pytest
find dist -type d -name __pycache__ -prune -exec rm -rf {} +
python3 scripts/regen_guard.py verify
python3 scripts/regen_guard.py stale
uv run python -m dist.main --dry-run --once
docker build -f deploy/Dockerfile -t comfyui-spec:local .
docker run --rm comfyui-spec:local --dry-run --onceexport PROJECT_ID=your-project
export GCS_BUCKET=my-comfy-models
export SA="comfyui-fuse@${PROJECT_ID}.iam.gserviceaccount.com"
gcloud iam service-accounts create comfyui-fuse --display-name="ComfyUI FUSE"
gcloud storage buckets add-iam-policy-binding "gs://${GCS_BUCKET}" \
--member="serviceAccount:${SA}" \
--role="roles/storage.objectViewer"
read -r ACCESS_ID SECRET <<< "$(gcloud storage hmac create "$SA" --format='value(accessId,secret)')"Create platform secrets:
modal secret create gcs-hmac \
GOOGLE_ACCESS_KEY_ID="$ACCESS_ID" \
GOOGLE_ACCESS_KEY_SECRET="$SECRET"
beam secret create GCS_ACCESS_KEY_ID "$ACCESS_ID"
beam secret create GCS_SECRET_ACCESS_KEY "$SECRET"Modal:
export GCS_BUCKET=my-comfy-models
modal deploy deploy/modal_app.pyBeam:
export GCS_BUCKET=my-comfy-models
beam volume create comfyui-outputs
beam deploy deploy/beam_app.py:comfyuiBoth print a public HTTPS URL.
curl -fsS "$URL/system_stats"
curl -fsS "$URL/queue"
curl -fsS "$URL/object_info/CheckpointLoaderSimple"The last call must list at least one checkpoint from GCS.
python3 scripts/regen_guard.py stale
python3 scripts/regen_guard.py prepare <cell>
# synthesize dist/<cell>/ from scratch/context_<cell>.md
uv run pytest tests/
python3 scripts/regen_guard.py seal <cell> [--adapter|--entrypoint]Never edit dist/ by hand. Never modify contracts/, specs/, or tests/
after prepare; seal will reject the tamper.
The deployed URL is public. Add Cloudflare Access, a basic-auth sidecar, or Modal proxy auth before exposing real data. ComfyUI has no built-in auth.