🦙 Ollama UI 🦙

Modern, reactive web interface for exploring Ollama models, browsing a scraped public catalog, pulling variants with streaming progress, and managing locally installed models.

What exactly is this? You’ll find a short, visual explanation in what_is/WHAT_IS.md (incl. Screenshots). 👈

Table of Contents

1. Features
2. Repository Layout
3. Prerequisites
4. Quick Start (UI Only)
5. Host Resolution Logic 5b. Access Control 5c. Backups
6. API Routes Overview
7. Frontend Architecture
8. Python Scraper
9. Development Workflow
10. Deployment
11. Troubleshooting
12. Roadmap / Ideas
13. Contributing
14. License
15. At A Glance
16. Disclaimer / Infos
17. Release Notes

1. Features ✨

• 🦙 Browse locally installed Ollama models (name, size, digest, modified date)
• ⏬ Pull / re-pull models (streamed NDJSON progress with derived percentage)
• 🗑️ Delete installed models
• 🌎 Searchable remote model catalog (slug, name & capabilities filtering)
• 🧩 Expandable variant lists with size info and one‑click pull
• 🔒 Global pull lock (avoids concurrent overwriting / race conditions)
• 🏠 Host configuration (cookie + header + env fallback resolution)
• 💬 Chat console with persisted sessions, personas, reasoning/tool-call traces, and a Compare mode to run two models side by side
• 🔌 Chat generation survives closing the tab — runs as a server-side job, reconnect from any tab/device to pick a live reply back up; a global "N generating" badge, toast and tab-title flash tell you when a background reply finishes
• 🛠️ Tool-calling for capable models — web_search via SearXNG, get_current_date, get_weather via Open-Meteo, calculator, create_reminder, create_recurring_task, list_scheduled_tasks, cancel_scheduled_task. Each individually toggleable under Settings → Tools, all on by default; a tool turned off there stays off everywhere — web chat, Telegram, scheduled tasks
• ⏰ Scheduled tasks — recurring prompts that run automatically at a set time/days, no tab needed; each run lands as a new session with the usual background-job notification. One-off reminders can also be set directly from chat ("remind me tomorrow at 9...") via create_reminder; a footer clock shows the server's own time since schedules run on it
• 📱 Telegram bridge (opt-in) — chat with the app from your phone through a Telegram bot, using the same tool-calling engine as the web UI, including sending photos to a vision model, voice messages (transcribed via a local whisper.cpp server), documents (PDF/text/code — attach one to summarize or ask about it), tap-to-cancel buttons on /tasks, and /info//tasks//new//help slash commands. Locked to a single allowlisted Telegram user id; set TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USER_ID and TELEGRAM_MODEL in .env.local to enable it (unset = bridge stays off), plus TELEGRAM_VISION_MODEL for photos and WHISPER_HOST for voice messages — the combined Docker image bundles whisper-server + a model automatically, so WHISPER_HOST there just defaults to it. Scheduled tasks and reminders push their result to Telegram too, not just into a new chat session, so they still reach you with no tab open — toggle this specifically under Settings → Telegram (on by default, independent of the bridge's own configuration). The polling loop backs off exponentially on a Telegram-side outage and auto-restarts if it ever crashes, with a "reconnected" notice once it recovers. The bridge's one persistent conversation is marked in the web UI's session list with a small paper-plane icon so it's not mistaken for an ordinary web chat. Replies are rendered as real Telegram formatting: long ones are split at Markdown block boundaries (never mid-entity, which used to make Telegram reject the message and drop the whole reply back to raw **asterisks**), tables become aligned monospace blocks — or one Key: value record per row when they're too wide for a phone — code blocks keep their language, and - [x] checkboxes stay visible
• 🔁 create_recurring_task, list_scheduled_tasks, cancel_scheduled_task tools — manage scheduled tasks and reminders entirely from chat (Telegram or web), no need to open the Scheduled page; in Telegram, /tasks also offers a tap-to-cancel button per task. Every schedule-related claim (created, cancelled, or listed) gets verified against the actual tool-call trace instead of trusting the model's own "done" claim — a fabricated list is replaced outright with the real data rather than just flagged, since it's misinformation about your own data, not just an unconfirmed action
• 💾 Automatic database backups — a snapshot is taken before the one-way messages migration (and the migration is refused if one can't be written), plus a daily one on startup, kept 7 deep in data/backups/. Taken with SQLite's VACUUM INTO, so they're consistent rather than a copy of a file being written to. Settings → Status shows when the last one happened
• 🔒 Optional password gate — set APP_PASSWORD and every page and API route requires a login (30-day session cookie, HMAC-signed, HttpOnly). Unset = off, so an existing localhost-only install is unaffected. Settings → Access shows which state you're in and warns when the instance is open
• 📎 Attach documents in the web chat — PDF, text, Markdown, CSV, JSON and source files are extracted to text server-side the moment you pick them (a file that can't be read fails right there, not at send time) and go into the message as readable context. Same extraction the Telegram bridge already used
• 🌿 Branching conversations — Regenerate and editing a message no longer delete what they replace: the new version is stored beside the old one and a ‹ 2 / 3 › switcher on the message moves between them, restoring that branch's whole continuation
• 🔌 MCP client — connect Model Context Protocol servers (stdio or HTTP) under Settings → MCP Servers and their tools appear alongside the built-in ones in every chat, in Telegram and in scheduled tasks, with no code change. The list shows what each server actually advertises right now, so a misconfiguration is visible immediately
• 📏 Global default context window — Settings → Generation sets the num_ctx requested from Ollama, stored server-side so it reaches the web chat, the Telegram bridge and scheduled tasks alike (the per-model pill in the chat header is browser-local and never reached the latter two). Worth raising as soon as an MCP server is connected: a large tool catalog is easily tens of thousands of tokens of definitions, and a window too small to hold it is silently truncated, leaving the model a mangled tool list
• 🧪 Evaluations — save the prompts you actually use, run them across several models sequentially, and score the answers side by side with tokens/second shown alongside. Benchmarks tell you which model is fastest; this tells you which is better at your work
• 🗄️ Per-message storage with SQLite FTS5 search — messages live in their own table instead of one JSON blob per session, attachments are stored on disk and content-addressed, and search runs against a real full-text index rather than scanning every conversation in memory
• 🩺 Settings → Status panel — live reachability check for Ollama, the Whisper voice server and the Telegram bridge in one place, including a real Telegram getMe call so a revoked/rotated bot token (which otherwise fails silently forever) shows up immediately instead of only as "nothing happens" when you message the bot
• 📈 Model benchmark history — every real chat logs its speed automatically, plus an on-demand fixed-prompt benchmark across all installed models, with a trend chart
• 🗜️ Context compaction — summarize older chat history into a dense context note via the model itself (with undo)
• 📏 Honest context-window badge (real runtime num_ctx from /api/ps, not the model's theoretical max) + per-model context slider up to the model's maximum
• 🖥️ Running Models page — live ollama ps view with CPU/GPU memory split, context window, auto-unload countdown and one-click unload, plus per-GPU VRAM on multi-card machines (Ollama's API only ever reports one total across all cards — see Per-GPU readout)
• 🎨 Theme-adaptive glass UI — 5 accent themes driving an ambient aurora background, glass cards, charts and scrollbars
• 📊 Dashboard with model stats and accessible, colorblind-safe charts
• 🔔 Toast notifications (success / error / info)
• ⚡️ Lightweight state management with Zustand & React Query caching, with per-message memoization and deferred markdown parsing so streaming stays smooth in long conversations
• 🐍 Python scraper (separate directory) to periodically refresh the catalog JSON

Removed in 0.1.20260913-3: the persistent memory. It saved facts about you during a chat and put them back into later prompts; it could not be made reliable enough to be worth the surprises it produced, so it is gone along with its tables, which are dropped the first time this version opens an older database. Chats, search, scheduled tasks and the Telegram bridge are untouched.

2. Repository Layout 🗂️

ollama-ui/        # Next.js (App Router) application
	src/app/        # Pages & API routes
	src/proxy.ts    # Password gate (Next 16's renamed middleware)
	src/lib/        # Server logic: generation, tools, MCP, Telegram, ...
	src/lib/db/     # SQLite: connection.ts owns schema+migrations,
	                #   one module per entity, re-exported by src/lib/db.ts
	src/hooks/      # Client hooks (chat column, attachments, voice input)
	src/store/      # Zustand stores (pull logs, toast, etc.)
	models.json     # Scraped catalog file (copied/updated manually)
	data/           # SQLite database, uploads and backups (gitignored)
Scraper/          # Python async scraper producing models.json

data/ can be moved with OLLAMA_UI_DATA_DIR (useful for a Docker volume, and what the tests use to stay away from the real database).

You run / build only inside ollama-ui/. The Python scraper is optional and only needed when you want to regenerate the catalog file.

3. Prerequisites 🛠️

• Node.js 22.5+ (required for the built-in node:sqlite module used for persistence)
• pnpm (preferred) OR npm / yarn / bun
• Python 3.11+ (only if you run the scraper)
• A reachable Ollama server (local or remote) exposing its HTTP API (/api/pull, /api/tags, etc.)

Optional, per feature — each is unnecessary until you use the feature it backs:

4. Quick Start (UI Only) 🚦

cd ollama-ui
pnpm install          # or npm install / yarn
pnpm dev              # start dev server on http://localhost:3000

Open http://localhost:3000

If you already have an Ollama instance running locally at the default fallback (see below) the Installed Models list should populate. Otherwise set the host in the UI or via environment.

Nothing works until a host is added and activated — do that first, under Settings → Ollama Host. Settings → Status will tell you whether it is actually reachable.

Upgrading an existing install

Just start it. Chat messages move out of the per-session JSON blob into their own table on first start, and inline base64 images move to data/uploads/ — automatically, once, reclaiming the freed space (VACUUM).

A snapshot of the database is taken immediately before that migration, into data/backups/, and if one cannot be written the migration is refused rather than run unprotected — see Backups. So the old advice to copy app.db by hand is no longer necessary; it does no harm if you prefer to anyway.

Two things are worth setting while you're there: APP_PASSWORD (see §5b) if the instance is reachable from anywhere but localhost, and pdftotext (see §3) if you want to attach PDFs.

5. Host Resolution Logic 🌐

The active host from the hosts table is the only source. Add and activate it under Settings → Ollama Host (the green dot marks the active one); it's stored server-side, so it's the same host for every browser and for the Telegram bridge and scheduler, which have no request to read a header from.

Validation enforces a full http:// or https:// URL.

An x-ollama-host request header used to override this. Nothing in the app ever sent one — the host is chosen in the Host Manager — and all it actually did was let any request that reached the server point it at an arbitrary URL and read the response back through the chat and model routes. It was removed along with the unused /api/config/ollama-host route and its cookie.

Environment

OLLAMA_HOST / NEXT_PUBLIC_OLLAMA_HOST are only read by getDefaultOllamaHost() — they seed a suggestion, they don't override the configured host.

5b. Access Control 🔒

By default the app is unauthenticated: anyone who can reach the port can read your chats, pull and delete models, and drive your Ollama host. That's fine bound to localhost, and not fine the moment it's reachable from anywhere else — which is the normal case for the Docker image and the whole point of the Telegram bridge.

Set a password to turn on the gate:

# ollama-ui/.env.local  (or the container environment)
APP_PASSWORD=something-long-and-not-guessable

With it set, src/proxy.ts requires a valid session for every page and every API route; a browser is redirected to /login, an API call gets a 401. Sessions last 30 days and live in an HMAC-signed, HttpOnly cookie — the token is never readable from JavaScript. Login attempts are rate-limited per IP. Leave APP_PASSWORD unset and nothing changes from before.

AUTH_SECRET is optional: the signing key is derived from the password by default, so changing the password signs everyone out. Set AUTH_SECRET explicitly if you'd rather sessions survive a password change.

Settings → Access shows which state the instance is in, and offers a sign-out.

⚠️ Build requirement: the password gate lives in src/proxy.ts (Next 16's renamed middleware). Turbopack compiles it and even lists it in the build summary, but does not wire it into an output: standalone server — every request then bypasses it and the gate is silently a no-op. pnpm build therefore pins next build --webpack. Don't run next build directly without that flag.

5c. Backups 💾

The database is snapshotted automatically into data/backups/. Two triggers, for two different problems:

Snapshots are taken with SQLite's VACUUM INTO, not a file copy: a copy of a live database can miss whatever is still in the write-ahead log, or catch a write mid-flight. The result is a consistent, already-compact .db file.

The newest 7 are kept; older ones are pruned. The restart-in-a-crash-loop case is handled by the once-a-day rule, so the retained set is never seven snapshots from the same minute.

Settings → Status shows the snapshot count, when the newest was taken and where they live — an automatic backup nobody can see is one nobody trusts, and the failure that matters (a read-only volume, so nothing is ever written) is invisible by definition until you need one.

Restoring

A snapshot is an ordinary SQLite database. Stop the app, then:

cd ollama-ui/data
cp app.db app.db.broken            # keep the bad one, just in case
cp backups/app-<timestamp>-<reason>.db app.db
rm -f app.db-wal app.db-shm        # stale journal from the replaced database

Start the app again. Note that data/uploads/ is not in the snapshot — attachments are content-addressed files that are only ever added, never rewritten, so an older database paired with the current uploads directory is consistent. Back that directory up separately if you want the images too.

Settings

6. API Routes Overview 📡

Base path: /api

Every route above is behind the password gate when APP_PASSWORD is set — see Access Control.

Pull Streaming Contract

/api/models/pull emits newline‑delimited JSON objects. Each line may contain:

{ status, digest?, total?, completed?, percentage? }

If total & completed exist but percentage is missing, the proxy computes and injects it.

Client logic (React) merges these events into a progress bar; a final { done: true } is appended.

7. Frontend Architecture 🏗️

• Next.js App Router: mostly the Node runtime — anything touching the database (which is most of it) cannot run on Edge, since node:sqlite isn't available there. src/proxy.ts gates every request when a password is configured.
• React Query: Data caching & stale control for models and catalog.
• Zustand Stores: Lightweight stores for chat messages, sessions, pull logs & toast queue.
• Hooks: use-column-chat (one chat column's generation lifecycle, including reconnecting to a job started in another tab), use-attachments (images + documents in the composer), use-voice-input (record → transcribe → fill the composer).
• Streaming: Manual ReadableStream consumption with incremental parsing of NDJSON lines (src/lib/chat-stream.ts).
• Styling: Tailwind CSS (v4) + theme-adaptive glass design system (accent-driven aurora background, glass cards, scrollbars) with 5 color themes.
• Components: Reusable <Button /> with variants (primary, outline, danger, etc.).

State highlights:

• anyPullActive prevents concurrent pulls.
• expandedVariants[slug] toggles full variant list per model.
• Pull progress has exactly one writer, the stream loop, and updates once per network chunk rather than once per line.

Where a chat message actually lives

Worth knowing before changing anything in this area, because the ownership moved and the old shape is the intuitive-but-wrong one:

1. The browser POSTs to /api/chat with the user message and an empty assistant placeholder.
2. The server writes both to the database before contacting Ollama, then runs the generation as a detached job and writes the final content itself. That is what lets a reply survive closing the tab.
3. The browser therefore does not PATCH the conversation back. A full-history write means "this is the conversation now" and would delete every branch the tab cannot see — it is used only where that is genuinely intended (compaction, undo, clearing).
4. History is a tree, not a list: each message has a parent_id, and the session points at the active leaf per column. A conversation with no branches is just a tree where every node has one child.

8. Python Scraper 🐍

Location: Scraper/

Purpose: Crawl public model pages, produce models.json with:

• scraped_at
• For each model: slug, name, pulls, pulls_text, capabilities[], blurb, description, tags_count, variants[] (each variant: tag, size, size_text, context tokens, input tokens)

Run

cd Scraper
python -m venv .venv && source .venv/bin/activate   # one time
pip install -r requirements.txt
python ollama_scraper.py           # full scrape
python ollama_scraper.py --limit 50  # first 50 models for quick test

Output: out/models.json. Copy or move that file into ollama-ui/models.json (overwrite existing) so the catalog endpoint serves it.

Schedule (Optional)

Use cron or a CI workflow to periodically update the file. Example cron entry (daily at 02:30):

30 2 * * * /usr/bin/bash -lc 'cd /path/to/repo/Scraper && source .venv/bin/activate && python ollama_scraper.py && cp out/models.json ../ollama-ui/models.json'

9. Development Workflow 🧑‍💻

Common scripts:

pnpm dev        # start dev server (webpack, not Turbopack — see below)
pnpm build      # production build (next build --webpack)
pnpm start      # run built app
pnpm lint       # eslint (uses flat config)
pnpm typecheck  # tsc --noEmit
pnpm test       # vitest run
pnpm test:watch # vitest in watch mode
pnpm format     # prettier write

Why webpack, not Turbopack. Two independent reasons, both of which fail quietly rather than loudly:

• next dev --turbopack cannot load node:sqlite at all (see the note at the top of src/lib/db/connection.ts).
• Turbopack does not wire src/proxy.ts into an output: standalone build, so the password gate silently stops running. pnpm build pins --webpack for exactly this reason.

Tests

pnpm test runs the unit suite (Vitest, node environment, no jsdom) — 391 tests over the pure logic and the database layer. The database tests run against a real SQLite file in a temp directory (OLLAMA_UI_DATA_DIR), never data/, because what's worth testing there — the FTS triggers, the branch walk, attachment content-addressing — is SQLite's behaviour, not something a mock would exercise. The MCP tests spawn an actual MCP server process.

Lint, typecheck and tests all run in CI on every push and pull request.

After updating models.json, no restart is strictly required (catalog route reads file each request) but browser cache is bypassed anyway (cache: 'no-store'). Just refresh.

10. Deployment 🚀

You can deploy like any standard Next.js app (Vercel, Docker, etc.). Requirements:

• Ensure models.json is present in the build output (it is read at runtime, so keep it in project root of the app).
• Provide OLLAMA_HOST environment variable or rely on user-set cookie.
• If deploying serverless, note: the catalog route uses Node runtime (filesystem). Ensure hosting platform supports reading that static file at runtime.

Docker (Combined Ollama + UI)

This repository now includes a multi‑stage Dockerfile at repo root that:

1. Builds the Next.js app (standalone) with Node 20.
2. Compiles whisper.cpp's whisper-server from source in its own stage (speech-to-text for Telegram voice messages — Ollama has no audio-input support of its own) and downloads a multilingual model (~465MB; override with --build-arg WHISPER_MODEL_URL=... for a smaller/larger one, e.g. ggml-base.bin or ggml-medium.bin — avoid the .en-suffixed variants unless you only ever speak English to it).
3. Uses the official ollama/ollama:latest image as the final base.
4. Copies the standalone server + static assets + the compiled whisper-server + its model, plus the compiled instrumentation.js (and the server chunk(s) it depends on) explicitly — Next's standalone output tracing doesn't include these on its own, which silently prevented the scheduler and Telegram bridge from ever starting in the built image (no error anywhere — confirmed live, see instrumentation.ts's own doc comment and the Dockerfile's comment at this COPY step for the full story).
5. Starts Ollama (ollama serve), whisper-server (bound to 127.0.0.1 only — internal, never exposed) and the UI (node server.js) via start.sh.
6. Also installs ffmpeg (audio conversion for voice messages) and poppler-utils (pdftotext, for reading PDF documents sent to the Telegram bridge) via apt-get in the final image.

Build & run:

docker build -t ollama-ui:latest .
docker run --rm -p 11434:11434 -p 3000:3000 ollama-ui:latest

Then open http://localhost:3000 (UI) and Ollama API at http://localhost:11434.

Docker Volumes: Persist Models & Database

To persist Ollama models and the UI database outside the container, mount host directories as volumes:

docker run --rm -p 11434:11434 -p 3000:3000 \
	-v /path/to/ollama-models:/root/.ollama \
	-v /path/to/ollama-ui-data:/app/data \
	ollama-ui:latest

• /root/.ollama: stores all pulled Ollama models (can be reused across containers/updates)
• /app/data: stores the SQLite database (app.db) for UI state (profiles, logs, etc.)

Docker Compose Example:

services:
	ollama-ui:
		image: ollama-ui:latest
		build: .
		ports:
			- "11434:11434"
			- "3000:3000"
		volumes:
			- /path/to/ollama-models:/root/.ollama
			- /path/to/ollama-ui-data:/app/data
volumes: {}

Override default host the UI uses:

docker run --rm -e OLLAMA_HOST=http://localhost:11434 -p 11434:11434 -p 3000:3000 ollama-ui:latest

Telegram Bridge & Voice Transcription (Docker / Homeserver)

.env.local (used elsewhere in this doc) only applies to pnpm dev — it's never baked into the image or read inside a container. In Docker, set the same variable names as regular container environment variables instead:

docker run --rm -p 11434:11434 -p 3000:3000 \
	-v /path/to/ollama-models:/root/.ollama \
	-v /path/to/ollama-ui-data:/app/data \
	-e TELEGRAM_BOT_TOKEN=your-bot-token \
	-e TELEGRAM_ALLOWED_USER_ID=your-telegram-user-id \
	-e TELEGRAM_MODEL=llama3.1:8b \
	ollama-ui:latest

Same idea in Docker Compose — add them under environment: (or env_file: pointing at a local file kept out of version control, so the token isn't sitting in docker-compose.yml itself):

services:
	ollama-ui:
		image: ollama-ui:latest
		environment:
			- TELEGRAM_BOT_TOKEN=your-bot-token
			- TELEGRAM_ALLOWED_USER_ID=your-telegram-user-id
			- TELEGRAM_MODEL=llama3.1:8b

Password protection in Docker: set APP_PASSWORD as a container environment variable exactly like OLLAMA_HOST. This matters more here than for a local pnpm dev — a container is usually reachable from the rest of the network, and without it every chat and model operation is open to anyone who can reach the port. Optionally add AUTH_SECRET to keep sessions valid across a password change, and OLLAMA_UI_DATA_DIR to point the database and uploads at a mounted volume.

Backups in Docker: snapshots land in data/backups/ inside the container, so they only survive a container rebuild if data/ is a mounted volume — which it should be anyway, since the database lives there. OLLAMA_UI_BACKUP_KEEP and OLLAMA_UI_BACKUP_DISABLED are ordinary environment variables like the rest.

On Homeserver: edit the container → Add another Path, Port, Variable → type Variable, with TELEGRAM_BOT_TOKEN etc. as Key and the value as Value — no file involved, same as any other env var on that screen (this is also how OLLAMA_HOST gets set on Homeserver).

Optional additions, same mechanism: TELEGRAM_VISION_MODEL (photos, only if TELEGRAM_MODEL itself doesn't already report vision support) and TELEGRAM_MODEL's tool-calling requirement carries over unchanged. Voice messages need nothing extra in the combined image — WHISPER_HOST already defaults to the bundled whisper-server (http://localhost:8790, see the Dockerfile section above); only set it yourself to point at a different/external Whisper server instead.

The bot token is a credential like any other — treat it the same way you'd treat OLLAMA_HOST credentials or a database password: not in docker-compose.yml committed to a repo, not pasted into shell history you'll publish, etc. If it ever leaks, revoke/regenerate it via @BotFather (/revoke or /token) — that's cheap and immediate.

Prebuilt Images (Combined Ollama + UI)

You can use prebuilt images from GitHub Container Registry (GHCR):

• ghcr.io/chrizzo84/ollamaui

Pull and run:

docker pull ghcr.io/chrizzo84/ollamaui:latest
docker run --rm -p 11434:11434 -p 3000:3000 ghcr.io/chrizzo84/ollamaui:latest

If you want to disable the bundled Ollama server and point only to an external one, you can adapt start.sh to skip ollama serve and only run node server.js.

GPU Passthrough

Ollama can leverage GPUs inside the same container. Usage differs by platform:

NVIDIA (Linux) Prerequisites: Install the NVIDIA Container Toolkit on the host.

docker run --rm \
	--gpus=all \
	-p 11434:11434 -p 3000:3000 \
	-v ollama_models:/root/.ollama \
	ollama-ui:latest

Limit GPU visibility (e.g. only GPU 0):

docker run --rm --gpus 'device=0' -p 11434:11434 -p 3000:3000 ollama-ui:latest

Docker Compose Example (docker-compose.yml at repo root):

services:
	ollama-ui:
		image: ollama-ui:latest
		build: .
		ports:
			- "11434:11434"
			- "3000:3000"
		volumes:
			- ollama_models:/root/.ollama
		deploy:
			resources:
				reservations:
					devices:
						- capabilities: [gpu]
		environment:
			- OLLAMA_HOST=http://localhost:11434
volumes:
	ollama_models:

Apple Silicon (Metal) Metal acceleration is available natively when running Ollama directly on macOS. Docker GPU passthrough for Metal is not currently supported in the same way; prefer running Ollama on the host and pointing the container UI to it:

docker run --rm -e OLLAMA_HOST=http://host.docker.internal:11434 -p 3000:3000 ollama-ui:latest

AMD ROCm If your base image / host supports ROCm and ollama/ollama adds ROCm builds in future, you would expose the devices similarly (e.g. --device=/dev/dri); consult upstream Ollama documentation.

Verify GPU usage after starting:

docker exec -it <container> ollama ps

Or on host: nvidia-smi (NVIDIA) while a model runs.

Per-GPU readout

The Running Models page shows a CPU/GPU split per model. That split comes from Ollama's /api/ps, which reports exactly two numbers per model: size (total resident footprint) and size_vram. size_vram is the sum over every card the model was placed on — Ollama adds up one GPU buffer at a time and keeps a per-device map internally (vramByDevice in its llm/llama_server.go), but only the total ever leaves the process. No HTTP route exposes the breakdown, and ollama ps doesn't print it either. So the split is already correct on a multi-GPU box; what it cannot tell you is which card holds what — and "one card at 95%, the other idle" looks exactly like an even spread.

For that, the page asks the machine it runs on directly (/api/gpu) using whatever is installed — nvidia-smi, rocm-smi, or Apple Silicon's unified memory — and lists every card with its own used/total bar and utilization. Those numbers are the whole device, not just Ollama's share, which is the useful figure when deciding whether the next model still fits.

Because this reads local hardware, it is only shown when that hardware is provably the hardware Ollama is using:

With a remote Ollama host the panel is replaced by a line saying so, rather than by nothing: a missing panel reads like a broken feature, and "the API only reports a total" is the actual answer. In Docker, the card is only visible inside the container if the GPU was passed in (see above) — without that, nvidia-smi isn't there and the panel stays absent.

11. Troubleshooting 🕵️‍♂️

12. Roadmap / Ideas 🗺️

• Persist catalog search & expansion state (localStorage)
• Per-variant progress indicator (when layers known)
• Multi-pull queue (sequential)
• Download speed & ETA estimation
• Keyboard shortcuts (focus search, abort pull)
• RAG over a local folder — embeddings via Ollama's /api/embed, searched when a question calls for it
• Modelfile editor — build a model from a base + system prompt + parameters, so a persona can become a real Ollama model usable outside this app
• MCP: resources and prompts (only tools are implemented today)

13. Contributing 🤝

1. Fork & clone
2. Create a branch: feat/my-feature
3. Run pnpm dev and implement
4. Ensure lint passes: pnpm lint
5. Open PR with description & screenshots

14. License 📜

Distributed under the MIT License. See the LICENSE file for full text.

15. At A Glance 👀

🚀 Happy hacking! Pull, explore, iterate. 🦙

16. Disclaimer / Infos

# The winning approach: Manual node-gyp compilation at runtime
RUN cd /app/node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3 && \
    npm install node-gyp -g && \
    node-gyp configure --module_name=better_sqlite3 --module_path=./build && \
    node-gyp build

17. Release Notes

See the latest changes and release notes here