Configuration

Layering

Every setting is resolved from four layers. The first layer that sets a key wins:

1. A command-line flag you passed.
2. A COMFY_PROXY_* environment variable.
3. The config file.
4. The built-in default.

A flag left at its default does not count as set, so comfy-api-proxy run with no flags still honors the environment and the file. The proxy records which layer each final value came from, prints it in comfy-api-proxy config, and names it in every error.

Environment variables

A key's variable is COMFY_PROXY_ plus the key in upper case: port is COMFY_PROXY_PORT, comfyui_base_dir is COMFY_PROXY_COMFYUI_BASE_DIR.

• An empty or whitespace-only variable counts as unset. COMFY_PROXY_PORT= in a service file falls through to the config file instead of failing as a bad integer.
• Integers must parse as integers. Booleans take true, false, 1, 0, t, f, and the TRUE, True, T style variants of each.
• COMFY_PROXY_CORS_ORIGINS is a comma-separated list. Spaces around each origin are trimmed, and empty entries are dropped.

COMFY_PROXY_CONFIG names the config file. It is not a key.

COMFY_PROXY_HOST=global COMFY_PROXY_TOKEN="$TOKEN" comfy-api-proxy
COMFY_PROXY_CORS_ORIGINS="https://a.example.com, https://b.example.com" comfy-api-proxy

Config file

The file is TOML. The proxy reads the first of:

1. --config <path>
2. COMFY_PROXY_CONFIG
3. The default location: $XDG_CONFIG_HOME/comfy-api-proxy/config.toml, which is ~/.config/comfy-api-proxy/config.toml when XDG_CONFIG_HOME is unset. On macOS the default is ~/Library/Application Support/comfy-api-proxy/config.toml.

Only the default location may be missing. A file named by --config or COMFY_PROXY_CONFIG must exist and be readable, or the proxy exits 2.

An unknown key is an error, so a typo fails loudly instead of leaving a setting at its default. That matters most for host and token, where a silent fallback would change who can reach the proxy.

A complete file, with every key at its default and the optional ones commented out:

comfyui = "http://127.0.0.1:8188"
host = "local"
port = 8189

# token = "change-me"
# comfyui_token = "secret"
# allow_insecure_bind = false
# comfyui_base_dir = "/path/to/ComfyUI"
# max_upload_mb = 100
# state_dir = "/path/to/state"
# cors_origins = ["https://app.example.com"]
# quiet = false

config.example.toml in the repository carries the same keys with a comment on each.

Keys

comfyui

Base URL of the ComfyUI the proxy fronts. It must use http or https and include a host. A trailing slash is removed.

Requests to ComfyUI never go through an HTTP_PROXY or HTTPS_PROXY from the environment, because they can carry the partner API key.

host

The bind scope:

An empty host is an error rather than a wildcard bind. Any address that is not loopback needs token or allow_insecure_bind. See remote access.

port

The port to serve on, 1 to 65535. It is fixed: if it is taken the proxy exits 1 and does not try another, because clients are configured with this one.

token

When set, every /api/v2/* request except GET /api/v2/health must carry Authorization: Bearer <token>. Required for a non-loopback host unless allow_insecure_bind is set. See remote access.

comfyui_token

A bearer token the proxy sends to ComfyUI on every request, for a ComfyUI behind an authenticating gateway. It is never sent to clients. It is independent of token.

allow_insecure_bind

Permits a non-loopback bind with no token. Anyone who can reach the port can then submit work to your ComfyUI.

comfyui_base_dir

The root of a ComfyUI install on the same machine as the proxy. Setting it turns on model-file uploads into models/<category>/ and POST /api/v2/assets/from-path. Without it, model-file uploads are rejected and input uploads still work. A relative path is resolved against the working directory, and symlinks in it are resolved at startup. See assets.

max_upload_mb

The largest single upload, in MB. Must be at least 1.

state_dir

Turns on SQLite persistence of job records, idempotency keys, the asset index, and the signing secret for output asset ids. Unset means all of that lives in memory and is lost on restart. See state and service.

This is not the directory where start keeps its PID record and log. That one is separate; see state and service.

cors_origins

Browser origins allowed to call the proxy. Each entry must be an absolute http or https URL with a host and nothing after it: no path other than /, no query, no fragment, no user info. * is refused. Entries are normalized to the form a browser sends in its Origin header, with the default port dropped, so https://app.example.com:443/ becomes https://app.example.com. The scheme and host are lowercased, as browsers send them, so https://App.Example.com matches too. See remote access.

public_url

The origin clients reach the proxy at, such as https://comfy.example.com. Every URL the proxy puts in a response (a job's urls, each output's url, an asset's url) starts with it. Unset, links follow the scheme and Host of each request, which is right when clients connect to the proxy directly. Behind a reverse proxy that terminates TLS, requests arrive as plain http, so set this or clients get http:// links, treat them as another origin, and drop the bearer token. It must be an absolute http or https URL with a host and no query, fragment, or user info. A path is kept, for a reverse proxy that serves the proxy under a prefix and strips it. The scheme and host are lowercased and a trailing / is dropped. See remote access.

quiet

Turns off the per-request access log.

Errors

A configuration error exits 2 and names the layer the bad value came from, so you know which flag, variable, or file to fix. The source reads flag --port, env COMFY_PROXY_PORT, config /path/to/config.toml, or default.

An unknown key points at its line:

error: config file /home/you/.config/comfy-api-proxy/config.toml has unknown keys:
1| hots = "global"
 | ~~~~ unknown field

A taken port is a runtime error, exit 1, and also names where the port came from. See remote access.

Inspecting the result

comfy-api-proxy config resolves everything exactly as run would, prints each value with its source, and exits. It accepts the same flags, so you can test a command line before you use it.

comfy-api-proxy config --port 9001

file: /home/you/.config/comfy-api-proxy/config.toml (loaded)
comfyui: http://127.0.0.1:8188 (default)
host: local → 127.0.0.1 (config /home/you/.config/comfy-api-proxy/config.toml)
port: 9001 (flag --port)
token: unset (default)
comfyui token: unset (default)
insecure: false (default)
base dir: none (default)
upload: 100 MB (default)
state: none (default)
cors: none (default)
quiet: false (default)

The file line says whether the file was loaded or not found, using defaults, and adds named explicitly when it came from --config or COMFY_PROXY_CONFIG. host shows the setting and the address it resolves to. Tokens print as set (N characters) or unset, never their value.

A configuration that would fail at startup fails here too, with the same message and exit code 2.