Agent-Skills.md

Agent Skills: ComfyUI Gateway

REST API gateway for ComfyUI servers. Workflow management, job queuing, webhooks, caching, auth, rate limiting, and image delivery (URL + base64).

UncategorizedID: sickn33/antigravity-awesome-skills/comfyui-gateway

Repository

sickn33/antigravity-awesome-skills
sickn33License: MIT
27,0474,580

Install this agent skill to your local

pnpm dlx add-skill https://github.com/sickn33/antigravity-awesome-skills/tree/HEAD/skills/comfyui-gateway

Skill Files

Browse the full folder contents for comfyui-gateway.

Download Skill

Loading file tree…

skills/comfyui-gateway/SKILL.md

Skill Metadata

Name
comfyui-gateway
Description
REST API gateway for ComfyUI servers. Workflow management, job queuing, webhooks, caching, auth, rate limiting, and image delivery (URL + base64).

ComfyUI Gateway

Overview

REST API gateway for ComfyUI servers. Workflow management, job queuing, webhooks, caching, auth, rate limiting, and image delivery (URL + base64).

When to Use This Skill

  • When the user mentions "comfyui" or related topics
  • When the user mentions "comfy ui" or related topics
  • When the user mentions "stable diffusion api gateway" or related topics
  • When the user mentions "gateway comfyui" or related topics
  • When the user mentions "api gateway imagens" or related topics
  • When the user mentions "queue imagens" or related topics

Do Not Use This Skill When

  • The task is unrelated to comfyui gateway
  • A simpler, more specific tool can handle the request
  • The user needs general-purpose assistance without domain expertise

How It Works

A production-grade REST API gateway that transforms any ComfyUI server into a universal, secure, and scalable service. Supports workflow templates with placeholders, job queuing with priorities, webhook callbacks, result caching, and multiple storage backends.

Architecture Overview

┌─────────────┐     ┌──────────────────────────────────┐     ┌──────────┐
│   Clients    │────▶│        ComfyUI Gateway           │────▶│ ComfyUI  │
│ (curl, n8n,  │     │                                  │     │ Server   │
│  Claude,     │     │  ┌─────────┐  ┌──────────────┐  │     │ (local/  │
│  Lovable,    │     │  │ Fastify │  │ BullMQ Queue │  │     │  remote) │
│  Supabase)   │     │  │ API     │──│ (or in-mem)  │  │     └──────────┘
│              │◀────│  └─────────┘  └──────────────┘  │
│              │     │  ┌─────────┐  ┌──────────────┐  │     ┌──────────┐
│              │     │  │ Auth +  │  │ Storage      │  │────▶│ S3/MinIO │
│              │     │  │ RateL.  │  │ (local/S3)   │  │     │(optional)│
│              │     │  └─────────┘  └──────────────┘  │     └──────────┘
└─────────────┘     └──────────────────────────────────┘

Components

| Component | Purpose | File(s) | |-----------|---------|---------| | API Gateway | REST endpoints, validation, CORS | src/api/ | | Worker | Processes jobs, talks to ComfyUI | src/worker/ | | ComfyUI Client | HTTP + WebSocket to ComfyUI | src/comfyui/ | | Workflow Manager | Template storage, placeholder rendering | src/workflows/ | | Storage Provider | Local disk + S3-compatible | src/storage/ | | Cache | Hash-based deduplication | src/cache/ | | Notifier | Webhook with HMAC signing | src/notifications/ | | Auth | API key + JWT + rate limiting | src/auth/ | | DB | SQLite (better-sqlite3) or Postgres | src/db/ | | CLI | Init, add-workflow, run, worker | src/cli/ |

Quick Start


## 1. Install

cd comfyui-gateway
npm install

## 2. Configure

cp .env.example .env

## 3. Initialize

npx tsx src/cli/index.ts init

## 4. Add A Workflow

npx tsx src/cli/index.ts add-workflow ./workflows/sdxl_realism_v1.json \
  --id sdxl_realism_v1 --schema ./workflows/sdxl_realism_v1.schema.json

## 5. Start (Api + Worker In One Process)

npm run dev

## Or Separately:

npm run start:api   # API only
npm run start:worker # Worker only

Environment Variables

