How to use Darkbloom with Open WebUI

At a glance

How do I use Darkbloom with Open WebUI?

Open WebUI’s connection form has no Darkbloom choice. It does not need one: its OpenAI connection takes any web address that answers OpenAI’s API, and Darkbloom does. So you edit the connection that Open WebUI starts with, https://api.openai.com/v1, so that it points at Darkbloom. The steps below describe Open WebUI 0.12.3, which we ran in Docker on our own machine. Menu names can differ in other versions, and we did not run the pip, Kubernetes or desktop installs.

1. Get a Darkbloom API key. Open the Darkbloom console and sign in, add credits (the minimum is $0.50, and Darkbloom says credits are non-refundable and never expire), then choose API console in the console’s left menu and Create API key (Darkbloom’s docs call this page Settings → API Keys). The console shows the key only once, so copy it right away. Every key spends from your prepaid balance, so add only what you are willing to spend while you test, and watch your first chats, because Open WebUI sends several requests for one message.
2. Start Open WebUI. If you already run it, skip to step 4. Otherwise install Docker, make a secret with openssl rand -hex 32, and run the command from Open WebUI’s docs with that secret in place of your-secret-key. Then open http://localhost:3000 in your browser. The first start took 20 to 32 seconds on our machine, and once 99 seconds when the machine was busy, so give it a minute or two.

   The command in Open WebUI’s docsCopy

   docker run -d -p 3000:8080 \
     --add-host=host.docker.internal:host-gateway \
     -v open-webui:/app/backend/data \
     -e WEBUI_SECRET_KEY=your-secret-key \
     --name open-webui --restart always \
     ghcr.io/open-webui/open-webui:main

3. Create the admin account. The first screen says Welcome to your AI home. Click Get started, enter a name, an email address and a password, and click Create Admin Account. The first account is the administrator, and it exists only on your machine. A What's New in Open WebUI box opens next: click Okay, Let's Go!.
4. Open the connections page. Click your avatar at the bottom left and choose Settings. In the list on the left of the Settings window, find the Admin heading and click Connections under it.
5. Point the OpenAI connection at Darkbloom. The page lists one connection under Manage OpenAI API Connections, with the address https://api.openai.com/v1. Click the gear beside it. In the Edit Connection window, replace the address in URL with the one below, leave Auth on Bearer, and paste your key into the box beside it. Leave API Type on Chat Completions.

   URLCopy

   https://api.darkbloom.dev/v1

   API KeyCopy

   YOUR_DARKBLOOM_API_KEY

6. Test the connection, then save it. Saving does not test a connection, so click the icon of two circular arrows beside the URL first. Server connection verified means Darkbloom accepted the key. OpenAI: invalid API key means the key is wrong, and OpenAI: Network Problem means the URL is not Darkbloom’s address. Then click Save in the window, and Save again at the bottom right of the page. OpenAI API settings updated confirms it.
7. Send a message. Close Settings. You land on a new chat, and if you do not, click the pencil icon at the top of the narrow bar on the left. Open WebUI chose Gemma 4 26B for us. To choose another model, click the model name at the bottom right of the message box. Type Say hello in five words. and press Enter. The reply appears, and then Open WebUI makes up to three more requests: a title for the chat in the sidebar, follow-up suggestions under the reply, and tags.
8. Optional: switch off what you do not use. In Settings, click the second Interface in the left list, the one under the Admin heading. Under Generation, switch off Title Generation, Follow Up Generation and Tags Generation, starting with the lowest, because the rows below a switch move up when you turn it off. Click Save at the bottom right. Then click Models under Admin, open Model Defaults, Model Capabilities and Builtin Tools, switch off the tools you do not use and click Save. The cost section shows what each switch saves.

What does each setting in Open WebUI mean?

The first rows are the fields of the connection and the rest are the admin settings that mattered when we tested. We left every setting that is not listed at its default.

Which Darkbloom model should I use with Open WebUI?

