Remote access

The short version

The proxy listens on 127.0.0.1:8189 by default, so only the machine it runs on can reach it. To reach it from elsewhere, bind every interface and set a token:

# ~/.config/comfy-api-proxy/config.toml
host = "global"
token = "pick-a-long-random-string"

comfy-api-proxy start
comfy-api-proxy status

The startup panel, or the log for start, lists the LAN and VPN addresses to use. Clients send Authorization: Bearer <token> on every /api/v2/* call except GET /api/v2/health.

The token travels in plain HTTP. The proxy does not terminate TLS, so across a network you do not trust, put it behind a VPN or a TLS reverse proxy.

Behind a reverse proxy

A reverse proxy such as Caddy, nginx, or Traefik can terminate TLS in front of the proxy. The request then reaches the proxy as plain http, and without more configuration every link in a response (a job's urls, each output's url) would read http://. Clients treat that as a different origin and drop the bearer token. Tell the proxy its public origin:

host = "local"                              # the reverse proxy on this machine connects to 127.0.0.1
public_url = "https://comfy.example.com"
token = "pick-a-long-random-string"

The proxy never reads X-Forwarded-Proto or X-Forwarded-Host, because any client could send them and point the links somewhere else. You state the origin once in configuration instead. A path in public_url is kept, for a reverse proxy that serves the API under a prefix and strips it before passing the request on.

Host

host picks the address the listener binds:

The listener uses tcp4 for an IPv4 address and tcp6 for an IPv6 one. 0.0.0.0 stays IPv4 only and never becomes a dual-stack socket that also listens on IPv6 addresses the startup output did not print. To serve IPv6, bind an IPv6 address.

localhost is mapped to 127.0.0.1 without a DNS lookup.

Token required off loopback

Any host that is not a loopback address needs a token. Without one the proxy refuses to start and exits 2:

error: refusing to bind non-loopback host "global" (from flag --host) without a token.
Set a token (--token, COMFY_PROXY_TOKEN, or token in the config file), or set allow_insecure_bind to expose the proxy unauthenticated.

allow_insecure_bind = true (or --allow-insecure-bind) lifts the check. Then anyone who can reach the port can submit workflows to your ComfyUI, read its outputs, and, with comfyui_base_dir set, place model files on disk. Use it only on a network where every host is yours.

Bearer auth

With token set, every request under /api/v2/ must carry:

Authorization: Bearer <token>

• The scheme name Bearer is matched without regard to case. The token is compared in constant time.
• A missing or malformed header is a 401 with code unauthorized and the message Missing or malformed Authorization header. A wrong token is a 401 with Invalid token.
• GET /api/v2/health stays open, so a supervisor or comfy-api-proxy status can probe the proxy without the secret.
• OPTIONS requests pass, because a browser's CORS preflight never carries Authorization.

curl -H "Authorization: Bearer $TOKEN" http://192.168.1.20:8189/api/v2/jobs

{"error": {"code": "unauthorized", "message": "Invalid token.", "details": null}}

A token is also useful on loopback: it stops other local users and local software from driving the proxy.

Startup URLs

When the bind is a specific address, the startup panel lists that one URL. When it is a wildcard (global or ::), it lists loopback first and then the address of every interface that is up, in the bound address family:

  url: http://127.0.0.1:8189
  url: http://192.168.1.20:8189
  url: http://100.64.0.7:8189

The list leaves out:

• Container and VM bridge interfaces whose names start with docker, br-, veth, virbr, cni, flannel, vmnet, vboxnet, lxcbr, lxdbr, or podman. They are reachable only from this machine's own guests, and on a Docker host there can be dozens of them burying the LAN and VPN addresses.
• IPv6 link-local addresses, which do not work in a URL without a zone.

The proxy still listens on those interfaces when bound to a wildcard. They are only omitted from the printout.

Port 8189

The port defaults to 8189 and stays where you put it. SDK clients are configured with a fixed base URL, and a proxy that moved to the next free port would break them without saying so.

When the port is taken, run exits 1 and says where the value came from and how to change it:

error: port already in use: 127.0.0.1:8189 (port from default).
Another process is holding it. Stop that process, or change the port with --port, COMFY_PROXY_PORT, or port in the config file.
The proxy does not pick another port because clients are configured with this one.

start checks before it launches anything and exits 1 with comfy-api-proxy cannot start: http://127.0.0.1:8189 is already in use.

Browser access and CORS

Browsers are blocked from calling the proxy cross-site unless you allowlist their origin. To let a hosted web app call a proxy on your machine:

comfy-api-proxy --enable-cors-header https://app.example.com --token "$TOKEN"

cors_origins = ["https://app.example.com", "http://localhost:3000"]

For a request whose Origin is on the list, the proxy:

• answers a preflight OPTIONS with 204;
• sets Access-Control-Allow-Origin to that origin (never *), with Vary: Origin and Access-Control-Allow-Credentials: true;
• allows the methods GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS and the headers Authorization, Content-Type, and Idempotency-Key;
• exposes Retry-After, Content-Range, and Accept-Ranges to the page;
• lets the browser cache the preflight for 600 seconds.

The CORS headers go on before auth runs, so a 401 or 403 is still readable by an allowlisted page. Event streams get the same headers.

Origins are matched exactly against the normalized list, so the scheme, host, and port must all match what the browser sends. * is refused at startup, since an authenticated proxy must never answer every origin. See configuration for the accepted forms.

Origin guard

With no configuration at all, the proxy rejects cross-site browser requests. This is ComfyUI core's origin-only middleware, ported through the reference. It stops a page you have open in a browser from scripting requests at a server on your machine (drive-by CSRF and DNS rebinding).

For a request whose Origin is not allowlisted:

1. Sec-Fetch-Site: cross-site is rejected. Browsers set that header and page script cannot forge it.
2. When Host names a loopback address and an Origin is present, the two hosts must match. Ports are compared only when both carry one. A Host that is a name counts as loopback when every address it resolves to is loopback.

Both rejections are a 403 with code forbidden_origin:

{"error": {"code": "forbidden_origin", "message": "Origin 'http://evil.example' does not match request host '127.0.0.1:8189'.", "details": null}}

What passes:

• Requests with no Origin, such as curl and the SDKs. Browsers always send one on the cross-site requests the guard exists to stop.
• Same-origin requests, where the Origin host matches Host.
• Requests to a non-loopback Host. A reverse proxy may rewrite Host, so the check is left to the token and the network in that case.

The guard applies to every path, routed or not. It follows the reference's string comparison exactly, including its quirks, each of which fails closed. For example, an IPv6 origin without a port, http://[::1], does not match a Host of [::1]:8189.

Upstream auth with comfyui_token

If ComfyUI sits behind a gateway that requires a bearer token, set comfyui_token:

comfyui = "https://comfy.internal.example.com"
comfyui_token = "gateway-token"

The proxy sends Authorization: Bearer <comfyui_token> on every request to ComfyUI, including the WebSocket handshake behind the event stream. It never forwards the token to clients and never prints it. It is unrelated to token, which is what clients present to the proxy.

Security defaults

Each of these holds without any configuration: