Set up Open WebUI on your Spark
By the end of this page you have Open WebUI in front of the model on your DGX Spark: a ChatGPT-style interface with accounts, chat history, document upload and model switching, so colleagues can use the model without curl. It covers install, connecting the model, locking down signups, documents, HTTPS and backups.
You need:
- A running GPUwerk instance with an OpenAI-compatible endpoint: a console model preset, or your own vLLM server.
- For a console preset reached from outside the instance, an API key with the
inferencescope, created in the console. - No SSH key to deploy. GPUwerk configures the machine, and the console's browser terminal works without one for the install commands. To open the web interface through an SSH tunnel you do need your own SSH key, because the tunnel runs from your own SSH client.
1. Install it
Open WebUI does no GPU work. It is a frontend that talks to an inference endpoint over HTTP, so it runs next to whatever serves your model.
On a GPUwerk instance, use the pip install. An instance is itself a Docker container with no Docker daemon inside (see the tenant environment), so the docker run commands on this page work on a DGX Spark or server of your own, not inside the instance. On the instance, install with pip install open-webui into a virtual environment under /workspace, set DATA_DIR=/workspace/open-webui, and start it with open-webui serve --host 127.0.0.1 --port 8080. The environment variables below work the same way.
docker run -d \ --name open-webui \ --network host \ -v /workspace/open-webui:/app/backend/data \ --restart unless-stopped \ ghcr.io/open-webui/open-webui:main
Two choices in there are deliberate. --network host lets the container reach your vLLM server at localhost:8000 with no bridge networking to configure. The data directory is a bind mount under /workspace rather than a named Docker volume, so it is easy to find and back up.
With host networking the port is 8080, not the 3000 in the upstream quick start (3000 is the host side of a -p 3000:8080 mapping). Open http://localhost:8080 through an SSH tunnel. You should see the sign-up screen.
Without Docker, pip install open-webui then open-webui serve works and needs Python 3.11. Where Docker is available, the container is easier to keep clean, and it is what the project ships first.
2. Connect it to your model
Open WebUI speaks two protocols: the OpenAI-compatible API, and Ollama's native one. For a vLLM backend you want the first.
- Sign in and open Settings, Admin Settings, Connections.
- Add an OpenAI-compatible connection. For your own vLLM server on the same machine, the base URL is
http://localhost:8000/v1with any non-empty API key; vLLM checks the key only if you started it with--api-key. - For a GPUwerk console preset, use
http://localhost:8888/v1when Open WebUI runs inside the same instance; that local path needs no key. If Open WebUI runs on another server, use the preset's HTTPS endpoint from the console plus/v1(it looks likehttps://app-<instance-id>.gpuwerk.com/v1) and an API key with theinferencescope from the account that owns the instance. Keep that key in the Open WebUI server configuration only. - Save. The model picker should now list your model, for example
qwen3-coder-30b.
To set the connection at start-up instead, so a fresh deployment comes up configured, pass it as environment variables:
docker run -d \ --name open-webui \ --network host \ -e OPENAI_API_BASE_URLS="http://localhost:8000/v1" \ -e OPENAI_API_KEYS="sk-local" \ -e ENABLE_OLLAMA_API=False \ -v /workspace/open-webui:/app/backend/data \ --restart unless-stopped \ ghcr.io/open-webui/open-webui:main
Note the plural. OPENAI_API_BASE_URLS takes a semicolon-separated list, and Open WebUI balances across the entries, so one interface can front two Sparks. ENABLE_OLLAMA_API=False stops it probing for an Ollama server you are not running, which otherwise causes a slow page load and a red error toast.
Open WebUI fills the model picker by calling /v1/models at start-up. If the picker is empty, that call is failing. Check the endpoint from where Open WebUI runs, for example docker exec open-webui curl -s http://localhost:8000/v1/models, before you change anything in the UI. All variables are in the Open WebUI environment configuration reference.
Pointing Open WebUI at LiteLLM instead of straight at vLLM gives you per-user API keys, spend tracking and fallback routing, while Open WebUI keeps seeing one ordinary OpenAI endpoint. That is the setup I would run for more than a handful of people.
3. Control who gets in
The first account created becomes the admin. That is a race, so create yours right after you start Open WebUI, before anyone else can reach the port, then turn off signups. On a GPUwerk instance, anything listening on 0.0.0.0 is reachable on the instance's public IPv4 address, which is one more reason to bind Open WebUI to 127.0.0.1 and use the tunnel.
# after your admin account exists
-e ENABLE_SIGNUP=False
If colleagues should self-register but wait for approval, leave signup on. New accounts get the pending role by default and can do nothing until an admin approves them in the users panel.
One variable needs a warning. WEBUI_AUTH=False turns off authentication and makes the whole install one shared session with no login. That is fine on a laptop. On anything another person can reach, every visitor reads everyone's chat history.
If you ever run more than one replica behind a load balancer, set WEBUI_SECRET_KEY explicitly and identically on all of them. Left unset, each instance generates its own key and saves it to .webui_secret_key in the data directory, so a token issued by one replica is rejected by the next and users get logged out at random. Generate one with openssl rand -base64 32.
4. Add your own documents
Most people install Open WebUI to ask questions about their own files. Documents you upload through the workspace panel are chunked, embedded and stored locally, then retrieved and added to the prompt at query time. Attach a file to one chat with the paperclip, or add it to a knowledge collection and reference the collection with # in the message box to use it across conversations.
Two things matter before you load a large corpus. The embedding model also runs locally, at a small extra memory cost, and the default is tuned for size rather than quality: switching to a stronger multilingual embedder in the admin settings is usually the biggest retrieval improvement you can make. Retrieval quality also depends more on how documents are split than on which model answers, so a PDF that is mostly tables will retrieve poorly with any model.
The documents, embeddings and prompts all stay in the data directory where Open WebUI runs. Use public or synthetic documents for an evaluation unless you have agreed a path for customer data.
5. Put it behind HTTPS
For your own use, the SSH tunnel is enough and needs no certificates. A team needs a real URL.
- Do not put Open WebUI behind the console preset's HTTPS endpoint. That hostname serves the authenticated model API, and a browser cannot send the inference bearer key it requires.
- Run Open WebUI on a web server of your own and connect its backend to the preset's HTTPS endpoint with an inference-scope key, as in step 2.
- Keep Open WebUI's own login enabled.
- Put Caddy in front for HTTPS:
# /etc/caddy/Caddyfile
chat.yourcompany.com {
reverse_proxy localhost:8080
}
That is the whole config. Caddy gets and renews the certificate from Let's Encrypt, provided the DNS record points at the machine and ports 80 and 443 are reachable. Open https://chat.yourcompany.com and you should see the Open WebUI login.
6. Back up the one directory that matters
Everything Open WebUI knows lives in its data directory (/app/backend/data in the container, /workspace/open-webui on the host here): the SQLite database with accounts and chat history, the vector store, uploaded files and the secret key. Back up that directory and a lost machine costs you only the time to start Open WebUI again.
tar czf openwebui-$(date +%F).tar.gz -C /workspace open-webui
To restore, extract the archive and start Open WebUI with the same data directory. Take a backup before every upgrade. GPUwerk's own periodic copy of /workspace is for drive failures only, so copy this archive off the instance yourself.