Open WebUI: Local AI Setup, Features & Requirements

Use it when

you want a browser chat workspace connected to a model that already works.

Avoid it when

your model provider is not working yet or you want the fewest moving parts.

Where your data goes

Your browser connects to the Open WebUI server, which contacts your selected model and document-processing services. Choose local inference, extraction, embeddings and reranking in Admin Settings for an on-device workflow. Offline mode controls selected downloads and checks; it is not a firewall. External search, tools and hosted providers can send content elsewhere.

Easiest alternative

Use the underlying provider directly for a simpler setup

Use Open WebUI when you have a working model provider and want a browser workspace with saved conversations, reusable document collections, or access for other people. It adds a service to administer. If you only need occasional chat with one model, the provider's own desktop interface may be enough.

For a typical local setup, your browser contacts Open WebUI, which in turn communicates with Ollama, and Ollama runs the model. Choosing a hosted provider changes that final destination. Document extraction, search, and tools can also point elsewhere, so the browser's local address doesn't mean the entire workflow stays on your computer.

Get the model working before adding the interface

Install Ollama through its official instructions and use a small downloaded model that fits your computer. One modest connection exercise is:

ollama run qwen3:1.7b

This download is about 1.4 GB (a 4-bit Q4_K_M file); running memory is higher. It is a small setup example, not a recommendation for demanding document interpretation. At its conversation prompt, set a modest context:

/set parameter num_ctx 4096

Ask it to rewrite “The orientation session will commence at 10:30. Attendance requires prior registration.” Require it to preserve the time and registration condition. Check the answer before proceeding. A later knowledge-tool exercise may need a model with stronger tool-call support even if this ordinary chat works.

Use the native Ollama app on macOS for this arrangement. Open WebUI can run in Docker Desktop while Ollama runs on the host; that is different from trying to accelerate Ollama itself inside a macOS container.

Install a personal browser service

The following example is for Docker Desktop on Windows or macOS with Ollama already running on the same computer. Use an up-to-date Docker installation. Docker documents that versions before Engine 28.0.0 had a same-network exception to the protection expected from loopback-published ports.

Create a private settings folder. In it, save a plain-text file named openwebui.env containing:

WEBUI_SECRET_KEY=REPLACE_WITH_A_LONG_RANDOM_SECRET
OLLAMA_BASE_URL=http://host.docker.internal:11434

Replace the placeholder with a long random secret from your password manager. If OpenSSL is available, openssl rand -hex 32 generates one. Keep the secret for future container recreation and keep the file out of public repositories. It is application configuration, not your account password.

Run the following from that folder. The example pins v0.12.3, the current release when this page was written, so the installed version is explicit. Check the releases page for a newer tag before installing, and review later releases and security updates rather than keeping a tag indefinitely. The setup guide uses this same recipe and openwebui.env file.

docker pull ghcr.io/open-webui/open-webui:v0.12.3

In Windows PowerShell, create the container with:

docker run -d `
  -p 127.0.0.1:3000:8080 `
  --add-host=host.docker.internal:host-gateway `
  --env-file openwebui.env `
  -v open-webui:/app/backend/data `
  --name open-webui --restart unless-stopped `
  ghcr.io/open-webui/open-webui:v0.12.3

On macOS, use the shell's backslash continuation instead:

docker run -d \
  -p 127.0.0.1:3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  --env-file openwebui.env \
  -v open-webui:/app/backend/data \
  --name open-webui --restart unless-stopped \
  ghcr.io/open-webui/open-webui:v0.12.3

Do not run both creation commands. They express the same operation for different shells. Keep continuation characters at the line ends without trailing spaces. If a container named open-webui already exists, inspect that installation and its data before replacing it.

Open http://localhost:3000. The explicit port mapping publishes this browser service on the local computer. The named volume open-webui preserves application data when the container is replaced. Retain both the volume and secret. Use the standard image for this first document setup; the slim image omits local document-processing dependencies. Floating tags such as main do not identify a fixed release.

Create the first account yourself; on a fresh instance, it becomes administrator. For personal use, disable further signups afterward. For shared use, require deliberate account approval and appropriate roles before opening access.

Understand the Docker address

Inside a container, localhost means that container. Under Docker Desktop, host.docker.internal addresses the host. In the administration connection settings, the Ollama address for this example is http://host.docker.internal:11434.