All configuration is via .env — nothing is hardcoded:

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | API server port | | HOST | 0.0.0.0 | API bind address | | COMFYUI_URL | http://127.0.0.1:8188 | ComfyUI server URL | | COMFYUI_TIMEOUT_MS | 300000 | Max wait for ComfyUI (5min) | | API_KEYS | "" | Comma-separated API keys (key:role) | | JWT_SECRET | "" | JWT signing secret (empty = JWT disabled) | | REDIS_URL | "" | Redis URL (empty = in-memory queue) | | DATABASE_URL | ./data/gateway.db | SQLite path or Postgres URL | | STORAGE_PROVIDER | local | local or s3 | | STORAGE_LOCAL_PATH | ./data/outputs | Local output directory | | S3_ENDPOINT | "" | S3/MinIO endpoint | | S3_BUCKET | "" | S3 bucket name | | S3_ACCESS_KEY | "" | S3 access key | | S3_SECRET_KEY | "" | S3 secret key | | S3_REGION | us-east-1 | S3 region | | WEBHOOK_SECRET | "" | HMAC signing secret for webhooks | | WEBHOOK_ALLOWED_DOMAINS | * | Comma-separated allowed callback domains | | MAX_CONCURRENCY | 1 | Parallel jobs per GPU | | MAX_IMAGE_SIZE | 2048 | Maximum dimension (width or height) | | MAX_BATCH_SIZE | 4 | Maximum batch size | | CACHE_ENABLED | true | Enable result caching | | CACHE_TTL_SECONDS | 86400 | Cache TTL (24h) | | RATE_LIMIT_MAX | 100 | Requests per window | | RATE_LIMIT_WINDOW_MS | 60000 | Rate limit window (1min) | | LOG_LEVEL | info | Pino log level | | PRIVACY_MODE | false | Redact prompts from logs | | CORS_ORIGINS | * | Allowed CORS origins | | NODE_ENV | development | Environment |

Health & Capabilities

GET /health
→ { ok: true, version, comfyui: { reachable, url, models? }, uptime }

GET /capabilities
→ { workflows: [...], maxSize, maxBatch, formats, storageProvider }

Workflows (Crud)

GET    /workflows            → list all workflows
POST   /workflows            → register new workflow
GET    /workflows/:id        → workflow details + input schema
PUT    /workflows/:id        → update workflow
DELETE /workflows/:id        → remove workflow

Jobs

POST   /jobs                 → create job (returns jobId immediately)
GET    /jobs/:jobId          → status + progress + outputs
GET    /jobs/:jobId/logs     → sanitized execution logs
POST   /jobs/:jobId/cancel   → request cancellation
GET    /jobs                 → list jobs (filters: status, workflowId, after, before, limit)

Outputs

GET    /outputs/:jobId       → list output files + metadata
GET    /outputs/:jobId/:file → download/stream file

Job Lifecycle

queued → running → succeeded
                 → failed
                 → canceled
  1. Client POSTs to /jobs with workflowId + inputs
  2. Gateway validates, checks cache, checks idempotency
  3. If cache hit → returns existing outputs immediately (status: cache_hit)
  4. Otherwise → enqueues job, returns jobId + pollUrl
  5. Worker picks up job, renders workflow template, submits to ComfyUI
  6. Worker polls ComfyUI for progress (or listens via WebSocket)
  7. On completion → downloads outputs, stores them, updates DB
  8. If callbackUrl → sends signed webhook POST
  9. Client polls /jobs/:jobId or receives webhook

Workflow Templates

Workflows are ComfyUI JSON with {{placeholder}} tokens. The gateway resolves these at runtime using the job's inputs and params:

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": "{{seed}}",
      "steps": "{{steps}}",
      "cfg": "{{cfg}}",
      "sampler_name": "{{sampler}}",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "{{prompt}}",
      "clip": ["4", 1]
    }
  }
}

Each workflow has an inputSchema (Zod) that validates what the client sends.

Security Model

  • API Keys: X-API-Key header; keys configured via API_KEYS env var as key1:admin,key2:user
  • JWT: Optional; when JWT_SECRET is set, accepts Authorization: Bearer <token>
  • Roles: admin (full CRUD on workflows + jobs), user (create jobs, read own jobs)
  • Rate Limiting: Per key + per IP, configurable window and max
  • Webhook Security: HMAC-SHA256 signature in X-Signature header
  • Callback Allowlist: Only approved domains receive webhooks
  • Privacy Mode: When enabled, prompts are redacted from logs and DB
  • Idempotency: metadata.requestId prevents duplicate processing
  • CORS: Configurable allowed origins
  • Input Validation: Zod schemas on every endpoint; max size/batch enforced

Comfyui Integration

The gateway communicates with ComfyUI via its native HTTP API:

| ComfyUI Endpoint | Gateway Usage | |------------------|---------------| | POST /prompt | Submit rendered workflow | | GET /history/{id} | Poll job completion | | GET /view?filename=... | Download generated images | | GET /object_info | Discover available nodes/models | | WS /ws?clientId=... | Real-time progress (optional) |

The client auto-detects ComfyUI version and adapts:

  • Tries WebSocket first for progress, falls back to polling
  • Handles both /history response formats
  • Detects OOM errors and classifies them with recommendations

Cache Strategy

Cache key = SHA-256 of workflowId + sorted(inputs) + sorted(params) + checkpoint. On cache hit, the gateway returns a "virtual" job with pre-existing outputs — no GPU computation needed. Cache is stored alongside job data in the DB with configurable TTL.

Error Classification

