# 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:

```sh
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:

```sh
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

```sh
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:

```sh
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:

```sh
./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`](../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](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

```sh
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](filters.md).

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

See [setup/vm-agent.md](setup/vm-agent.md). In outline:

```sh
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:

```sh
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](setup/gitea.md) if sessions should publish what they
build, and the three timeouts in [advanced-params.md](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](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](configuration.md#servicesthe-supporting-containers) |