On Docker Engine for Linux, adding a host-gateway name does not make an Ollama that listens only on 127.0.0.1 reachable from a bridge-network container. Either run the container with --network=host and HOST=127.0.0.1 (Open WebUI is then at http://127.0.0.1:8080; the host setting replaces the loopback-only port mapping), or set OLLAMA_HOST=0.0.0.0:11434 for the Ollama service and limit port 11434 with your firewall. The connection troubleshooting guide gives both sets of commands.

Confirm the browser connection

In Settings → Admin → Connections, select the Ollama connection type and verify its address. An OpenAI-compatible server belongs under the corresponding connection type instead. Select the same downloaded model that worked directly in Ollama.

Leave search, terminals and extra tools off. Repeat the orientation prompt and inspect both the time and registration requirement. Try another new chat with the same model. If the model is absent, check the saved connection, model filters, and provider process before changing several settings at once.

A model name in a selector does not establish where it runs. Several local and hosted connections can coexist. Confirm the selected provider for each kind of material you intend to submit. With administrator access, open Settings → Admin → Connections and inspect the saved provider URLs. Match the model selected for the conversation to its configured provider; a model name alone may be ambiguous when several connections expose similar names. Disable unused connections for a controlled first trial if necessary. If you cannot establish the mapping or do not have administrator access, ask the administrator to confirm the destination before submitting sensitive material. Use a harmless prompt for the trial and check the intended provider's request logs where available. Separately verify extraction, embeddings and tools, because choosing the answer model does not set all of those destinations.

Add a document with answers you can check

Create sample-office.txt containing this fictional text:

Sample Office Handbook
Fictional example
The sample office opens at 09:15 on weekdays.
Visitors need an appointment on Wednesdays.
The handbook does not state weekend opening hours.

In Admin Settings → Documents, choose local extraction and a local embedding model, also called a document-search model. The standard image can use sentence-transformers/all-MiniLM-L6-v2; prepare its download before requiring offline use. If enabling a reranker, which reorders candidate passages, check that provider separately too.

Open Workspace → Knowledge, create Sample Office, add the file and wait for processing. Inspect the extracted text. In a new conversation, attach the collection using the # selector and ask:

Use Sample Office only. When does the office open on weekdays,
and what extra condition applies on Wednesdays? Quote the passages
supporting both answers. Does the handbook give Saturday opening hours?

The source supports 09:15 on weekdays, an appointment requirement on Wednesdays, and no stated Saturday hours. These are checks derived from invented input, not reported model results. Open the actual passages. A confident Saturday opening time is unsupported even if accompanied by a source marker.

Choose retrieval or full text deliberately

Focused Retrieval finds selected passages related to a question. It is useful for collections larger than a model can read at once, but it can miss a qualification. Native function calling lets a model invoke knowledge tools itself; that requires a model capable of using those tools and the relevant tools enabled.

For the short file, make a separate trial by attaching it directly to a conversation and selecting Full Context. Keep File Context enabled. This supplies its extracted text without relying on passage search. Knowledge attached to a model behaves differently in native mode, where the model accesses it through knowledge tools. Check which arrangement you are testing rather than assuming every attachment is handled identically.

If full text works but retrieval fails, inspect collection access, tool use and search settings. Increasing the answer model's size will not necessarily fix a collection it never searches. More passages can recover context but also crowd out useful information. A long published context limit is not proof that your current model allocation can hold the file and answer.

Try a text-based PDF after plain text works. For a scan, obtain readable OCR text and compare names, dates, and tables with the original image. A file preview is not proof that extraction preserved its contents. If the task requires reviewing every section, track that coverage yourself rather than treating a broad summary generated from retrieved document passages as exhaustive.

Changing the embedding model requires rebuilding Knowledge Base indexes. Reindexing uses previously extracted text; it does not repeat extraction from the originals, and it does not update standalone chat-upload indexes. Re-upload when extraction must change or when standalone files need reprocessing.

Know who receives each part of the request

Stage	Material involved	Configuration to inspect
Extraction	Original upload and extracted text	Document-extraction service
Embedding	Text chunks and search representations	Embedding model and provider
Retrieval and reranking	Query, index and candidate passages	Vector storage and reranker
Answer generation	Instructions, history and supplied passages	Selected model endpoint
Storage and actions	Uploads, chats, tool inputs and outputs	Server data, tools, logs and backups

A cloud extractor can receive the original file, while a cloud embedder receives the text it processes. A local answer model does not prevent either transfer. A local tool may also make external requests.

Prepare models and dependencies before disconnecting. OFFLINE_MODE=true suppresses selected checks and downloads; it is not a network firewall. Test a new harmless document as well as ordinary chat while disconnected. Hosted providers, online sign-in and external tools may fail without connectivity.

Administrators and infrastructure operators remain part of the data-access boundary. Disabling administrative chat viewing in the interface does not remove direct access to the host, database or backups. Protect those separately.

Open WebUI v0.12.3 added temporary encrypted direct messages and private-group channel chats. That feature does not make ordinary AI conversations, uploads or model-provider requests end-to-end encrypted. It also has its own permission, WebSocket and production HTTPS requirements.

Use an ordinary account for everyday work. Keep default permissions narrow and grant needed capabilities through groups. Permissions are additive: a restrictive group does not cancel access granted elsewhere. Test the shared model and underlying Knowledge Base with an ordinary account and with another account that should lack access.

Permission to create or import Tools and Functions can amount to executing code on the server. A tool's friendly name does not limit what its Python code can access. Review tools before enabling them and keep document contents separate from authority to run commands or send information.

Open chat links can permit reading without sign-in. Decide whether that is intended before sharing. Remote notifications, search providers and terminal connections deserve their own access decisions rather than inheriting an assumption that self-hosting makes them private.

Back up before updating

For the default Docker arrangement, /app/backend/data contains application records, uploads, vector storage, and caches. Ollama's model downloads live separately in Ollama's storage. A chat export is not a backup of the whole instance.

Preserve the current image tag, environment file and persistent data. Stop writes while taking a consistent backup. External databases, vector stores and file services need their own backup scope. Restore into an isolated instance and check an account, a conversation and the sample document answer before relying on recovery.

For an update, read the chosen release's migration notes, pull its image, stop and remove the old container, then recreate it with the new tag and the same volume, environment file, and loopback mapping. Do not remove the volume as part of a routine update. A database migration can make reverting only the application image ineffective; retain the matching pre-update backup.

After restarting, confirm the version and repeat chat, document and ordinary-account checks. Keep the application patched even on a private network. Historical fixes for document-preview and Knowledge Base permission defects illustrate why “private network” is not a substitute for maintenance.

Remove files and diagnose failures precisely

Use Settings → Data Controls → Manage Files to delete an uploaded file from the instance. The documented operation removes its Knowledge Base associations and corresponding embeddings. However, it does not remove original files, quotations in old conversations, exports, backups, or copies retained by external providers. To address remaining copies, first identify your retention requirements and the locations you control. Review the original file, quotations in old conversations, chat exports and backups; remove relevant copies where permitted. For external extraction, embedding or model services, use the provider's deletion process and check its retention terms, including any delayed deletion or retained backups. A policy statement alone does not confirm that a particular copy has been removed. Recheck accessible storage and record any copies whose deletion you cannot establish. Deleting files from the interface is different from sanitizing a storage device: when retiring media, use a method suited to that device and verify the result. These steps reduce retained data without promising that every trace is gone.

Symptom	Useful next action
A model works in Ollama but is missing here	Check connection type, saved URL, model filters and the address reachable from the container.
The answer lacks a supporting passage	Inspect processing and extracted text, then collection access and tool use. Compare the short direct Full Context attachment.
Retrieval worsens after an embedding change	Reindex Knowledge Bases and reprocess affected standalone files.
Long documents cause blank answers or raw tool-call text	Check allocated context and model tool support. Open WebUI's per-request num_ctx can override Ollama's server default.
An environment change has no effect	Open WebUI keeps saved settings in its database, and they take precedence over environment variables. Edit the value in Admin Settings, or start the container once with `-e RESET_CONFIG_ON_START=true` to reset saved settings to the environment values. Do not delete the data volume to force a setting change.

Check the software and model terms separately

The Open WebUI License for v0.12.3 includes notice requirements and a branding restriction. Its exceptions include deployments or distributions with no more than 50 individual end users within a rolling 30-day period, written permission, or an appropriate enterprise license. Read the full clause before rebranding or distributing a service. Prior-license material retains its original terms. Models and hosted providers have separate licenses or contracts.