Open WebUI

Open WebUI is a self-hosted, ChatGPT-style web interface. It has first-class support for OpenAI-compatible APIs, so adding the proxy is a single connection entry — the models it serves show up alongside any others you've configured.

Before you start

The proxy must be running and funded — see How-to guides.

Open WebUI almost always runs in Docker, and that changes two things — read the Docker networking note before you start. In short:

• Point Open WebUI at http://host.docker.internal:9376/v1, not localhost.
• Bind the proxy off loopback so the container can reach it — PROXY_SERVER_LISTEN=0.0.0.0:9376 zs-proxy proxy start (mind the exposure warning).

If you run Open WebUI natively (pip / uv) instead of Docker, use plain http://localhost:9376/v1 and skip the Docker parts.

Connect it

Open the connections settings

Click your avatar → Admin Panel → Settings → Connections. (For a single-user install you can also reach it under your own Settings → Connections.)

Add an OpenAI connection

Under OpenAI API, click + (Add Connection) and fill in:

• URL: http://host.docker.internal:9376/v1 (Docker) or http://localhost:9376/v1 (native).
• API Key: anything non-empty — the proxy ignores it.

Save. Open WebUI reads /v1/models and pulls in the live catalog.

(Optional) Filter the model list

The network can serve a lot of models. If you only want a few in your switcher, use the connection's Model IDs filter to allowlist specific ids (from curl http://localhost:9376/v1/models).

Start a chat

Open a new chat, pick a ZeroSignal model from the model selector at the top, and send a message. A reply confirms the setup works.

Troubleshooting

Symptom	Fix
Connection test fails / no models appear	The container can't reach the proxy. Use host.docker.internal and bind the proxy to 0.0.0.0:9376. On Linux add --add-host=host.docker.internal:host-gateway to the container.
curl http://localhost:9376/healthz works but Open WebUI still can't connect	You bound the proxy to loopback only. A container needs 0.0.0.0:9376 (or the docker-gateway IP).
Models list is huge	Use the connection's Model IDs filter to allowlist just the ones you use.
wallet_unfunded / payment errors	Add funds in the chat app, or with zs-proxy fund for a proxy-only wallet — see Wallet & funding.

What's next

• Configuration — server.listen, spend caps, and the output ceiling.
• Running as a service — keep the proxy up alongside your Docker stack.
• How-to guides — connect another app.