Open WebUI: connect to Zukko via Docker and the admin panel

Open WebUI is a web interface for language models that you run yourself in Docker. It can talk to any OpenAI-compatible API, so connecting Open WebUI to Zukko comes down to two values: the address https://api.zukko.pro/v1 and a fetch_... key. Below are the launch command, the admin panel setup, how to pick a model by price, and fixes for common errors.

What you need

• Docker on your machine or server.
• A Zukko key that looks like fetch_.... The full key is shown only once, when you create it, so save it right away.
• Optionally, limits on the key. In the dashboard every key can have a daily and monthly dollar limit and a list of allowed models. For a chat shared by several people, that's a simple guard against surprise spending.

How to connect Open WebUI to Zukko with Docker

The command follows the official Open WebUI instructions, with two variables added for Zukko:

docker run -d \
  -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="your_secret" \
  -e OPENAI_API_BASE_URL="https://api.zukko.pro/v1" \
  -e OPENAI_API_KEY="fetch_your_key" \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

What matters here:

• -p 3000:8080 — the UI will be at http://localhost:3000. If port 3000 is taken, change the left number.
• -v open-webui:/app/backend/data — chats, users and settings live in this volume. Without it, everything disappears when the container is recreated.
• WEBUI_SECRET_KEY — the key that signs sessions. The Open WebUI docs recommend a fixed value, otherwise everyone gets logged out when the container is recreated. Generate one with openssl rand -hex 32.
• OPENAI_API_BASE_URL and OPENAI_API_KEY — the Zukko address (with /v1, always) and your key.
• :main — the tag used in the official docs. For production you can pin a specific vX.Y.Z version.

On first launch Open WebUI asks you to create an admin account. The first account becomes the administrator, and sign-up then switches itself off; you can allow other people to register in the admin settings.

Connecting through the admin panel

If the container is already running without these variables, or you want to add Zukko as a second provider, do it in the UI:

1. Open Admin Panel → Settings → Connections (the docs write this path as Settings > Admin > Connections).
2. In the OpenAI API block, click "+" (Add Connection).
3. Set the URL to https://api.zukko.pro/v1 and the API Key to your fetch_... key.
4. You can leave Model IDs empty: Open WebUI will request the model list from /models, and Zukko serves it at GET /v1/models. If you only want users to see some of the models, list the IDs you need.
5. Save. Each connection has a toggle, so you can switch it off temporarily without deleting it.

Environment variables only apply on first launch

In Open WebUI, OPENAI_API_BASE_URL and OPENAI_API_KEY are persistent settings: on first start their values are written to the database inside the volume, and from then on the app reads them from there. If you change the key in docker run and recreate the container with the old volume, nothing changes. The right way is to update the key in Admin Panel → Settings → Connections. A temporary alternative is ENABLE_PERSISTENT_CONFIG=False: Open WebUI then reads values from the environment, but changes made in the UI are not saved.

Table: what goes where

Which model to choose: do the math

All models are served from the same address. Claude models also work through the OpenAI-compatible connection, because the gateway converts the format.

Example: a chat message where history plus question take 3,000 tokens and the answer takes 1,000. That's 4,000 tokens in total:

• claude-sonnet-5, claude-opus-5-5, gpt-5.6-sol: 4,000 × $0.3 / 1,000,000 = $0.0012;
• gpt-5.6-luna, glm-5.3: 4,000 × $0.1 / 1,000,000 = $0.0004;
• glm-5.3-flash: 4,000 × $0.04 / 1,000,000 = $0.00016.

Keep in mind that in a long conversation every new message resends the whole history, so input tokens grow with each turn.

Nobody can tell you in advance which model will handle your particular tasks best, so test it. Open WebUI can show two models' answers side by side: take 10–20 typical requests, run them on two or three models, and compare the answers and the cost in the "Usage" section of the dashboard.

Background requests are another cost: Open WebUI generates chat titles, tags and search queries on its own. You can assign a separate cheap model to them with TASK_MODEL_EXTERNAL (also a persistent setting, which you can change in the admin settings too).

For the current model list, call GET https://api.zukko.pro/v1/models (see the models documentation↗) or open the "Models" page in the dashboard.

Common errors and fixes

404 or an empty model list

It's almost always the address. Correct: https://api.zukko.pro/v1. Wrong: no /v1, or an extra /chat/completions at the end.

401: invalid key

The key was copied partially, with a space, or was deleted in the dashboard. Create a new key and update it in Connections — there, not in docker run (see the section on persistent settings).

402: insufficient balance

Top up your balance in the dashboard: SBP, Russian bank cards and crypto are supported, the minimum is $1.

403: model_not_allowed_for_key

The model isn't on this key's allowed list. Add it in the key settings or remove it from the connection's Model IDs.

400 on Claude models

claude-sonnet-5 and claude-opus-5-5 may reject a request with a 400 error if temperature is anything other than 1 or top_p is below 0.99. If you changed these in the chat or model advanced settings (Advanced Params), set them back to default for Claude.

429 or 503

429 means too many requests; wait and retry. 503 means the model provider is temporarily unavailable; switch to another model or try again later.

For request details, check the container logs: docker logs open-webui.

FAQ

Can my colleagues use the same Open WebUI?

Yes, create accounts for them in the admin settings. All requests go through one Zukko key, so it makes sense to set daily and monthly limits on it — see the key limits documentation↗.

Can I see my Zukko balance in Open WebUI?

No. Balance and spending history are in the dashboard under "Usage", and also available through the balance API↗.

How do I update Open WebUI without losing chats?

Remove the container with docker rm -f open-webui, pull the new image with docker pull ghcr.io/open-webui/open-webui:main, and run the same docker run command. Data and connection settings stay in the open-webui volume.

Do I need a separate key for Open WebUI?

Not required, but handy: a dedicated key makes it easier to track spending and set limits. If you don't have one yet, create it in the Zukko dashboard↗ — setup takes a couple of minutes.