Use any ID that GET /v1/models returns. On October 23, 2026 it listed 12 models, shown here from the cheapest output price up, in US dollars per million tokens. Check the live prices before you rely on a number; that public list also names models that are not online. A key can be limited to some models, and Darkbloom refuses any other with a 403 (see the errors table).

Open WebUI lists models by the name Darkbloom gives them, not by their ID, so gemma-4-26b appears as Gemma 4 26B. If another tool or an error message asks for the ID, use the second column of this table.

A listed model can still be refused with a 403 if your key is limited to some models, and the picker does not know which ones those are. Either choose only models you know your key allows, or list those under Advanced, Model IDs in the connection. We ran gemma-4-26b for the cost numbers and EigenLabs/Qwen3.8-27B-4bit-mtp for the thinking checks. A model that thinks first spends part of any token limit on its thinking. Darkbloom’s list does not mark EigenLabs/Qwen3.8-27B-4bit-mtp as a reasoning model, but it thinks: with max_tokens at 30 it used all 30 tokens, and Open WebUI showed only Thought for less than a second, with no answer and no error.

Which Open WebUI features work with Darkbloom?

We ran the chat features. For the others, the last rows say what we know.

How much does Open WebUI cost with Darkbloom, and how do I keep it low?

Darkbloom bills the tokens you use from your prepaid balance: (input tokens × input price + output tokens × output price) ÷ 1,000,000, with a minimum of $0.0001 per request. Open WebUI adds more to a request than your message, and it makes extra requests. With its default settings, the one-line message Say hello in five words. to gemma-4-26b made four requests:

Only the chat request is above the minimum, because it carries the tool definitions (about 5,800 tokens) for a reply of 8 tokens. At the October 23, 2026 prices that request is worth $0.000245, and Darkbloom billed $0.000244, because it rounds each part down. Six other chat requests of this size (5,583 to 5,929 tokens in, one of them on another model) were each billed exactly $0.0002, and we do not know why. Darkbloom’s usage log lists cached_tokens for a request that reused cached text, and Darkbloom bills those tokens at a lower cached price ($0.021 per million tokens for Gemma 4 26B, instead of $0.042), but these six rows list none.

These figures come from several runs, and they vary a little. In our last run the follow-ups were 47 tokens out, and the usage log had no row for the tags request, so that message cost $0.000444. In our earlier runs, a tags request that Darkbloom answered with 429 had no row either.

A later message in the same chat is cheaper to set up. The second message was one chat request that carried the earlier messages (3 messages in all) and the tool list, 5,820 tokens in, and one follow-up request of 353 tokens in. Open WebUI did not make a title or tags again. A question that made the model call a tool cost two chat requests, 5,810 and 5,929 tokens in, each carrying the whole tool list.

Open WebUI shows no price of its own, so check your real spend in the Darkbloom console, or call GET /v1/payments/usage with your key (Darkbloom docs: usage history).

Can I set up Open WebUI with environment variables instead?

Yes, on a new data folder. Open WebUI reads OPENAI_API_BASE_URL and OPENAI_API_KEY the first time it starts and saves them in its database. After that it uses the saved values: when we started the same data volume again with different values, the first ones stayed. Open WebUI’s docs say ENABLE_PERSISTENT_CONFIG=False makes the environment win on every start, and that settings you change on screen are then not kept, which is what we saw when we tried it.

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY=your-secret-key \
  -e OPENAI_API_BASE_URL=https://api.darkbloom.dev/v1 \
  -e OPENAI_API_KEY=YOUR_DARKBLOOM_API_KEY \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

Started this way on an empty volume, Open WebUI listed all 12 models that Darkbloom returned that day without any click in Settings. We did not send a chat through this route. docker inspect open-webui shows the key, so use the screens in the steps if other people can run Docker on your machine.

Where does Open WebUI keep my API key?

