Initial Commit
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
# OWUI Tools
|
||||
|
||||
A tool server for [Open WebUI](https://github.com/open-webui/open-webui), and a VM
|
||||
sub-agent that can actually try things.
|
||||
|
||||
A local assistant can reason, search and calculate. It cannot *check*. Asked whether a
|
||||
PowerShell script works, it can only read documentation about PowerShell; asked for the
|
||||
current version of a package, it recalls a number that was true when it was trained. This
|
||||
fixes both halves: **22 tools** for looking things up and working things out, and one more
|
||||
that hands a task to a second model driving a **real, throwaway virtual machine** which
|
||||
writes the script, runs it, reads the actual error, fixes it, and comes back with evidence.
|
||||
|
||||
Everything runs on your own hardware. Nothing leaves the machine except the web requests a
|
||||
tool makes on your behalf, and those go out through a proxy that refuses to touch your LAN.
|
||||
|
||||
> It speaks **OpenAPI**, which is what Open WebUI consumes natively — not the Model Context
|
||||
> Protocol. If you are looking for an MCP server, this is not one.
|
||||
|
||||
```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
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Then register it in Open WebUI and paste the system prompt —
|
||||
**[docs/install-ubuntu-desktop.md](docs/install-ubuntu-desktop.md)** walks through the whole
|
||||
thing on a clean machine.
|
||||
|
||||
## What it gives the assistant
|
||||
|
||||
| Group | Tools |
|
||||
|---|---|
|
||||
| **Web and research** | `web_search`, `fetch_page`, `wikipedia_lookup`, `search_stackexchange`, `search_papers` |
|
||||
| **IT and reference** | `lookup_rfc`, `lookup_cve`, `read_man_page`, `lookup_package` |
|
||||
| **Networking** | `subnet_calc`, `dns_lookup`, `inspect_tls`, `http_headers`, `lookup_ip_or_asn`, `network_reference` |
|
||||
| **Electronics** | `ohms_law_power`, `component_calc`, `pcb_calc`, `wiring_calc`, `find_datasheet` |
|
||||
| **Execution** | `matlab_run` (Octave, sandboxed), `vm_agent` (a real machine) |
|
||||
|
||||
Most need no setup at all. Turn any of them off in
|
||||
[`configs/tools.toml`](configs/tools.toml) — that removes them from the spec rather than
|
||||
hiding them, so you stop paying their schema tokens on every turn. Full list and what each
|
||||
needs: **[docs/tools.md](docs/tools.md)**.
|
||||
|
||||
## Configuring it
|
||||
|
||||
Everything you are meant to edit is in **[`configs/`](configs/)** — the stack's settings,
|
||||
the tool switch, the assistant's system prompt, and the sub-agent's prompts, parameters and
|
||||
tool definitions. Nothing else in the tree needs changing to run this.
|
||||
|
||||
See **[docs/configuration.md](docs/configuration.md)**.
|
||||
|
||||
## Isolation
|
||||
|
||||
The tool server takes URLs chosen by a language model, so it is built on the assumption that
|
||||
one day it will be persuaded to fetch something it should not.
|
||||
|
||||
- The app container has **no default route**. It lives in a network namespace whose only
|
||||
permitted destinations are squid, valkey and the inbound request from its gateway.
|
||||
- **squid refuses private address space** however politely it is asked.
|
||||
- The filter **re-verifies itself** before its healthcheck passes: a firewall that silently
|
||||
failed to apply is worse than none, because everything downstream carries on as though it
|
||||
were enforced.
|
||||
- Every container drops all capabilities, runs read-only where it can, and has memory and
|
||||
pid limits.
|
||||
|
||||
The VM sub-agent adds a second boundary: the guest has real internet and no route to your
|
||||
network, enforced primarily by a systemd address filter — *not* by a firewall, which fails
|
||||
open on any `nft flush ruleset`. `tests/vm_host_asserts.sh` proves it by turning each layer
|
||||
off in turn and re-running the same probe against the others.
|
||||
|
||||
Details, including what it deliberately does **not** prevent:
|
||||
**[docs/vm-agent/overview.md](docs/vm-agent/overview.md)**.
|
||||
|
||||
## The VM sub-agent
|
||||
|
||||
`vm_agent` starts a throwaway Ubuntu or Windows machine, hands it to a second model with
|
||||
about thirty tools — a shell, a file editor, a screen it can look at and click on, and a
|
||||
lookup suite — and returns a report whose facts are assembled by the trusted side rather
|
||||
than by the agent.
|
||||
|
||||
The machine is destroyed afterwards. The project folder survives on a quota'd dataset, and
|
||||
can be published to Gitea as a release.
|
||||
|
||||
Setup is the one substantial piece of work here: **[docs/setup/vm-agent.md](docs/setup/vm-agent.md)**.
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[docs/](docs/README.md)** — installation, configuration, every tool, the recommended
|
||||
parameters, the filters.
|
||||
- **[docs/operating.md](docs/operating.md)** — logs, rate limits, the cache, restarting
|
||||
things safely, and what to check when something looks wrong.
|
||||
- **[logs/](logs/README.md)** — every component writes its own file there, so there is one
|
||||
place to look rather than nine `docker compose logs` invocations.
|
||||
- **[docs/deployment/](docs/deployment/README.md)** — compose files for Ollama, Open WebUI
|
||||
and Gitea, the three services that live outside this repo.
|
||||
- **[docs/TUNING.md](docs/TUNING.md)** — the change log. Every entry is one change: what it
|
||||
was meant to fix, and what measurably happened afterwards. Long, and the most useful
|
||||
document here if you intend to modify anything.
|
||||
- **[docs/testing/](docs/testing/README.md)** — the corpus the tuning was measured against:
|
||||
forty graded prompts with rubrics, transcripts and scores.
|
||||
|
||||
## Requirements
|
||||
|
||||
Docker, an Ollama instance with a model, and Open WebUI. The VM sub-agent additionally needs
|
||||
KVM, a ZFS pool and about 50 GB for base images — it is optional, and the tool removes
|
||||
itself when the VM stack is absent.
|
||||
|
||||
Developed against Open WebUI 0.11.3 and `qwen3.8:latest` at a 160k context.
|
||||
|
||||
## Checking it works
|
||||
|
||||
```sh
|
||||
./verify.py # what is set up, what is off, what is broken
|
||||
```
|
||||
|
||||
A one-line-per-tool report, a full log in `logs/verify.log`, and a separate
|
||||
`logs/verify-error-<tool>.log` for anything that fails. See
|
||||
[docs/verifying.md](docs/verifying.md).
|
||||
|
||||
## Running the tests
|
||||
|
||||
```sh
|
||||
./tests/smoke.sh # every tool, through the real gateway
|
||||
python3 tests/test_*.py # unit tests, no container needed
|
||||
sudo ./tests/vm_host_asserts.sh # the VM isolation suite
|
||||
```
|
||||
Reference in New Issue
Block a user