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

# Install Open WebUI with Docker

> Write the env file, start Open WebUI in Docker, create the first admin, check the gateway path and send the first chat.

This page runs Open WebUI in one Docker container, points it at the gateway with two environment variables, and checks the path in order: the models list, a granted call, an ungranted call, then a chat in the browser.

You need the token from [Gateway access](https://www.truefoundry.com/docs/ai-gateway/open-webui/gateway-access.md#copy-the-token) and Docker on the host.

## Write the env file

Open WebUI reads its settings from the environment. Keep the token in a file that only you can read, and never put it on the command line.

Create the env file without echoing the token. Paste the token at the prompt:

```bash theme={"dark"}
umask 077
read -rs TFY_TOKEN && echo
printf 'OPENAI_API_BASE_URL=https://<your-tenant-host>/api/llm/v1\nOPENAI_API_KEY=%s\n' "$TFY_TOKEN" > openwebui.env
unset TFY_TOKEN
```

Replace `<your-tenant-host>` with your tenant host, for example `app.example.com`. The base URL ends in `/api/llm/v1`.

Check that both keys are present, without printing the token:

```bash theme={"dark"}
cut -d= -f1 openwebui.env
```

Expected output:

```text theme={"dark"}
OPENAI_API_BASE_URL
OPENAI_API_KEY
```

> [!WARNING]
>
> `openwebui.env` holds a live token. Keep it out of version control and out of shared folders. Delete it when you remove the install.

## Start the container

Create a named volume for Open WebUI's data, then start the container from the pinned image. The volume keeps accounts, chats and settings across restarts and upgrades.

```bash theme={"dark"}
docker volume create open-webui-data
docker run -d --name open-webui \
  -p 3000:8080 \
  --env-file openwebui.env \
  -v open-webui-data:/app/backend/data \
  ghcr.io/open-webui/open-webui:v0.13.4
```

Expected output: a 64-character container ID, then the container shows `health: starting` for about a minute.

```bash theme={"dark"}
docker ps --filter name=open-webui --format '{{.Names}} {{.Status}}'
```

Wait until the status reads `(healthy)`, then check the health endpoint:

```bash theme={"dark"}
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/health
```

Expected output:

```text theme={"dark"}
200
```

If the health check stays at `000`, the container has not finished starting. Read its log with `docker logs open-webui`.

## Create the first admin

Open `http://localhost:3000` in a browser. The first account you create becomes the admin. Enter a name, an email and a password in the sign-up form, then submit it.

![Open WebUI sign-in page with Email and Password fields and a Sign in button](https://mintcdn.com/truefoundry/u9A7Ha_L6d5kXr6t/images/ai-gateway/openwebui-ui-login.jpg?fit=max\&auto=format\&n=u9A7Ha_L6d5kXr6t\&q=85\&s=75fab2b65beeeeb5fa90f70047b9fb6d)

The sign-in page. The first account created on a new install becomes the admin.

Keep the admin password in your password manager. Open WebUI does not show it again.

> [!NOTE]
>
> After the first admin exists, turn off public sign-up. Add `ENABLE_SIGNUP=false` to `openwebui.env`, then recreate the container with `docker rm -f open-webui` and the same `docker run` command. The volume keeps the accounts.

## Check the gateway path

Run the checks in order. Each one uses the same key the container uses, loaded from the env file.

Load the env file into your shell for these checks only:

```bash theme={"dark"}
set -a; . ./openwebui.env; set +a
```

### 1. List the models

```bash theme={"dark"}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  "$OPENAI_API_BASE_URL/models"
```

Expected output:

```text theme={"dark"}
200
```

The list is the set of models the gateway serves to the tenant, and it can include models this token has no grant on. A listed model can still return `403`, as step 3 shows. To see the IDs, run the same call without `-o /dev/null`. The granted model appears as `azure-openai-main/o4-mini`, with the provider prefix.

### 2. Call a granted model

```bash theme={"dark"}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"azure-openai-main/o4-mini","messages":[{"role":"user","content":"ping"}],"max_completion_tokens":20}' \
  "$OPENAI_API_BASE_URL/chat/completions"
```

Expected output:

```text theme={"dark"}
200
```

### 3. Call a model without a grant

```bash theme={"dark"}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai-main/gpt-4o-mini","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \
  "$OPENAI_API_BASE_URL/chat/completions"
```

Expected output:

```text theme={"dark"}
403
```

The response body names the account and the model, for example `User openwebui-gw is not authorized to access model openai-main/gpt-4o-mini or model does not exist`. A `403` here is the grant working. It is not an error in the install.

### 4. Call a bare model name

```bash theme={"dark"}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"o4-mini","messages":[{"role":"user","content":"ping"}],"max_completion_tokens":20}' \
  "$OPENAI_API_BASE_URL/chat/completions"
```

Expected output:

```text theme={"dark"}
403
```

Use the provider-qualified ID in Open WebUI, not the bare name.

Clear the variables when you are done:

```bash theme={"dark"}
unset OPENAI_API_KEY OPENAI_API_BASE_URL
```

## Send the first chat

1. Open `http://localhost:3000` and sign in as the admin.
2. Open a new chat.
3. In the model picker at the top, choose **azure-openai-main/o4-mini**. If the model does not appear, check the grant in [Gateway access](https://www.truefoundry.com/docs/ai-gateway/open-webui/gateway-access.md#grant-a-model).
4. Send a short prompt, for example `Reply with the word: ready`.

The reply comes back from the provider through the gateway.

If the chat returns an error, use the table in [Troubleshoot](https://www.truefoundry.com/docs/ai-gateway/open-webui/operate.md#troubleshoot).

## Next steps

* Rotate, revoke or upgrade the install: [Operate and troubleshoot](https://www.truefoundry.com/docs/ai-gateway/open-webui/operate.md).
* Permissions for other models: add a grant on the same account. See [Gateway access](https://www.truefoundry.com/docs/ai-gateway/open-webui/gateway-access.md#grant-a-model).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.