| Error Code | Meaning | Retry? | |------------|---------|--------| | COMFYUI_UNREACHABLE | Cannot connect to ComfyUI | Yes (with backoff) | | COMFYUI_OOM | Out of memory on GPU | No (reduce dimensions) | | COMFYUI_TIMEOUT | Execution exceeded timeout | Maybe (increase timeout) | | COMFYUI_NODE_ERROR | Node execution failed | No (check workflow) | | VALIDATION_ERROR | Invalid inputs | No (fix request) | | WORKFLOW_NOT_FOUND | Unknown workflowId | No (register workflow) | | RATE_LIMITED | Too many requests | Yes (wait) | | AUTH_FAILED | Invalid/missing credentials | No (fix auth) | | CACHE_HIT | (Not an error) Served from cache | N/A |

Bundled Workflows

Three production-ready workflow templates are included:

1. Sdxl_Realism_V1 — Photorealistic Generation

  • Checkpoint: SDXL base
  • Optimized for: Portraits, landscapes, product shots
  • Default: 1024x1024, 30 steps, cfg 7.0

2. Sprite_Transparent_Bg — Game Sprites With Alpha

  • Checkpoint: SD 1.5 or SDXL
  • Optimized for: 2D game assets, transparent backgrounds
  • Default: 512x512, 25 steps, cfg 7.5

3. Icon_512 — App Icons With Optional Upscale

  • Checkpoint: SDXL base
  • Optimized for: Square icons, clean edges
  • Default: 512x512, 20 steps, cfg 6.0, optional 2x upscale

Observability

  • Structured Logs: Pino JSON logs with correlationId on every request
  • Metrics: Jobs queued/running/succeeded/failed, avg processing time, cache hit rate
  • Audit Log: Admin actions (workflow CRUD, key management) logged with timestamp + actor

Cli Reference

npx tsx src/cli/index.ts init                    # Create dirs, .env.example
npx tsx src/cli/index.ts add-workflow <file>      # Register workflow template
  --id <id> --name <name> --schema <schema.json>
npx tsx src/cli/index.ts list-workflows           # Show registered workflows
npx tsx src/cli/index.ts run                      # Start API server
npx tsx src/cli/index.ts worker                   # Start job worker
npx tsx src/cli/index.ts health                   # Check ComfyUI connectivity

Troubleshooting

Read references/troubleshooting.md for detailed guidance on:

  • ComfyUI not reachable (firewall, wrong port, Docker networking)
  • OOM errors (reduce resolution, batch, or steps)
  • Slow generation (GPU utilization, queue depth, model loading)
  • Webhook failures (DNS, SSL, timeout, domain allowlist)
  • Redis connection issues (fallback to in-memory)
  • Storage permission errors (local path, S3 credentials)

Integration Examples

Read references/integration.md for ready-to-use examples with:

  • curl commands for every endpoint
  • n8n webhook workflow
  • Supabase Edge Function caller
  • Claude Code / Claude.ai integration
  • Python requests client
  • JavaScript fetch client

File Structure

comfyui-gateway/
├── SKILL.md
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── api/
│   │   ├── server.ts          # Fastify setup + plugins
│   │   ├── routes/
│   │   │   ├── health.ts      # GET /health, /capabilities
│   │   │   ├── workflows.ts   # CRUD /workflows
│   │   │   ├── jobs.ts        # CRUD /jobs
│   │   │   └── outputs.ts     # GET /outputs
│   │   ├── middleware/
│   │   │   └── error-handler.ts
│   │   └── plugins/
│   │       ├── auth.ts        # API key + JWT
│   │       ├── rate-limit.ts
│   │       └── cors.ts
│   ├── worker/
│   │   └── processor.ts       # Job processor
│   ├── comfyui/
│   │   └── client.ts          # ComfyUI HTTP + WS client
│   ├── storage/
│   │   ├── index.ts           # Provider factory
│   │   ├── local.ts           # Local filesystem
│   │   └── s3.ts              # S3-compatible
│   ├── workflows/
│   │   └── manager.ts         # Template CRUD + rendering
│   ├── cache/
│   │   └── index.ts           # Hash-based cache
│   ├── notifications/
│   │   └── webhook.ts         # HMAC-signed callbacks
│   ├── auth/
│   │   └── index.ts           # Key/JWT validation + roles
│   ├── db/
│   │   ├── index.ts           # DB factory (SQLite/Postgres)
│   │   └── migrations.ts      # Schema creation
│   ├── cli/
│   │   └── index.ts           # CLI commands
│   ├── utils/
│   │   ├── config.ts          # Env loading + validation
│   │   ├── errors.ts          # Error classes
│   │   ├── logger.ts          # Pino setup
│   │   └── hash.ts            # SHA-256 hashing
│   └── index.ts               # Main entrypoint
├── config/
│   └── workflows/             # Bundled workflow templates
│       ├── sdxl_realism_v1.json
│       ├── sdxl_realism_v1.schema.json
│       ├── sprite_transparent_bg.json
│       ├── sprite_transparent_bg.schema.json
│       ├── icon_512.json
│       └── icon_512.schema.json
├── data/
│   ├── outputs/               # Generated images
│   ├── workflows/             # User-added wor

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `ai-studio-image` - Complementary skill for enhanced analysis
- `image-studio` - Complementary skill for enhanced analysis
- `stability-ai` - Complementary skill for enhanced analysis