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, andGET /view_metadata/{folder_name}./viewcan resolveblake3: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, andGET /history/{prompt_id}. - Job API:
GET /api/jobs,GET /api/jobs/{job_id},POST /api/jobs/{job_id}/cancel, andPOST /api/jobs/cancel. These read the samePromptQueuerunning/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,/apiduplication, 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/**:/internalfrontend-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.routesin server.py, verify whether it should also work under/api:PromptServer.add_routes()automatically clones onlyaiohttp.web.RouteDefentries and only before static catch-all registration. Routes registered directly onself.appafter 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 checkmain.py:prompt_worker()and openapi.yaml'sPromptRequest/PromptResponseschemas. 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_metadatabehavior changes, keepserver.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 carriesprompt_id; preview-with-metadata frames require special tuple handling insend_sync(). - If
/viewfile-serving rules change in server.py, verifyfolder_pathscontainment checks, asset hash resolution,X-Content-Type-Options,Vary: Sec-Fetch-Dest, andCache-Control: no-storebehavior 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/subscribechanges in api_server/…/internal_routes.py, also update api_server/…/terminal_service.py and the WebSocket client contract. Subscriptions are keyed by the/wsclient 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 /,/viewdangerous content handling, and static frontend/template routes). The middleware usessetdefault, 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. /viewin server.py is security-sensitive: if the dangerous content-type branch orSec-Fetch-Desthandling 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/viewpreview/content serving (fix(server): ... /view res previews,serve the original..., andmake /view responses revalidate with ETags), so review changes here with browser-cache and content-sniffing tests./system_statsin 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.