In plain text, in Open WebUI’s own database. That is a SQLite file, webui.db, in Open WebUI’s data folder (/app/backend/data in Docker, which is the open-webui volume in the documented command). Every admin account can see the key: the Edit Connection window shows it as dots, the eye icon beside it shows the text, and Open WebUI’s admin interface returns it. If the key leaks, delete it in the Darkbloom console and create a new one.

Anyone who can read the data volume or its backups can read your key and your chats, so protect them like the key itself.

What do the common errors mean?

In a chat, an error shows as a grey banner under the model name. The connection test shows its result as a pop-up at the top right. Each row was seen in Open WebUI 0.12.3, except the empty-balance row. Two rows, the invalid key and the output tokens banner, came from a test server that answers as Darkbloom does.

Is Darkbloom private, and is it ready for production?

Not yet for sensitive work. Darkbloom’s quickstart calls the service “an experimental research prototype” and says not to use it in production applications, and its console labels it Public alpha. Darkbloom says prompts are encrypted to a verified provider Mac. Its security overview says the coordinator re-encrypts each request for the chosen provider and runs in a confidential VM. An independent review by Wavect (September 2026) reads Darkbloom’s technical documentation as saying that both the coordinator and the provider handle your prompt as plaintext inside protected boundaries.

Open WebUI sends the text of your message and the earlier messages of the chat to Darkbloom, together with its built-in tool definitions. The first message and the reply go again, in the background requests that make the chat title, the follow-up suggestions and the tags. Do not send secrets, customer data or code you are not allowed to share.

Open WebUI keeps a copy of your chats for itself. In our test the text of every chat was readable in webui.db, next to the key. Protect that data volume and its backups like the prompts themselves.

Open WebUI’s account screen says it makes no external connections. In our runs it also contacted GitHub (a check for a newer version), Hugging Face (a check for its local embedding model when it starts) and, until we edited the OpenAI connection, OpenAI (a model list, without a key). These calls do not need your chats, but we did not capture all of Open WebUI’s traffic. By default it does not send your name or email to Darkbloom: ENABLE_FORWARD_USER_INFO_HEADERS is off (Open WebUI docs), and a test server showed no such headers. The docs say OFFLINE_MODE switches off the update check and the model downloads and keeps connections like Darkbloom working.

How this guide was checked

