Introducing a new way to review your PRs.

Read the announcement

comfy-org / comfyui

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / server-startup-and-http-api

Server Startup and HTTP API

Overview

main.py is the ComfyUI process entrypoint. It enables CLI parsing, configures logging, sets early environment variables for telemetry/GPU behavior, initializes governance and model paths, runs custom-node prestartup_script.py files, and only then imports torch-adjacent modules such as execution, server, nodes, and comfy.model_management. start_comfyui() is the main orchestration function: it prepares temp/model/user paths, creates the AssetManager, creates an asyncio loop, constructs server.PromptServer, initializes custom/API nodes, starts the asset database/scanner, registers routes with PromptServer.add_routes(), installs progress hooks, and starts the daemon prompt_worker() thread that drains execution.PromptQueue.

prompt_worker() in main.py is the bridge between HTTP submissions and execution. /prompt in server.py validates a workflow, assigns or validates a UUID prompt ID, extracts bounded workflow_metadata, removes sensitive extra_data keys into a separate tuple slot, and enqueues (number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive). The worker merges the sensitive fields back only for execution, runs execution.PromptExecutor, stores history through PromptQueue.task_done(), emits queue/progress WebSocket events through PromptServer.send_sync(), and services /free flags by unloading models and clearing caches.

server.py owns the aiohttp server. PromptServer.__init__() creates shared managers (UserManager, ModelFileManager, CustomNodeManager, SubgraphManager, NodeReplaceManager), an InternalRoutes sub-router, the PromptQueue, the asyncio.Queue used for outbound socket messages, and the aiohttp web.Application. start_multi_address() binds one web.TCPSite per configured listen address, optionally with TLS from CLI cert/key arguments. publish_loop() is the single async consumer of cross-thread messages queued by send_sync().

The WebSocket endpoint is GET /ws in server.py. A client either supplies clientId to resume a socket ID or receives a generated UUID. On connect the server sends status with queue info and the socket ID. The first text frame may be {"type":"feature_flags","data":...}; if so, server.py stores the client's feature flags in sockets_metadata and responds with server feature flags from comfy_api.feature_flags. Outbound JSON frames are {type, data}. Binary frames are prefixed by a big-endian 4-byte event ID from protocol.py: preview image (1), raw/legacy preview (2), progress text (3), or preview image with JSON metadata (4). main.py:hijack_progress() sends progress JSON for every progress update and only sends legacy unencoded preview frames when the connected client did not advertise supports_preview_metadata.

HTTP middleware is assembled in PromptServer.__init__() in server.py. middleware/cache_middleware.py always runs first and adds no-store for JS/CSS frontend entrypoints, one-day cache headers for successful image assets, one-hour cache headers for missing images, and no-cache for temporary redirects. server.py then adds a deprecation logger for legacy frontend import paths, optional gzip compression for JSON/text, either explicit CORS headers (--enable-cors-header) or the default loopback origin guard, optional offline Content-Security-Policy, and optional ComfyUI Manager middleware.

Core routes are registered on self.routes inside PromptServer.__init__() and then finalized by PromptServer.add_routes(). add_routes() first lets the optional agent host mount /api/agent and /api/workflows, then asks the user/model/custom-node/subgraph/node-replacement managers to add their routes, mounts api_server/…/internal_routes.py at /internal, duplicates every non-static self.routes route under /api, adds the original unprefixed routes, then adds deploy-to-cloud routes only under /api. Static extension routes, template routes, embedded /docs, and the frontend static catch-all / are registered last so API routes win before static serving.

The route groups implemented directly in server.py are:

  • Frontend/bootstrap: GET /, /extensions, /features, /default_workflow, /system_stats, /models, /models/{folder}, /embeddings, /object_info, and /object_info/{node_class}.
  • File viewing/upload: POST /upload/image, POST /upload/mask, GET /view, and GET /view_metadata/{folder_name}. /view can resolve blake3: asset hashes through the asset system, enforces directory containment for filename/subfolder requests, can render preview/channel variants with Pillow, and forces dangerous renderable content types to attachment unless the request is safely image-rendered.
  • Queue/history/execution: GET/POST /prompt, GET/POST /queue, POST /interrupt, POST /free, GET/POST /history, and GET /history/{prompt_id}.
  • Job API: GET /api/jobs, GET /api/jobs/{job_id}, POST /api/jobs/{job_id}/cancel, and POST /api/jobs/cancel. These read the same PromptQueue running/queued/history state as the legacy queue/history endpoints and strip sensitive tuple slot data before serializing.

