# comfy-api-proxy-go

> comfy-api-proxy is one static Go binary that serves the Comfy API v2 (/api/v2/*) in front of a self-hosted ComfyUI, so code written for Comfy Cloud runs against a local GPU unchanged. The repository also ships a Go SDK for the same API and for Comfy Router.

Install the proxy with `go install github.com/regiellis/comfy-api-proxy-go/cmd/comfy-api-proxy@latest` and the SDK with `go get github.com/regiellis/comfy-api-proxy-go/sdk`. Each link below is the Markdown source of one documentation page, in reading order.

## Docs

- [Introduction](https://comfy-proxy.regiellis.com/docs/introduction.md): comfy-api-proxy-go serves the Comfy API v2 in front of your own ComfyUI as one static Go binary, and ships a Go SDK for the same API, so code written for Comfy Cloud runs against a local GPU unchanged.
- [Install](https://comfy-proxy.regiellis.com/docs/install.md): Download a release binary, install with go install, or build from source. The binary is static and needs no libc, Python, or other runtime.
- [Quick start](https://comfy-proxy.regiellis.com/docs/quickstart.md): Run the proxy in front of ComfyUI, submit a workflow with curl, wait for it, and download the output. About five minutes with ComfyUI already running.
- [Command line](https://comfy-proxy.regiellis.com/docs/cli.md): Every comfy-api-proxy command and flag, the exit codes, and the flags kept compatible with the Python reference proxy.
- [Configuration](https://comfy-proxy.regiellis.com/docs/configuration.md): How the proxy resolves its settings from flags, environment variables, a TOML file, and defaults, with every key, its type and default, and the errors a bad value produces.
- [Remote access](https://comfy-proxy.regiellis.com/docs/remote-access.md): How to reach the proxy from another machine or a browser, what each bind and auth setting does, and the security defaults that hold when you change nothing.
- [State and background service](https://comfy-proxy.regiellis.com/docs/state-and-service.md): What --state-dir persists across restarts and how expired assets are cleaned up, and how start, stop, and status run and track the proxy in the background.
- [API reference](https://comfy-proxy.regiellis.com/docs/api.md): Every route the proxy serves under /api/v2, with request fields, response shapes, status codes, and error codes. Also covers the error envelope, Idempotency-Key, and the fixed bounds.
- [Event stream](https://comfy-proxy.regiellis.com/docs/events.md): The Server-Sent Events stream at /api/v2/jobs/{id}/events. Covers its event names and payloads, how it bridges ComfyUI's WebSocket, and why it always ends.
- [Assets](https://comfy-proxy.regiellis.com/docs/assets.md): Uploading inputs and model files, content-hash dedup, downloads with Range, signed output asset ids, and the guards on model placement under --comfyui-base-dir.
- [Go SDK](https://comfy-proxy.regiellis.com/docs/sdk.md): How to use the Go SDK against a local comfy-api-proxy, from creating a client through submitting workflows, waiting on jobs, downloading outputs, and handling errors. The same code runs against Comfy Cloud with a different base URL and key.
- [Comfy Cloud and Router](https://comfy-proxy.regiellis.com/docs/sdk-cloud.md): How to point the same Go SDK client at Comfy Cloud for workflows and at Comfy Router for hosted models, and what changes from the local proxy. Covers model runs, queued requests, schemas, retries, and which calls are billed.
- [Differences from the reference](https://comfy-proxy.regiellis.com/docs/differences.md): Every way this binary behaves differently from Comfy-Org's Python comfy-api-proxy, with the reason for each, and the parts that match it on purpose.
- [Benchmarks](https://comfy-proxy.regiellis.com/docs/benchmarks.md): Throughput, latency, startup time, and memory of this proxy against the Python reference on one machine, how they were measured, and how to measure your own.
- [Troubleshooting](https://comfy-proxy.regiellis.com/docs/troubleshooting.md): What the common startup failures and error codes mean, and what to change. Every API error carries a code; start with the one you got.

## Optional

- [All documentation in one file](https://comfy-proxy.regiellis.com/llms-full.txt): every page above, concatenated in reading order.
- [Go SDK reference](https://pkg.go.dev/github.com/regiellis/comfy-api-proxy-go/sdk): generated reference for every exported identifier.
- [Source code](https://github.com/regiellis/comfy-api-proxy-go): the proxy, the SDK, and this site.