---
title: "Open WebUI Setup Guide | Hostman Docs"
description: "Learn how to install Open WebUI using Docker and connect it to AI agents via API. Explore local and server deployment, Traefik setup, SSL configuration, and direct or global model connections."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

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](https://hostman.com/docs/ai-agents/manage-agents/create/). 

## 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:

```shell
docker --version
docker compose version
```

### Local Deployment

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

```shell
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:

```shell
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:

```shell
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:

```shell
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:

```shell
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](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/) for accessing the agent.
    

6.  Click **Test Connection**. If there are no errors, save the configuration.
    
7.  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](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/) for agent access.
    

5.  Click **Test Connection**, then save if successful.
    
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.
    

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