Collector setup guide

What it does — and doesn't

Data that is sent

Per job, the collector sends only what cost tracking needs:

• prompt_id — ComfyUI job identifier (deduplication)
• Status transitions: queued, running, success, failed, interrupted
• Timestamps: queued / started / finished (UTC)
• workflow_hash — SHA-256 of the workflow structure, computed locally; the JSON itself is not uploaded
• Error type (exception class name only, truncated to 64 chars)
• GPU model name from ComfyUI system stats, when available
• Your optional project tag (exact match against your project names)

All timestamps are normalized to UTC. If a job cannot be fully reconstructed (ComfyUI restart, collector offline during execution), it is marked as partial data and cost figures for it are labeled as estimates.

1. Create an instance and a token

1. In ClipCost, open Instances and add your ComfyUI machine (e.g. "RTX 4090 render box").
2. Set its GPU hourly price, billing mode and GPU count on the same page.
3. Click Generate token. Copy the raw token immediately — it is shown only once and stored hashed on our side.

2. Install the collector on your GPU machine

Requires Python 3.10+. No dependencies beyond the standard library and httpx / websockets.

git clone https://github.com/clipcost-tracker/collector.git clipcost-collector
cd clipcost-collector
python3 -m venv .venv && source .venv/bin/activate
pip install httpx websockets

3. Configure environment variables

4a. Run with systemd (recommended)

# /etc/systemd/system/clipcost-collector.service
[Unit]
Description=ClipCost Collector for ComfyUI
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/clipcost-collector
EnvironmentFile=/etc/clipcost/collector.env
ExecStart=/opt/clipcost-collector/.venv/bin/python -m collector.main
Restart=always
RestartSec=5
User=comfyui

[Install]
WantedBy=multi-user.target

Put your variables in /etc/clipcost/collector.env (one per line, no quotes needed), then:

sudo systemctl daemon-reload
sudo systemctl enable --now clipcost-collector
journalctl -u clipcost-collector -f

4b. Or run with Docker

docker run -d --name clipcost-collector \
  --restart unless-stopped \
  --network host \
  -e CLIPCOST_COLLECTOR_URL=https://clipcost.example.com \
  -e CLIPCOST_TOKEN=cct_xxx \
  -e CLIPCOST_COMFYUI_URL=http://localhost:8188 \
  clipcost/collector:latest

With Docker, use --network host (or map port 8188) so the collector can reach ComfyUI on localhost.

5. Verify

1. Run any workflow in ComfyUI.
2. Within about a minute, the job should appear on your ClipCost Jobs page and the instance status turns green (online).

Troubleshooting

Instance shows "offline"

The collector's heartbeat (every 60 s) has not arrived. Check the process is running (systemctl status clipcost-collector), that CLIPCOST_COLLECTOR_URL is correct, and that outbound HTTPS (port 443) from the GPU machine is not blocked.

Collector online but no jobs appear

Check that CLIPCOST_COMFYUI_URL points at the right ComfyUI (default is localhost:8188). A wrong token produces an authentication error in the collector log, not silent success.

Duplicate jobs?

They are deduplicated by prompt_id. Replayed events update the existing record; they never create a second job.

ComfyUI or collector restarted mid-job

The collector re-syncs ComfyUI history on startup. Jobs that cannot be fully reconstructed are kept and marked as partial data, with costs labeled as estimates.

Network outage

Events are buffered in a local SQLite outbox on the GPU machine and uploaded automatically when connectivity returns. Nothing is lost for up to several days of offline time.