Initial Commit
This commit is contained in:
@@ -0,0 +1,184 @@
|
||||
# Configuration
|
||||
|
||||
Everything you are meant to edit is in [`../configs/`](../configs/). Nothing else in the
|
||||
tree needs changing to run this.
|
||||
|
||||
```
|
||||
configs/
|
||||
owuitools.env the stack's settings and its one required token (gitignored)
|
||||
owuitools.env.example the template to copy it from (tracked)
|
||||
tools.toml which tools the assistant can see
|
||||
vms.toml the machines the VM sub-agent can be given
|
||||
vmd.env the VM daemon's settings, installed to /etc/owuivm/
|
||||
host.env.example overrides for vm/host/install.sh (optional)
|
||||
assistant/
|
||||
system-prompt.md what you paste into Open WebUI
|
||||
agent/
|
||||
params.env the sub-agent's model, sampling and session bounds
|
||||
tools.toml every one of the sub-agent's tool definitions
|
||||
prompt.md its system prompt, shared by both machines
|
||||
prompt.ubuntu.md the Ubuntu half
|
||||
prompt.windows.md the Windows half
|
||||
prompt.screen.md the part about looking at the screen
|
||||
services/
|
||||
gateway.nginx.conf the ingress proxy
|
||||
egress.squid.conf the one route to the internet
|
||||
searxng.settings.yml the search back end
|
||||
vmgw.nginx.conf.template the sub-agent's one path to Ollama
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `owuitools.env`
|
||||
|
||||
Copy the example and fill it in:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
`.env` in the project root is a symlink to it, because that is the file `docker compose`
|
||||
reads. Both are gitignored.
|
||||
|
||||
**`OWUITOOLS_AUTH_TOKEN` is the only required setting.** The same value goes in Open WebUI's
|
||||
tool connection, and in the `vm_agent_progress` filter's valve if you use it.
|
||||
|
||||
| Setting | Default | What it does |
|
||||
|---|---|---|
|
||||
| `OWUITOOLS_AUTH_TOKEN` | — | **Required.** The bearer token Open WebUI presents. |
|
||||
| `OWUITOOLS_CONTACT` | `owuitools@localhost` | Goes in the User-Agent. Wikimedia **403s** without a real one — see [setup/contact.md](setup/contact.md). |
|
||||
| `OWUITOOLS_MAX_RESPONSE_CHARS` | `12000` | Ceiling on any one tool response. Open WebUI does not truncate tool results, so this is what stands between one greedy fetch and a blown context. |
|
||||
| `OWUITOOLS_PROBE_RATE_PER_HOUR` | `30` | Per-user hourly budget for the four tools that touch a named host. `0` disables the limiter. |
|
||||
| `OWUITOOLS_LOG_LEVEL` | `INFO` | |
|
||||
| `OWUITOOLS_VM_WAIT_SECONDS` | `7000` | How long one `vm_agent` call may block. One of [three clocks](advanced-params.md#the-three-clocks). |
|
||||
| `OWUITOOLS_GITHUB_TOKEN` | — | Optional. [setup/github-token.md](setup/github-token.md) |
|
||||
| `OWUITOOLS_STACKEXCHANGE_KEY` | — | Optional. [setup/stackexchange.md](setup/stackexchange.md) |
|
||||
| `OWUITOOLS_NVD_KEY` | — | Optional. [setup/nvd.md](setup/nvd.md) |
|
||||
|
||||
---
|
||||
|
||||
## `tools.toml` — the on/off switch
|
||||
|
||||
One line per tool. `false` **removes** it: the operation leaves the OpenAPI spec, so the
|
||||
model is never told it exists, and the endpoint stops answering.
|
||||
|
||||
That matters because the 22 schemas cost about **9,700 tokens on every turn of every
|
||||
conversation**, whether or not a tool is used. A tool you will not use is a standing tax.
|
||||
|
||||
```toml
|
||||
[tools]
|
||||
web_search = true
|
||||
pcb_calc = false # not doing electronics
|
||||
```
|
||||
|
||||
Tools needing setup carry a comment pointing at the page for it. After editing:
|
||||
|
||||
```sh
|
||||
docker compose restart api
|
||||
```
|
||||
|
||||
…and then **re-save the tool connection in Open WebUI**, which caches the spec it fetched.
|
||||
Both steps are needed.
|
||||
|
||||
A tool the file does not mention stays **on**, so an old config never silently removes a new
|
||||
tool. A name that does not exist is reported in the log and ignored.
|
||||
|
||||
---
|
||||
|
||||
## `vms.toml` — the machines
|
||||
|
||||
```toml
|
||||
[[machine]]
|
||||
id = "ubuntu"
|
||||
name = "Ubuntu"
|
||||
iso = "ubuntu*.iso"
|
||||
```
|
||||
|
||||
**`id` is identity, not a label.** It names the base disk, the systemd unit instance, the
|
||||
saved-machine directory, and the value the assistant passes as `os` — and it appears in
|
||||
regex allowlists inside the privileged launch scripts, which is what lets those scripts
|
||||
refuse a path. Changing it does not rename a machine; it describes one that does not exist.
|
||||
|
||||
**`name` is yours.** Change it here, or press **Rename** in the maintenance app. Renames
|
||||
made in the app are written to `/var/lib/owuivm/registry/vm-names.toml` and merged over the
|
||||
top, so the registry keeps its comments.
|
||||
|
||||
`shell`, `project` and `example` are prompt text, substituted into the sub-agent's tool
|
||||
descriptions so one set of definitions describes both machines.
|
||||
|
||||
---
|
||||
|
||||
## `agent/` — the second model
|
||||
|
||||
`params.env` holds its model, sampling and session bounds; see
|
||||
[advanced-params.md](advanced-params.md).
|
||||
|
||||
`tools.toml` holds **every one of its tool definitions** — name, description and parameters.
|
||||
The descriptions are prompt text the model reads, and rewording one is often the most
|
||||
effective change available. It is bind-mounted, so:
|
||||
|
||||
```sh
|
||||
docker compose restart vmagent
|
||||
```
|
||||
|
||||
is enough — no rebuild.
|
||||
|
||||
What that file **cannot** do is give the agent a new capability. Dispatch lives in code, and
|
||||
a tool named there with nothing behind it is refused at startup, naming the file. There is
|
||||
an allowlist (`DISPATCHABLE` in `vmagent/app/tools.py`) precisely so that a config file
|
||||
cannot widen what the agent can reach.
|
||||
|
||||
The prompts beside it are loaded the same way. If `prompt.md` is missing the agent
|
||||
**refuses to start**: one that runs with no instructions still calls tools and still reports
|
||||
success, which is the worst failure available.
|
||||
|
||||
---
|
||||
|
||||
## `services/` — the supporting containers
|
||||
|
||||
Bind-mounted read-only into their containers. Restart the one you changed.
|
||||
|
||||
| File | Container | Watch out for |
|
||||
|---|---|---|
|
||||
| `gateway.nginx.conf` | `owuitools-gw` | `/tools/vm_agent` has its own 7200s timeout; everything else keeps 240s |
|
||||
| `egress.squid.conf` | `owuitools-egress` | The private-range denies are a security control, not tuning |
|
||||
| `searxng.settings.yml` | `owuitools-searxng` | Set your own `secret_key`. The engine list is a measurement from one IP — see [setup/searxng.md](setup/searxng.md) |
|
||||
| `vmgw.nginx.conf.template` | `owuitools-vmgw` | The `location =` exact matches are load-bearing. Ollama is unauthenticated and serves `DELETE /api/delete` |
|
||||
|
||||
**Restarting `netguard` or `vmguard` strands the containers that share their network
|
||||
namespace.** They keep running, keep passing their own healthchecks, and have no route to
|
||||
anything. Recreate the dependents too:
|
||||
|
||||
```sh
|
||||
docker compose up -d --force-recreate netguard api searxng
|
||||
docker compose up -d --force-recreate vmguard vmagent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Host-side settings
|
||||
|
||||
The VM sub-agent's daemon reads `/etc/owuivm/vmd.env`, created from
|
||||
[`../configs/vmd.env`](../configs/vmd.env) by `vm/host/install.sh` — **only if it is not
|
||||
already there**, because the live copy holds the Gitea token. Edit the live file to change
|
||||
the running daemon.
|
||||
|
||||
`configs/host.env` (optional, gitignored) overrides what `install.sh` works out for itself.
|
||||
Copy `host.env.example` if any of its guesses are wrong for your machine.
|
||||
|
||||
Nothing in it is required — the installer derives the operator from `sudo`, the VM's memory
|
||||
and CPU from `nproc` and installed RAM, and defaults the pool to `/Pool`. What you are most
|
||||
likely to need is:
|
||||
|
||||
| Setting | Why |
|
||||
|---|---|
|
||||
| `OWUIVM_POOL_ROOT` | Your ZFS pool's mountpoint. `/Pool` is this project's default and nothing more — `zfs list` shows yours. The installer creates `<pool>/vmrun` and `<pool>/vmprojects` if they are missing. |
|
||||
| `OWUIVM_GITEA_ALLOW` | The daemon runs `IPAddressDeny=any`. Gitea is not on the allowlist by default, because a fresh install has none. |
|
||||
| `OWUIVM_ALLOWED_CPUS` | Pin the VM to particular cores. Empty — the default — means no pinning. |
|
||||
|
||||
These are read at **install time** and written into the units and scripts, so re-run
|
||||
`sudo ./vm/host/install.sh` after changing them. The installer refuses to install a file
|
||||
that still has an unrendered placeholder in it, so a value added to a template and not to
|
||||
the installer fails loudly rather than producing a unit that will not start.
|
||||
Reference in New Issue
Block a user