Open WebUI

Open WebUI is a convenient chat interface for models accessible via API. It allows interaction with AI agents in a familiar dialogue format.

This guide explains how to install Open WebUI and connect it to an AI agent.

The guide assumes that you have already created an AI agent. 

Installation

Open WebUI can be deployed locally on your workstation or on a remote server for continuous access to the chat.

Minimum requirements: 2 GB of RAM.

Ensure that Docker and Docker Compose are installed:

docker --version
docker compose version

Local Deployment

To deploy Open WebUI locally, create a docker-compose.yaml file with the following content:

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

Server Deployment

If deploying on a server for easier access, it is recommended to use a domain and SSL certificate. Create a .env file with the following variables:

DOMAIN=openwebui.example.com
LETSENCRYPT_EMAIL=admin@example.com
TZ=Europe/Cyprus

• DOMAIN: the domain where Open WebUI will be accessible. Ensure the domain’s A record points to your server.
• LETSENCRYPT_EMAIL: the email address used for issuing an SSL certificate.
• TZ: the server’s timezone.

Then, create a docker-compose.yaml file with the following content:

version: "3.8"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "letsencrypt:/letsencrypt"

  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    restart: unless-stopped
    environment:
      - TZ=${TZ}
      - WEBUI_URL=https://${DOMAIN}
    volumes:
      - openwebui-data:/app/backend/data
    labels:
      - "traefik.enable=true"

      # HTTPS router
      - "traefik.http.routers.openwebui.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui.entrypoints=websecure"
      - "traefik.http.routers.openwebui.tls.certresolver=myresolver"
      - "traefik.http.services.openwebui.loadbalancer.server.port=8080"
      - "traefik.http.services.openwebui.loadbalancer.server.scheme=http"

      # HTTP router redirecting to HTTPS
      - "traefik.http.routers.openwebui-http.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui-http.entrypoints=web"
      - "traefik.http.routers.openwebui-http.middlewares=redirect-to-https"

      # Middleware for redirecting
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"

volumes:
  openwebui-data:
  letsencrypt:

Save the manifest and start the container:

docker compose up

Docker will download the image and deploy Open WebUI. Once the logo appears in the terminal, open your browser at http://localhost:3000/ (or use your domain if deployed on a server).

If the welcome page loads, the installation was successful.

Return to the terminal and stop the container with Ctrl+C, then restart it in detached mode:

docker compose up -d

Refresh the page in your browser (http://localhost:3000/); the welcome page should appear again.

Connecting an AI Agent

Click Let’s get started.

Complete the administrator account setup. For local deployments, you may use a simple password; for server deployments, choose a strong password. The email entered is only used as an identifier or login; no emails are sent to it.

Open WebUI supports two methods for connecting AI agents:

• Direct connection: each user provides their own API key and URL.
• Global connection: connection settings are configured once in the admin panel and used by all users.

Direct Connection

After creating the admin account, you will be in the main workspace. To connect agents:

1. Click the account name in the lower-left corner and select Admin Panel.

2. Go to Settings → Connections and enable Direct Connections. Save changes.

3. To connect a model, click the account name again and select Settings → Connections, then click the + icon.

4. In the popup, enter:

• URL: copy from the OpenAI URL field on the agent’s Access tab in the Hostman dashboard.

• Key: API token for accessing the agent.

5. Click Test Connection. If there are no errors, save the configuration.

6. Close the settings window and click New Chat. Your AI agent’s model should appear in the model selection menu. If not, refresh the page and check again.

At this point, Open WebUI installation and direct agent connection are complete.

Global Connection (for all users)

To configure a single connection for all users:

1. Click the account name in the lower-left corner and select Admin Panel.

2. Go to Settings and click the + icon next to OpenAI API.

3. In the popup, enter:

• URL: from the agent’s OpenAI URL field in Hostman.

• Key: API token for agent access.

4. Click Test Connection, then save if successful.

5. Close the settings window and click New Chat. Your AI agent’s model should appear in the model selection menu. If not, refresh the page and check again.

Open WebUI is now fully set up and connected to your AI agent.