lordraw/velox-ui repository overview

⁠velox-ui

A fast, self-hosted web interface for local and remote language models. Functional parity with Open WebUI, built for latency and a small footprint.

Local backends are the primary case, not a fallback. No API key is required, loading a model is reported as its own state rather than as a timeout, and a host that is switched off degrades to an offline badge instead of an error.

docker run -d \
  --name velox-ui \
  -p 8080:8080 \
  -v velox-data:/data \
  lordraw/velox-ui:latest

Open http://localhost:8080 and create the first account — it becomes the administrator. If Ollama is already running on the host, velox-ui finds it by itself.

⁠What it does

• Local backends first — Ollama and llama.cpp have native adapters (model management, load state, the full sampling parameter set). LM Studio, vLLM, TGI, TabbyAPI, KoboldCpp, LocalAI, Jan, llamafile, MLX LM and Text Generation WebUI work through an OpenAI-compatible adapter.
• Cloud backends — OpenAI, Groq, OpenRouter, Mistral, NVIDIA, Cloudflare Workers AI, Google Gemini and Anthropic. Credentials are encrypted at rest.
• Streaming chat with a branching message tree, virtual scrolling, markdown, and per-reply tokens/second.
• RAG — knowledge collections, document upload, background ingest/embed, and citations streamed into the reply.
• Tools — MCP servers (stdio, Streamable HTTP and legacy SSE, with transport detection) behind an approval gate, plus builtin tools a model can call mid-turn: the current date and time, and web search/browsing over a self-hosted SearXNG instance.
• Optional plugins — image generation and voice (transcription and speech) against any OpenAI-compatible endpoint. Disabled by default and never even imported when off.
• Multi-user — folders, tags, full-text search, custom model presets, an admin console, and API keys.
• Import from Open WebUI — velox import openwebui reconstructs the branching message tree, tags and folders from an Open WebUI chat export.
• Works on a phone — the interface is responsive, with a slide-over navigation drawer on small screens.

⁠Performance

These are CI gates, not marketing numbers — a regression fails the build.

No GPU, no Node.js and no PyTorch in the runtime image.

⁠Configuration

Everything has a working default; none of this is required.

Backends, plugins and MCP servers can also be added from the interface, where credentials are stored encrypted.

⁠With Ollama

services:
  velox-ui:
    image: lordraw/velox-ui:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - velox-data:/data
    environment:
      VELOX_PROVIDER_OLLAMA_HOSTS: http://ollama:11434

  ollama:
    image: ollama/ollama:latest
    restart: unless-stopped
    volumes:
      - ollama-models:/root/.ollama

volumes:
  velox-data:
  ollama-models:

⁠Image details

• Base: python:3.12-slim. Runs as a non-root velox user (uid 1000).
• Exposes 8080; VOLUME /data.
• HEALTHCHECK probes /ready (database reachable and migrations current), not /health (process alive) — so an instance mid-migration is not sent traffic.
• Entrypoint is the velox CLI: serve by default, also config check, migrate up, bench, import openwebui, import mcp-config.

Note on stdio MCP servers: the runtime image deliberately ships no Node.js, so MCP servers launched with npx cannot run inside this container. Run such a server in lordraw/velox-ui-mcp-gateway⁠ instead — it republishes a stdio server as Streamable HTTP, which velox-ui then adds as an ordinary http_sse server.

⁠Backups

Everything that must survive a container recreation is in the /data volume: the SQLite database, uploaded and generated files, and secret.key if you did not set VELOX_SECRET_KEY. Back it up as a unit — losing the key means re-entering every stored credential. SQLite runs in WAL mode, so use sqlite3 velox.db ".backup backup.db" rather than copying the file from under a running process.

⁠Links

• Source, issues and documentation: https://github.com/lordraw77/velox-ui⁠
• Configuration reference: docs/configuration.md⁠
• Deployment guide: docs/deployment.md⁠

Apache-2.0.