From 5ff367f90074875f48fc410655cf5083c7902b6d Mon Sep 17 00:00:00 2001
From: Rob Ballantyne <rob@vast.ai>
Date: Thu, 18 Jun 2026 14:58:37 +0100
Subject: [PATCH] =?UTF-8?q?docs(agents):=20openwebui=20=E2=80=94=20tailor?=
 =?UTF-8?q?=20toward=20configuring=20the=20bundled-Ollama=20model=20(CON-1?=
 =?UTF-8?q?566)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This image is Open WebUI backed by a bundled Ollama (it serves models, not just a
front end). Expand the stub to focus on the thing an operator actually configures:
the served model — set OLLAMA_MODEL (pulled at boot; MODEL_NAME alias) or `ollama pull`
at runtime; models persist at ${WORKSPACE}/ollama/models, Open WebUI data at
${WORKSPACE}/data. Note open_webui waits on /tmp/.ollama_ready (server up + model
pulled) so the UI is intentionally down while a large model downloads, and that
Ollama is directly usable via its native /api + OpenAI /v1 (base_url+key from
/capabilities/endpoints).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../ROOT/etc/vast_agents/openwebui.md         | 33 ++++++++++++++++---
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/external/openwebui/ROOT/etc/vast_agents/openwebui.md b/external/openwebui/ROOT/etc/vast_agents/openwebui.md
index 71319ed3..ee91a3ef 100644
--- a/external/openwebui/ROOT/etc/vast_agents/openwebui.md
+++ b/external/openwebui/ROOT/etc/vast_agents/openwebui.md
@@ -1,7 +1,32 @@
 ## Open WebUI (this image)
 
-Runs **Open WebUI** (chat UI — service "Open WebUI") backed by a bundled
-**Ollama** server (service "Ollama API", OpenAI-compatible at `/v1`).
+**Open WebUI** (a browser chat UI) backed by a **bundled Ollama** server on the same instance —
+so this image both *serves* models and gives you a chat over them. base.md applies. Two
+services; get their externally callable URLs + token from the manifest (base.md §5, §9):
+```
+curl -s http://localhost:11111/capabilities/services    # both services, with direct_url + state
+curl -s http://localhost:11111/capabilities/endpoints   # Ollama's OpenAI /v1 base_url + key
+```
 
-- Manage models with the `ollama` CLI: `ollama list`, `ollama pull <model>`.
-- For the externally callable `base_url` + auth: `curl -s http://localhost:11111/capabilities/endpoints`.
+### The model is the thing you configure (start here)
+
+The bundled **Ollama** (supervisor service `ollama`, internal `:21434`) is the model backend;
+**Open WebUI** (service `open_webui`, internal `:17500`) is just the front end, already pointed at
+it (`OLLAMA_BASE_URL=http://localhost:21434`). Two ways to set the served model:
+
+- **At launch — `OLLAMA_MODEL`** (e.g. `llama3.2`, `qwen2.5:7b`): Ollama pulls it at boot and it
+  appears in Open WebUI automatically. (`MODEL_NAME` is an accepted alias.)
+- **At runtime — the `ollama` CLI:** `ollama pull <model>` / `ollama list` / `ollama rm <model>`;
+  a newly pulled model shows up in Open WebUI's model selector right away.
+
+Models persist at **`${WORKSPACE}/ollama/models`**, and Open WebUI's own data (accounts, chats) at
+**`${WORKSPACE}/data`** — both survive on the workspace.
+
+### Boot order & direct API access
+
+**Open WebUI waits for Ollama to be up *and* the configured model pulled** (`/tmp/.ollama_ready`)
+before it starts — so on first boot with a large `OLLAMA_MODEL` the chat UI is intentionally down
+while the model downloads. That's the pull, not a fault. Besides the chat UI, Ollama is directly
+usable for code: its native `/api` plus an **OpenAI-compatible `/v1`** (chat/completions,
+embeddings). Take the `base_url` + key from `/capabilities/endpoints` to point an external client
+(or another agent) straight at it.