# ComfyUI Serverless — Admin Package

This package contains everything to **configure, deploy, and manage** a ComfyUI serverless endpoint on fal.ai.

## What's included

- `admin-ui/` — local web UI (http://localhost:9999) to manage models, nodes, deps, deploy, and run ComfyUI
- `comfy_server/` — the fal.App config (models, custom nodes, Python deps)
- `proxy/`, `frontend/` — bundled ComfyUI proxy + built frontend (used by the **Run ComfyUI** button)
- `wheel/` — custom patched serverless-comfy wheel
- `docs/` — full documentation

---

## Quick start

### macOS

1. Unzip. Drag the folder anywhere.
2. Double-click **`admin-ui.command`**

> **First-time Gatekeeper warning**: macOS may block `.command` files from "unidentified developers".
> **Workaround**: right-click → **Open** (not double-click) → **Open** in the dialog.
> Alternatively: `chmod +x admin-ui.command` in Terminal.

> **First-time firewall prompt**: macOS will ask to allow Python to accept incoming connections.
> Click **Allow** (the proxy only binds `localhost`, nothing is exposed to the network).

### Windows

1. Unzip. Place the folder anywhere (avoid paths with special characters).
2. Double-click **`admin-ui.bat`**

> Requires **Python 3.11** from https://www.python.org/downloads/ —
> during install, **check "Add Python to PATH"**.

### First run

On the first launch the script installs Python deps into a local `.venv/` (1–3 min, one-time).
Then a browser opens on http://localhost:9999.

1. Open the **Settings** tab
2. Paste your **FAL API key** (https://fal.ai/dashboard/keys — enable the **Admin** scope, and **switch to the right team BEFORE creating the key**: the team is encoded in the key).
3. Save, then click **Deploy** in the top bar to push your config to fal.ai.

---

## Using the admin UI

- **Models tab** — add/remove model weights (filename + download URL)
- **Custom Nodes tab** — add GitHub repos + commit SHA; imports `requirements.txt` automatically
- **Python Deps tab** — edit the `requirements.txt` your fal app uses
- **Settings tab** — manage API key + app name
- **ComfyUI** chip (top bar) — pin a specific ComfyUI version (git SHA)
- **Runners** chip — live view of running fal GPU runners + logs (click the icon to stream)
- **Outputs** chip — all rendered images/videos from your ComfyUI session, with download
- **Deploy button** — publishes current config to fal.ai
- **Run ComfyUI button** — starts a local proxy and opens the ComfyUI interface

### Heads up

- Deploys reuse a cached Docker environment when `requirements.txt` hasn't changed (fast). First deploy with new deps takes longer.
- The first time a fal **runner** starts for your app, it cold-boots for **5–10 minutes** (downloads all models + custom nodes). Follow-up requests are fast as long as `min_concurrency ≥ 1`.
- One runner handles one request at a time (`max_multiplexing=1`). If multiple users need concurrency, raise `max_concurrency` via `fal apps scale <app> --max-concurrency N`.

---

## CLI power-user path

Instead of the UI you can still use the command-line scripts:

- `./deploy.sh` (mac/linux) or `deploy.bat` / `deploy.ps1` (windows) — interactive deploy

---

## Docs

- **[Add a Model](docs/ADD_MODELS.md)**
- **[Add a Custom Node](docs/ADD_CUSTOM_NODES.md)**
- **[Deploy](docs/DEPLOY.md)**
- **[Troubleshooting](docs/TROUBLESHOOTING.md)**
- **[Claude Code rules](claude-rules.md)** — rules for using Claude Code safely

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| macOS `"cannot be opened because the developer cannot be verified"` | Right-click `admin-ui.command` → **Open** → **Open** |
| Windows `python is not recognized` | Reinstall Python 3.11 with "Add Python to PATH" checked |
| Deploy fails with `No module named 'fal'` | Delete `.venv/` and re-run the launcher |
| "Address already in use" on port 9999 or 8188 | Close the old terminal window; the launcher also auto-kills stale instances |
| Too many fal runners spawning | Set `max_concurrency=1` in Settings or via `fal apps scale <app> --max-concurrency 1` |
| "Reconnecté" toasts spam in ComfyUI | Cosmetic — the WebSocket keeps renegotiating. Your workflow still runs correctly. |
