DEV Community

Cover image for LLM Agent Tools: Setup & Installation of OpenWeb UI
Sebastian
Sebastian

Posted on

LLM Agent Tools: Setup & Installation of OpenWeb UI

#ai #agents #llm #openwebui

LLMs are a fascinating technology. Trained on a sufficient subset of the public internet and other curated sources, they are knowledge experts in many fields. Chat interfaces for LLMs have become a daily helper for many knowledge workers. Step by step, agent capabilities are driving the evolution of these interfaces.

In an ongoing series about agentic tools, capabilities, and technical components, the next articles focus on Open WebUI. This article is concerned with the initial setup - you will learn how to install and run a Docker container, and see how to connect with an LLM provider to start chatting.

The technical context of this article is openwebui v0.9.6, published on 2026-06-01. The setup and configuration examples should also work with newer versions.

While I am fascinated by the capabilities of artificial intelligence tools and applications, crafting blog articles remains my personal skill. Every character, number, and symbol in this article was typed manually, with the exception of verbose copies from log messages and screenshots.

This article originally appeared at my blog admantium.com.

Setup

Any software needs the required libraries in specific versions. To avoid cluttering one’s own system, container-based software can be used instead. Each container provides a separate environment, and it exposes its services via defined ports. Docker is the primary tool for starting containers, and it is the tool of choice for setting up agentic tools in the context of this article.

For Open WebUI, complete Docker containers for all releases are published automatically. Check the available tags, then download the required container. For v0.9.6, execute the following command:

docker pull ghcr.io/open-webui/open-webui:v0.9.6
Enter fullscreen mode Exit fullscreen mode

Once the image is downloaded, it can be started with a simple follow-up command. If you want to try Open WebUI with the default config, simply run the following:

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:v0.9.6
Enter fullscreen mode Exit fullscreen mode

Then access the application at http://localhost:3000 and start configuring the admin account. While you can use the container as-is, its state will not be persisted. When the Docker daemon of your host system is restarted, all data in the container is lost. The recommended approach is to define a docker-compose.yml file, which tracks the applied configuration options and also persists the created data as a volume.

Docker Compose Configuration

Open WebUI exposes several configuration options. To keep the state persistent, it should be started with a config file to define aspects like its users and LLM configuration. It should also have a volume in which all permanent data is stored so it survives container restarts.

Create the following file structure:

.
├── docker-compose.yml
└── .open-webui.env
Enter fullscreen mode Exit fullscreen mode

Use the following template for the docker-compose.yml file as a kickstart.

name: openwebui

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.9.6
    container_name: open-webui
    env_file:
      - ./open-webui.env
    ports:
      - "3000:8080"
    restart: unless-stopped
    volumes:
      - open-webui-data:/app/backend/data
    networks:
      - openwebui

networks:
  openwebui:
    name: openwebui
    external: true

volumes:
  open-webui-data:
    name: open-webui-data
    driver: local
Enter fullscreen mode Exit fullscreen mode

Next, add the following .open-webui.env file with a minimal configuration:

OPENWEBUI_PORT=3000
Enter fullscreen mode Exit fullscreen mode

Only once, you need to run the following command:

docker network create openwebui
Enter fullscreen mode Exit fullscreen mode

Then start the container with the following command:

docker compose up open-webui
Enter fullscreen mode Exit fullscreen mode

It should print these log messages, indicating a successful initial setup.

docker compose up open-webui

open-webui-manual  | No WEBUI_SECRET_KEY environment variable set, loading from file.
open-webui-manual  | Generating new WEBUI_SECRET_KEY...
open-webui-manual  | Loading WEBUI_SECRET_KEY from .webui_secret_key
...
open-webui-manual  | INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
open-webui-manual  | INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
open-webui-manual  | INFO  [alembic.runtime.migration] Running upgrade  -> 7e5b5dc7342b
...
open-webui-manual  |
open-webui-manual  |  ██████╗ ██████╗ ███████╗███╗   ██╗    ██╗    ██╗███████╗██████╗ ██╗   ██╗██╗
open-webui-manual  | ██╔═══██╗██╔══██╗██╔════╝████╗  ██║    ██║    ██║██╔════╝██╔══██╗██║   ██║██║
open-webui-manual  | ██║   ██║██████╔╝█████╗  ██╔██╗ ██║    ██║ █╗ ██║█████╗  ██████╔╝██║   ██║██║
open-webui-manual  | ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║    ██║███╗██║██╔══╝  ██╔══██╗██║   ██║██║
open-webui-manual  | ╚██████╔╝██║     ███████╗██║ ╚████║    ╚███╔███╔╝███████╗██████╔╝╚██████╔╝██║
open-webui-manual  |  ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝     ╚══╝╚══╝ ╚══════╝╚═════╝  ╚═════╝ ╚═╝
open-webui-manual  |
open-webui-manual  |
open-webui-manual  | v0.9.6 - building the best AI user interface.
open-webui-manual  |
open-webui-manual  | https://github.com/open-webui/open-webui
open-webui-manual  |
Enter fullscreen mode Exit fullscreen mode

