Grant/owui-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated README

Browse Source
This commit is contained in:
Grant
2026-09-15 15:40:12 -04:00
parent 4dc7086e7e
commit b862d23b62
1 changed files with 61 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+60 -58
View File
@@ -1,20 +1,17 @@
# OWUI Tools # OWUI Tools
A tool server for [Open WebUI](https://github.com/open-webui/open-webui), and a VM A tool server for [Open WebUI](https://github.com/open-webui/open-webui), and a VM
sub-agent that can actually try things. sub-agent that can test before claiming that everything works.
A local assistant can reason, search and calculate. It cannot *check*. Asked whether a A local assistant can only reason. It cannot *check*. This tool server allows the LLM to
PowerShell script works, it can only read documentation about PowerShell; asked for the ground its answer in fact: **22 tools** for looking things up and working things out, and one more
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 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. can write the script, run it, read the actual errors, fix them, and loop until it works.
Everything runs on your own hardware. Nothing leaves the machine except the web requests a 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. tool makes on your behalf.
> It speaks **OpenAPI**, which is what Open WebUI consumes natively — not the Model Context > It speaks **OpenAPI**, which is what Open WebUI consumes natively.
> Protocol. If you are looking for an MCP server, this is not one.
```sh ```sh
cp configs/owuitools.env.example configs/owuitools.env cp configs/owuitools.env.example configs/owuitools.env
@@ -23,9 +20,9 @@ sed -i "s|^OWUITOOLS_AUTH_TOKEN=.*|OWUITOOLS_AUTH_TOKEN=$(openssl rand -hex 32)|
docker compose up -d --build docker compose up -d --build
``` ```
Then register it in Open WebUI and paste the system prompt — 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 **[docs/install-ubuntu-desktop.md](docs/install-ubuntu-desktop.md)** walks through the whole
thing on a clean machine. setup process on a clean machine.
## What it gives the assistant ## What it gives the assistant
@@ -38,90 +35,95 @@ thing on a clean machine.
| **Execution** | `matlab_run` (Octave, sandboxed), `vm_agent` (a real machine) | | **Execution** | `matlab_run` (Octave, sandboxed), `vm_agent` (a real machine) |
Most need no setup at all. Turn any of them off in 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 [`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 hiding them, so you stop paying their schema tokens on every turn. Full list and what each
needs: **[docs/tools.md](docs/tools.md)**. needs: **[docs/tools.md](docs/tools.md)**.
## Configuring it ## Configuring it
Everything you are meant to edit is in **[`configs/`](configs/)** — the stack's settings, Everything you need 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 switches, 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. tool definitions. Nothing else in the tree needs changing to run this.
See **[docs/configuration.md](docs/configuration.md)**. See **[docs/configuration.md](docs/configuration.md)**.
## Isolation ## Isolation
The tool server takes URLs chosen by a language model, so it is built on the assumption that The tool server fetches URLs chosen by a language model. It assumes the model may be
one day it will be persuaded to fetch something it should not. persuaded to request something it should not.
- The app container has **no default route**. It lives in a network namespace whose only - The app container has **no default route**. Its network namespace only permits traffic
permitted destinations are squid, valkey and the inbound request from its gateway. to squid and valkey, plus inbound requests from its gateway.
- **squid refuses private address space** however politely it is asked. - **squid blocks private address space**.
- The filter **re-verifies itself** before its healthcheck passes: a firewall that silently - The filter **verifies its rules** before passing its healthcheck, so downstream services
failed to apply is worse than none, because everything downstream carries on as though it do not rely on a filter that failed to apply.
were enforced. - Every container drops all capabilities, runs read-only where possible, and has memory
- Every container drops all capabilities, runs read-only where it can, and has memory and and process limits.
pid limits.
The VM sub-agent adds a second boundary: the guest has real internet and no route to your The VM sub-agent adds a second boundary: the guest has internet access but no route to your
network, enforced primarily by a systemd address filter — *not* by a firewall, which fails network. This is enforced primarily by a systemd address filter. A firewall alone fails
open on any `nft flush ruleset`. `tests/vm_host_asserts.sh` proves it by turning each layer open after `nft flush ruleset`. `tests/vm_host_asserts.sh` tests the isolation by disabling
off in turn and re-running the same probe against the others. each layer in turn and running the same probe against the remaining layers.
Details, including what it deliberately does **not** prevent: Details, including what the isolation does **not** prevent:
**[docs/vm-agent/overview.md](docs/vm-agent/overview.md)**. **[docs/vm-agent/overview.md](docs/vm-agent/overview.md)**.
## The VM sub-agent ## The VM sub-agent
`vm_agent` starts a throwaway Ubuntu or Windows machine, hands it to a second model with `vm_agent` starts a throwaway Ubuntu or Windows machine and 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 about thirty tools - a shell, a file editor, a screen it can view and click on, and a lookup
lookup suite — and returns a report whose facts are assembled by the trusted side rather suite. It returns a report with facts assembled by the trusted side.
than by the agent.
The machine is destroyed afterwards. The project folder survives on a quota'd dataset, and The machine is destroyed afterwards. The project folder survives on a dataset with a
can be published to Gitea as a release. quota 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)**. Setup takes more work than the rest of the stack. Follow
**[docs/setup/vm-agent.md](docs/setup/vm-agent.md)**.
## Documentation ## Documentation
- **[docs/](docs/README.md)** — installation, configuration, every tool, the recommended - **[docs/](docs/README.md)** - installation, configuration, tool details, recommended
parameters, the filters. parameters and filters.
- **[docs/operating.md](docs/operating.md)** — logs, rate limits, the cache, restarting - **[docs/operating.md](docs/operating.md)** - logs, rate limits, caching, safe restarts
things safely, and what to check when something looks wrong. and troubleshooting.
- **[logs/](logs/README.md)** — every component writes its own file there, so there is one - **[logs/](logs/README.md)** - each component writes its own log file here, giving you
place to look rather than nine `docker compose logs` invocations. one place to check instead of running nine `docker compose logs` commands.
- **[docs/deployment/](docs/deployment/README.md)** — compose files for Ollama, Open WebUI - **[docs/deployment/](docs/deployment/README.md)** - compose files for Ollama, Open WebUI
and Gitea, the three services that live outside this repo. and Gitea, the three services that run outside this repo.
- **[docs/TUNING.md](docs/TUNING.md)** — the change log. Every entry is one change: what it - **[docs/TUNING.md](docs/TUNING.md)** - the change log. Each entry records one change,
was meant to fix, and what measurably happened afterwards. Long, and the most useful what it was meant to fix and the measured result. It is long, but the most useful
document here if you intend to modify anything. reference if you plan to modify the project.
- **[docs/testing/](docs/testing/README.md)** — the corpus the tuning was measured against: - **[docs/testing/](docs/testing/README.md)** - the test corpus used to measure tuning:
forty graded prompts with rubrics, transcripts and scores. forty graded prompts with rubrics, transcripts and scores.
## Requirements ## Requirements
Docker, an Ollama instance with a model, and Open WebUI. The VM sub-agent additionally needs Docker, an Ollama instance with a model, and Open WebUI.
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. The optional VM sub-agent also needs KVM, a ZFS pool and about 50 GB for base images.
The tool removes itself when the VM stack is absent.
Developed against Open WebUI 0.11.3 and `qwen3.8:latest` with a 160k context window.
## Checking it works ## Checking it works
```sh ```sh
./verify.py # what is set up, what is off, what is broken ./verify.py # what is configured, disabled or broken
``` ```
A one-line-per-tool report, a full log in `logs/verify.log`, and a separate This prints one line per tool, writes a full log to `logs/verify.log`, and creates a
`logs/verify-error-<tool>.log` for anything that fails. See separate `logs/verify-error-<tool>.log` for each tool that fails. See
[docs/verifying.md](docs/verifying.md). [docs/verifying.md](docs/verifying.md).
## Running the tests ## Running the tests
```sh ```sh
./tests/smoke.sh # every tool, through the real gateway ./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 # Unit tests, no container needed
for test_file in tests/test_*.py; do
python3 "$test_file"
done
sudo ./tests/vm_host_asserts.sh # VM isolation tests
``` ```