owui-tools/docs/install-ubuntu-desktop.md

Installing on an Ubuntu desktop

Start to finish. About an hour, most of it unattended. Steps 1–4 are the whole tool server; 5 and 6 are optional extras, and 6 is the big one.

Assumes Ubuntu 24.04 or newer with Docker installed, and that you can sudo.

---

Already running Ollama and Open WebUI? Skip to step 3.

1. Ollama and a model

Read the header of docs/deployment/ollama.compose.yml first: the memory limit and the port binding are the two things most likely to need changing for your machine. Then:

docker compose -f docs/deployment/ollama.compose.yml up -d
docker exec ollama ollama pull qwen3.8:latest

Any model with tool-calling support works; qwen3.8 is what this was tuned against.

2. Open WebUI

Edit docs/deployment/open-webui.compose.yml and set WEBUI_SECRET_KEY to your own value (openssl rand -hex 32). The OIDC block at the bottom is optional — delete it to use the built-in login form. Then:

docker compose -f docs/deployment/open-webui.compose.yml up -d

Open http://localhost:3000, create the first account — it becomes the admin — and check you can chat before going any further. If that does not work, nothing downstream will, and the tool server will get the blame.

The compose file pins its project name to openwebui, so its network is openwebui_default — which is the name the tool server joins in the next step. If you already run Open WebUI under some other name, put that network in OWUITOOLS_OWUI_NETWORK instead of renaming anything.

3. The tool server

cp configs/owuitools.env.example configs/owuitools.env
sed -i "s|^OWUITOOLS_AUTH_TOKEN=.*|OWUITOOLS_AUTH_TOKEN=$(openssl rand -hex 32)|" \
  configs/owuitools.env

Set OWUITOOLS_CONTACT to a real address while you are in there — Wikipedia refuses requests without one.

Then generate a secret for SearXNG, which ships with a placeholder:

sed -i "s|^  secret_key: .*|  secret_key: \"$(openssl rand -hex 32)\"|" \
  configs/services/searxng.settings.yml
docker compose up -d --build

Give it a minute, then:

./tests/try-tool.sh          # is it up?
./tests/smoke.sh             # every tool, through the real path

Nothing here publishes a port to the host — the app container has no default route and the gateway is only on Open WebUI's docker network. So curl http://localhost:8000 does not reach the tool server, and may reach something else entirely that answers and looks healthy. try-tool.sh calls it from inside the container instead.

smoke.sh exercises every tool through the real path. Some cases need the internet and can fail on a slow link; a couple of failures out of 175 is not alarming, twenty is.

4. Point Open WebUI at it

Two things, both by hand, and the second matters more than the first.

The connection. Admin Panel → Settings → Integrations — not your personal settings, or only you will have the tools.

Field	Value
Type	OpenAPI
URL	http://owuitools-gw:8000 (or the host's address if not on the same docker network)
Auth	Bearer, and the token you generated

Save. It fetches the spec; you should see 22 tools.

The model. Workspace → Models → your model → Edit:

• paste ../configs/assistant/system-prompt.md into System Prompt
• turn the tool connection on
• Function Calling: Default, not Legacy
• set num_ctx to match what Ollama loaded

See advanced-params.md for the rest and the reasoning.

Try it: "what's the current version of ripgrep?" should call lookup_package rather than recalling a number.

After any change to the tool list

docker compose restart api

…then re-save the connection in Open WebUI. It caches the spec from when you saved.

5. The filters — optional

Five small plugins, pasted into Open WebUI. None are required. inline_tool_images is the one to install if you plot anything; vm_agent_progress is required to watch a VM session rather than stare at a spinner. See filters.md.

6. The VM sub-agent — optional, and the big one

See setup/vm-agent.md. In outline:

sudo ./vm/host/install.sh          # users, units, nftables, polkit
sudo ./vm/images/import.sh ubuntu  # ~9.6 GB, checksum-verified, frozen on arrival

That downloads a finished base image. To build one instead — about 25 unattended minutes, and the right choice if you want to change what is in it:

sudo ./vm/images/fetch.sh ubuntu   # ~6 GB, verified against Canonical's checksums
sudo ./vm/images/ubuntu/build.sh

Then open Tool Server VM Maintenance from your applications menu and check the Ubuntu row says frozen.

You will also want setup/gitea.md if sessions should publish what they build, and the three timeouts in advanced-params.md raised, or a long session is cut off with the work already done.

---

If something is wrong

Symptom	Cause
No tools in the model	Connection added to personal settings instead of Admin → Integrations
Tools listed but never called	Function Calling set to Legacy; or the system prompt was not pasted
A tool you switched on is missing	docker compose restart api, then re-save the connection
wikipedia_lookup returns 403	OWUITOOLS_CONTACT is unset
Searches return nothing	SearXNG's engines are blocking your IP — see setup/searxng.md
vm_agent fails at ~5 minutes	AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER unset; it defaults to 300, not to unlimited
Everything up, nothing reachable	You recreated netguard without recreating api — see configuration.md