Two options exist for the initial onboarding; see the next two paragraphs.

Manual Onboarding

The first step is to create an admin account. Access the application at http://localhost:3000 and fill out the shown fields.

Once completed, you will see the initial welcome message and a popup showing current version information. While manual onboarding is an option, the better approach is to extend the .open-webui.env file so that the admin account and other settings are controlled and persisted between container restarts. This is explained in the next section.

Onboarding with Config File

Alternatively to the dialog-based setup, settings about the admin user and additional variables to influence privacy and telemetry can be configured. The list of supported variables is extensive; see the official documentation for all options.

What you should also persist is the WEBUI_SECRET_KEY. Its value is used to encrypt JWT access tokens and stored secrets. As shown in the container start logs, its value is dynamically created. Therefore, restarting the container invalidates current sessions and also makes encrypted data obsolete. Check the file content of /app/backend/.webui_secret_key, and add it too.

Here is the extended .open-webui.env with all options.

# Port, persistence, logging
WEBUI_URL=http://localhost:8080
ENABLE_PERSISTENT_CONFIG=True
GLOBAL_LOG_LEVEL=INFO
LOG_FORMAT=json
WEBUI_SECRET_KEY=REDACTED

# Only allow one pre-configured admin user
WEBUI_ADMIN_NAME=Admin
WEBUI_ADMIN_EMAIL=REDACTED
WEBUI_ADMIN_PASSWORD=REDACTED
ENABLE_SIGNUP=False
ENABLE_LOGIN_FORM=True
ENABLE_PASSWORD_AUTH=True
ENABLE_PASSWORD_CHANGE_FORM=True

# Better privacy
ENABLE_ADMIN_ANALYTICS=False
ENABLE_PUBLIC_ACTIVE_USERS_COUNT=False
ENABLE_USER_STATUS=False
ENABLE_EASTER_EGGS=False
ENABLE_OTEL_LOGS=False
Enter fullscreen mode Exit fullscreen mode

Now restart the container once, and from then on all settings persist.

docker compose restart open-webui
Enter fullscreen mode Exit fullscreen mode

A warning: all of these variables, and additional changes in the GUI, are persisted. To reset, for example, the login values, stop the container, set ENABLE_PERSISTENT_CONFIG=True, then restart it. If there is a further problem, you can also set RESET_CONFIG_ON_START=true to delete the database, or take the final option to completely delete the Docker container and the volume.

Model Configuration

To use Open WebUI for its intended purpose, you need to add an LLM provider endpoint. Essentially, any endpoint that supports the OpenAI API format can be used. Besides OpenAI itself, you can choose from any direct provider, OpenRouter, or even GitHub Copilot with an additional proxy server.

For brevity, let's invoke the ChatGPT API directly.

First, create an OpenAI API key as follows:

  • Log in to the OpenAI service
  • Go to the API key page
  • Click the “+ Create New Secret Key” button, provide a name, and copy the key from the popup

Second, configure the endpoint in Open WebUI:

  • Access the Open WebUI dashboard
  • Click on the admin user icon in the bottom-left corner, and then click “Admin Panel”
  • In the horizontal tab bar, click “Settings,” then “Connections”
  • Disable all toggles from the bottom up
  • Enable the “OpenAI API” toggle
  • Click the “+” symbol next to “Manage OpenAI API Connections”

Now, the following dialogue should appear.

  • For the API endpoint URL, enter https://api.openai.com/v1
  • Enter your created API key
  • Click on the double-arrow icon to validate the connection; a green popup appears to show success

Finally, you can start a new chat from the dashboard.

Conclusion

Many tools exist for ongoing, contextual conversations with an LLM. Open WebUI is one of the earliest tools to support contextual conversations with LLMs. Since its inception in October 2023, many features were added. In this article, you learned how to set up and configure the tool as a Docker container with defined, persisted config. You saw the relevant docker-compose.yml and .env file, learned about the nuances of onboarding, the consequences of not persisting the central encryption key, and how to configure an LLM provider. The next article continues the feature exploration.

Top comments (0)