> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenWebUI

> Deploy OpenWebUI with Docker Compose and connect it to MixRoute to access a wide range of popular AI models.

Open WebUI is a feature-rich open-source AI interface that supports multiple model providers and offers user management and persistent chat history. This guide walks through deploying Open WebUI with Docker Compose and connecting it to **MixRoute** to access a wide range of popular AI models.

* Official docs: [docs.openwebui.com/getting-started/quick-start](https://docs.openwebui.com/getting-started/quick-start/)
* Deployment method: Docker Compose

## Prerequisites

<Steps>
  <Step title="Prepare MixRoute credentials">
    1. Obtain your MixRoute API endpoint URL: `https://api.mixroute.ai/v1`
    2. Generate your API Key in the MixRoute console.
    3. Confirm the model name you want to use, e.g. `gpt-5.5` (make sure this model is enabled in the MixRoute console).
  </Step>

  <Step title="Environment dependency check">
    Make sure **Docker** (including Docker Compose V2) is installed on your machine or server. Run in a terminal:

    ```bash theme={null}
    docker -v
    docker compose version
    ```

    If both commands return a version number, your environment is ready. If Docker is not installed, go to the [Docker website](https://docs.docker.com/get-docker/) to download and install Docker Desktop (Windows/macOS) or Docker Engine (Linux), then re-run the commands above to confirm.

    <Note>
      Earlier versions of Docker Compose use the `docker-compose` syntax (with a hyphen). This guide uses the newer `docker compose` syntax (with a space).
    </Note>
  </Step>
</Steps>

## Deploy OpenWebUI

### 1. Create a dedicated folder

Open a terminal and run the following commands to create an `openwebui` folder and enter it:

```bash theme={null}
mkdir openwebui
cd openwebui
```

### 2. Create docker-compose.yml

Inside the `openwebui` folder, create a file named `docker-compose.yml` with the following content (copy and paste the full file):

```yaml theme={null}
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      # host port:container port
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

**Field reference:**

| Field                | Purpose                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `image`              | The official Open WebUI image (`main` is the standard stable tag)                                      |
| `ports: "3000:8080"` | Maps container port 8080 to host port 3000, so you access the UI on port 3000                          |
| `volumes`            | Persistent data directory so chat history, accounts, and other data survive container restarts/updates |
| `restart: always`    | Automatically restart the container if it exits or the system reboots                                  |

<Note>
  If you run Open WebUI on a server or within a LAN, you can add the `WEBUI_SECRET_KEY` and `WEBUI_URL` environment variables:

  * `WEBUI_SECRET_KEY`: generate one with `openssl rand -hex 32`.
  * `WEBUI_URL`: your public IP or domain.

  If port 3000 is already in use on your machine, change `"3000:8080"` to e.g. `"3010:8080"` and access the UI at `http://localhost:3010`.
</Note>

### 3. Start the service

From the directory containing `docker-compose.yml`, run:

```bash theme={null}
docker compose up -d
```

* `up`: start the service
* `-d`: run in the background

On first run the image is pulled automatically; depending on your network this may take a few minutes. When you see a message like `Container open-webui Started`, the service has started successfully.

Check the running status:

```bash theme={null}
docker compose ps
```

If the `STATUS` column shows `Up`, the service is running normally.

## Access and initialize your account

<Steps>
  <Step title="Open the web UI">
    Open a browser and go to `http://localhost:3000`.

    If deployed on a remote server, replace `localhost` with the server IP, e.g. `http://SERVER_IP:3000`.
  </Step>

  <Step title="Register the first account">
    On first launch you'll see the registration page. Fill in the form to register.

    <Warning>
      The first registered account automatically becomes the **Administrator** account, with user-management and system-settings permissions. Make sure to remember this account's email and password.
    </Warning>
  </Step>

  <Step title="Subsequent user approval">
    Any accounts registered afterwards start in the "Pending" state by default. An administrator must log in to the admin panel and manually approve them before they can use the UI.
  </Step>
</Steps>

## Connect to MixRoute

Open WebUI is only an interface on its own — you need to connect at least one model provider before you can chat. Open WebUI supports several model sources:

| Model source                     | Description                                                      |
| -------------------------------- | ---------------------------------------------------------------- |
| Ollama (local models)            | Run open-source models locally for free, no network calls needed |
| OpenAI                           | Use an OpenAI API Key to access GPT-family models                |
| Anthropic                        | Use an Anthropic API Key to access Claude-family models          |
| Other OpenAI-compatible services | e.g. relay platforms or self-hosted inference services           |

It's recommended to connect through **MixRoute** — one configuration gives you access to 200+ popular AI models, with adequate privacy protection while staying easy to use.

<Steps>
  <Step title="Open settings">
    After logging in to Open WebUI, click your avatar in the bottom-left → **Settings**.

    <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p1.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=8662d96843f01722dba99e6d51147235" alt="Openwebui P1" width="541" height="937" data-path="images/openwebui-p1.png" />
  </Step>

  <Step title="Open the connections panel">
    Go to **Admin Settings** → **Connections**.

    <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p2.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=39c472a163ec27c4c3bb039ee5f7c678" alt="Openwebui P2" width="2962" height="765" data-path="images/openwebui-p2.png" />
  </Step>

  <Step title="Enter MixRoute credentials">
    For the provider you want to connect, enter the **Base URL** and **API Key**, then save.

    * **Base URL**: `https://api.mixroute.ai/v1`
    * **API Key**: your MixRoute API Key (e.g. `sk-xxxxxxxx`)

          <img src="https://mintcdn.com/personal-a5418d9f/qwAKZlzOFRKXXp1S/images/openwebui-p3.png?fit=max&auto=format&n=qwAKZlzOFRKXXp1S&q=85&s=f474eeace78f0a309e6e1017080643f3" alt="Openwebui P3" width="1081" height="1243" data-path="images/openwebui-p3.png" />
  </Step>

  <Step title="Pick a model and start chatting">
    Back on the main screen, the newly connected model appears in the model picker. Select it to start chatting.

    <Tip>
      In our testing, the GPT family performs well in OpenWebUI — pairing it with a GPT model is recommended.
    </Tip>
  </Step>
</Steps>

## Common maintenance

### Stop the service

```bash theme={null}
docker compose stop
```

### Start the service again

```bash theme={null}
docker compose start
```

### View logs (for troubleshooting)

```bash theme={null}
docker compose logs -f
```

### Update to the latest version

```bash theme={null}
docker compose pull
docker compose up -d
```

<Note>
  `pull` fetches the latest image, and `up -d` recreates the container with the new image. Your data is safe — it lives in `volumes`, separate from the container itself.
</Note>

### Full uninstall

Stop and remove the container only (data is preserved, so you can recover with `up -d` at any time):

```bash theme={null}
docker compose down
```

Stop and remove the container **and delete all data** (chat history, accounts, etc. will be permanently lost — proceed with caution):

```bash theme={null}
docker compose down -v
```

## FAQ

<Accordion title="Can't open http://localhost:3000 in the browser?">
  * Confirm the container is running: `docker compose ps`, and check that `STATUS` is `Up`.
  * Confirm the port isn't already in use by another program. If it is, change the port in `docker-compose.yml` and run `docker compose up -d` again.
</Accordion>

<Accordion title="Forgot the admin password?">
  You can reset the password in Settings. If you can't log in at all, it needs to be handled at the database level — we recommend asking for help in the Discord/GitHub community first, and avoiding deleting the data volume directly (that would lose all data).
</Accordion>

<Accordion title="How do changes to docker-compose.yml take effect?">
  After saving the file, from the same directory run:

  ```bash theme={null}
  docker compose up -d
  ```

  Docker Compose detects the changes automatically and recreates the container.
</Accordion>

<Info>
  Once configured, every Open WebUI conversation and capability is powered by the MixRoute endpoint you bound in Settings — you get a robust and highly cost-effective cloud LLM service.
</Info>