115 lines
4.6 KiB
Markdown
115 lines
4.6 KiB
Markdown
# `vm_agent` — the VM sub-agent
|
|
|
|
This is the one tool with real setup. Budget an hour, most of it unattended.
|
|
|
|
It is also removed automatically when the VM job volume is not mounted, so on a host
|
|
without the VM stack the `vm_agent = true` line in `configs/tools.toml` does nothing and
|
|
the assistant is never told the tool exists.
|
|
|
|
This page is the checklist. [../vm-agent/overview.md](../vm-agent/overview.md) explains what
|
|
it is and how the isolation works; [../vm-agent/base-images.md](../vm-agent/base-images.md)
|
|
covers media and base images in detail.
|
|
|
|
## What it does
|
|
|
|
Hands a task to a second model that has a real, throwaway Ubuntu or Windows machine in
|
|
front of it. That model writes the script, runs it, reads the actual error, fixes it, and
|
|
comes back with evidence. The machine is destroyed afterwards; the project folder survives.
|
|
|
|
## What the host needs
|
|
|
|
| Requirement | Why | Check |
|
|
|---|---|---|
|
|
| KVM | the machine is a real VM | `ls -l /dev/kvm` |
|
|
| A ZFS pool | the project quota and the overlay ceiling are ZFS quotas — they are what stops a runaway guest filling `/` and taking Docker, Ollama and Open WebUI down with it | `zfs list` |
|
|
| ~50 GB free for base images | Ubuntu settles around 9 GB, Windows around 40 GB | `df -h /var/lib` |
|
|
| `qemu-system-x86`, `qemu-utils`, `virtiofsd`, `ovmf`, `swtpm-tools`, `socat` | | `dpkg -l` |
|
|
| A VNC viewer (`remmina`) | the maintenance console | |
|
|
|
|
## Steps
|
|
|
|
1. **Install the host side.**
|
|
|
|
```sh
|
|
sudo ./vm/host/install.sh
|
|
```
|
|
|
|
Creates three service users, the systemd units, the nftables guard, the polkit rule and
|
|
the directory layout. Idempotent — re-run it after changing anything in `vm/host/`.
|
|
|
|
It works out who the operator is from `sudo`, and that person is the only account polkit
|
|
will let unfreeze a base image. Override with `OWUIVM_OPERATOR` in `configs/host.env`.
|
|
|
|
2. **Get a base image.** Two ways, and the first is much faster.
|
|
|
|
**Import a prebuilt one** — a coffee rather than an afternoon, and for Windows it avoids
|
|
clicking through an installer in a VNC console entirely:
|
|
|
|
```sh
|
|
sudo ./vm/images/import.sh ubuntu # ~9.6 GB
|
|
sudo ./vm/images/import.sh windows # ~41 GB
|
|
```
|
|
|
|
Checksum-verified, installed frozen and owned correctly, and resumable if the download
|
|
drops. See [../vm-agent/base-images.md](../vm-agent/base-images.md) for what is in them,
|
|
how to host your own, and the note on Windows licensing.
|
|
|
|
**Or build your own**, which is the right path if you want to change what is in the
|
|
image. Steps 3 and 4 below are that route; skip them if you imported.
|
|
|
|
3. **Get the installation media.**
|
|
|
|
```sh
|
|
sudo ./vm/images/fetch.sh ubuntu # downloads and verifies against Canonical's checksums
|
|
sudo ./vm/images/fetch.sh virtio # only needed for Windows
|
|
```
|
|
|
|
Windows media you supply yourself. You can now also do this from the maintenance app —
|
|
**Insert disc…** on a machine that has no disk yet.
|
|
|
|
4. **Build the Ubuntu base image.**
|
|
|
|
```sh
|
|
sudo ./vm/images/ubuntu/build.sh # ~25 minutes, unattended
|
|
```
|
|
|
|
Windows has no unattended path: install it through the maintenance app's console. See
|
|
[../vm-agent/base-images.md](../vm-agent/base-images.md).
|
|
|
|
5. **Set up Gitea**, if you want sessions to publish. See [gitea.md](gitea.md). Skippable.
|
|
|
|
6. **Install the live-progress filter** so you can watch a session. See
|
|
[../filters.md](../filters.md) — `vm_agent_progress`, with its `api_key` valve set to
|
|
your `OWUITOOLS_AUTH_TOKEN`.
|
|
|
|
7. **Raise the three timeouts.** A session runs for minutes to hours and dies at the
|
|
shortest clock. See [../advanced-params.md](../advanced-params.md).
|
|
|
|
## Checking it
|
|
|
|
```sh
|
|
sudo ./tests/vm_host_asserts.sh # the isolation suite
|
|
|
|
# A session by hand. `ready` is not optional: every verb that touches the
|
|
# machine is refused until the guest agent has answered, and this is what
|
|
# waits for it.
|
|
sudo -u owuivmd vmctl open --os ubuntu --project scratch
|
|
sudo -u owuivmd vmctl ready
|
|
sudo -u owuivmd vmctl plan "check the machine came up"
|
|
sudo -u owuivmd vmctl run 'uname -a'
|
|
sudo -u owuivmd vmctl close
|
|
```
|
|
|
|
Then, from a chat: *"use the VM to write a bash script that prints the largest ten files
|
|
under /usr and run it"*.
|
|
|
|
## Where the base images live, and what "frozen" means
|
|
|
|
`/var/lib/owuivm/base/<id>.qcow2`, and frozen is **literally the owner write bit**. A
|
|
session boots a throwaway overlay backed by the base; nothing it installs survives. vmd
|
|
refuses to start a session at all while a base image is writable, so an image left
|
|
unfrozen stops the agent rather than quietly letting it change the original.
|
|
|
|
Freezing and unfreezing is one button in the **Tool Server VM Maintenance** app on the
|
|
desktop.
|