• A paid request from Open WebUI to api.darkbloom.dev worked on October 23, 2026. We ran the steps on this page again as written, from a clean state. Open WebUI 0.12.3 in Docker, with an empty data volume, answered Say hello in five words. with gemma-4-26b selected. Darkbloom’s usage log shows the requests that this made billed $0.0001 for the title, $0.000244 for the answer and $0.0001 for the follow-ups, with no row for the tags request.
• The setup steps were compared with Open WebUI’s own docs (linked under Sources) on October 23, 2026. Where the docs and the program differ, this page follows what we saw: the docs tell you to click the + beside Manage OpenAI API Connections, and this page edits the OpenAI connection that is already there (adding a connection with the + also worked, and leaves the OpenAI row on, which then asks OpenAI for a model list without a key); and the docs call the test a Verify Connection button, which in 0.12.3 is an unlabeled icon of two circular arrows beside the URL.
• We ran Open WebUI 0.12.3 (the ghcr.io/open-webui/open-webui:main image of October 16, 2026, the same version as the latest release on PyPI that day) in Docker, with the command in Open WebUI’s docs and these changes for our machine: the host network with its own port, and our network’s proxy and certificate file. We used a browser from a fresh start, with an empty data volume: the account screen, the connection as on this page, chats with gemma-4-26b and EigenLabs/Qwen3.8-27B-4bit-mtp, a built-in tool call, a second message in the same chat, the Model IDs list, and the switches in the cost section. To see what Open WebUI sends, we also ran it through a local forwarder that passed each request to Darkbloom unchanged and logged its path, size and settings.
• In the run that the first line describes, we followed the steps in the order of this page: the admin account, the edit of the OpenAI connection (the test said Server connection verified), and the message. The follow-ups request had 47 tokens out, one more than in our earlier runs. The usage log has no row for the tags request, and we did not see why: in our earlier runs, a tags request that Darkbloom answered with 429 left no row either.
• The error rows were seen with Open WebUI against Darkbloom, except the “invalid API key” row and the output tokens banner, which used a test server that returns Darkbloom’s real reply for a wrong key and for that 429, and the empty-balance row, because that needs an empty balance. The draining row happened once, on a real request. The causes of the 429 rows come from Darkbloom’s API contract in its source repository (linked under Sources). Darkbloom’s 404 for /v1/embeddings comes from calling it directly, not from Open WebUI.
• The request sizes and amounts in the cost section come from Darkbloom’s usage log. For the runs through the forwarder we matched each request to its row by the job ID that Darkbloom returns, and for the clean run by its time and token counts. We compared 410 rows of the usage log that we captured while testing with Darkbloom’s pricing reference, which says each part of a bill is rounded down and that cached prompt tokens are billed at the cached price: 404 rows matched to the micro-dollar, 5 of them with cached tokens listed. The other 6 are the chat requests billed exactly $0.0002. They list no cached tokens, so we do not know why they were billed less.
• On the key and chat storage, we looked in webui.db, in the container’s log and in docker inspect, and asked the admin interface for the connection settings. That Open WebUI sends no name or email headers was checked with a local test server that prints the headers it receives. The environment variable route was checked on a new data volume with a test server (the first values applied, a second start with other values kept the first ones, and ENABLE_PERSISTENT_CONFIG=False made the new values win) and on a new volume against Darkbloom, where it listed the models. We did not chat through it.
• That Darkbloom lists POST /v1/responses comes from Darkbloom’s console, which names it in its API console page, and from the README of its source code; its docs site documents only chat completions. We called it with Open WebUI and it worked for the chat and the three background requests.
• The model list, names, context windows, features and prices come from GET /v1/models on October 23, 2026 (it needs a key). The key steps in the console come from the console’s own page text. We tested with a key that already existed, so we did not click through key creation ourselves.
• Our test machine adds that key to requests to Darkbloom on their way out, so in the runs against Darkbloom the connection held this page’s placeholder. That Open WebUI sends the key it is given was checked separately, with a local test server that prints the Authorization header it receives: it got Bearer and the key we had entered.
• Not run: the pip, Kubernetes and desktop installs, Windows, a second user account, Direct Connections, the Auth choices other than Bearer, the Provider choices other than Default, image attachments, file uploads and knowledge bases, voice, image generation, web search, the code interpreter, the built-in tools other than the time tool, other Open WebUI versions, and an empty balance.
• Our Darkbloom link was opened in a clean browser profile on October 22, 2026. It saved the referral code and the page said the code “is saved and will be applied after you sign in”. We did not create an account to test the sign-in step itself.

About this guide

BloomGauge is a free Mac app for people who run Darkbloom providers, so we benefit when Darkbloom has more paying demand. We are independent of Darkbloom and not endorsed by it. Our Darkbloom sign-in links carry our referral code, BLOOMGAUGE. If you sign in to Darkbloom after opening one, Darkbloom attaches the code to your account and pays us a share of your eligible token spend. Darkbloom funds that reward, so it does not change your price.

Sources

• Open WebUI docs: quick start
• Open WebUI docs: OpenAI-compatible providers
• Open WebUI docs: environment variables
• Darkbloom console: API console (endpoint list)
• Darkbloom source code: README (API surface)
• Darkbloom source code: API contracts (429 causes)
• Darkbloom source code: pricing model (cached tokens, rounding)
• Darkbloom docs: quickstart
• Darkbloom docs: chat completions
• Darkbloom docs: authentication and API keys
• Darkbloom docs: add credits
• Darkbloom docs: usage history
• Darkbloom live prices (GET /v1/pricing)

Found something out of date? Tell us in #bloomgauge on the Darkbloom Slack or at Support.