api_server/…/internal_routes.py owns the /internal/* sub-application. It exposes frontend-only routes for log text (GET /internal/logs), structured logs plus terminal size (GET /internal/logs/raw), live log subscription (PATCH /internal/logs/subscribe), configured folder paths (GET /internal/folder_paths), and recent visible files in input, output, or temp (GET /internal/files/{directory_type}). api_server/…/terminal_service.py backs log streaming by subscribing to app.logger.on_flush() and sending logs WebSocket messages only to currently connected client IDs. api_server/…/README.md explicitly marks /internal as unstable and ComfyUI-frontend-only.

openapi.yaml is the broad public contract document for ComfyUI APIs. It documents the core /api routes implemented in server.py, the /internal frontend routes from api_server/…/internal_routes.py, and additional /api surfaces mounted by manager/asset/cloud modules outside this doc's covered implementation. Treat it as the cross-module contract surface rather than proof that a route is implemented in server.py.

comfyui_version.py contains the generated __version__ string. main.py logs it at startup, and server.py reports it in /system_stats.

Routing / covers index

  • main.py: process startup, environment setup, custom-node prestartup, server creation, database/assets startup, prompt worker, progress hook, event loop run/shutdown.
  • server.py: PromptServer, middleware assembly, /ws, core HTTP routes, /api duplication, static frontend/template/docs routing, WebSocket encoding/publication, aiohttp bind/TLS.
  • protocol.py: binary WebSocket event IDs shared by server.py and main.py progress emission.
  • middleware/cache_middleware.py: cache headers for frontend assets and image/static responses.
  • api_server/routes/internal/**: /internal frontend-only routes and their README contract.
  • api_server/…/terminal_service.py: live terminal/log stream fanout over WebSocket.
  • api_server/…/file_operations.py: filesystem walk/type helpers available to API code; not wired directly by the covered internal routes.
  • openapi.yaml: API contract/spec for core, internal, and manager/asset/cloud-mounted routes.
  • comfyui_version.py: generated runtime version used by startup logs and /system_stats.

Coupling

  • If a route is added to self.routes in server.py, verify whether it should also work under /api: PromptServer.add_routes() automatically clones only aiohttp.web.RouteDef entries and only before static catch-all registration. Routes registered directly on self.app after the clone, such as deploy-to-cloud routes in server.py, are intentionally /api-only.
  • If a WebSocket binary event is added or renumbered in protocol.py, update every sender in server.py and main.py:hijack_progress() and the frontend decoder together. server.py:encode_bytes() sends only a 4-byte event prefix; clients must already know each event's payload format.
  • If prompt submission payloads change in server.py:post_prompt(), also check main.py:prompt_worker() and openapi.yaml's PromptRequest/PromptResponse schemas. The queue tuple shape is positional and includes a sensitive-data slot that server.py strips from queue/job responses and main.py reattaches only for execution.
  • If workflow_metadata behavior changes, keep server.py:valid_workflow_metadata(), workflow_metadata_from_prompt(), PromptServer.send_sync(), and openapi.yaml aligned. Metadata is bounded before enqueue and merged into outgoing messages only when a message carries prompt_id; preview-with-metadata frames require special tuple handling in send_sync().
  • If /view file-serving rules change in server.py, verify folder_paths containment checks, asset hash resolution, X-Content-Type-Options, Vary: Sec-Fetch-Dest, and Cache-Control: no-store behavior together. The route is both a local filesystem reader and an asset-hash reader, so path traversal and stored-XSS protections are load-bearing.
  • If /internal/logs/subscribe changes in api_server/…/internal_routes.py, also update api_server/…/terminal_service.py and the WebSocket client contract. Subscriptions are keyed by the /ws client ID, and disconnected clients are pruned only when log messages flush.
  • If cache policy changes in middleware/cache_middleware.py, check server.py responses that already set cache headers explicitly (GET /, /view dangerous content handling, and static frontend/template routes). The middleware uses setdefault, so route-level headers intentionally override it.
  • If the API contract in openapi.yaml is changed for endpoints implemented by managers imported in server.py (UserManager, ModelFileManager, CustomNodeManager, SubgraphManager, assets, deploy-to-cloud), verify those modules as well; many documented paths are not implemented inside this doc's covered files.

Risks

  • server.py and openapi.yaml disagree on POST /api/jobs/cancel: the covered implementation returns {"cancelled": <bool>} and treats unknown/finished IDs as idempotent no-ops, while openapi.yaml documents an array of cancelled IDs plus fail-fast 404 semantics. Clients generated from the spec can break against the local handler if this drift is not reconciled.
  • /view in server.py is security-sensitive: if the dangerous content-type branch or Sec-Fetch-Dest handling is loosened, stored HTML/SVG/JS/CSS outputs can execute in the ComfyUI origin instead of downloading. Recent covered-file history shows repeated fix churn around /view preview/content serving (fix(server): ... /view res previews, serve the original..., and make /view responses revalidate with ETags), so review changes here with browser-cache and content-sniffing tests.
  • /system_stats in server.py reads torch device memory and version data on an HTTP request path. Covered-file history includes a revert/fix sequence around not querying device memory while a prompt runs, so changes to this endpoint can reintroduce deadlocks or stalls during active execution.