`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 explains what it is and how the isolation works; ../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

Install the host side.
```
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.
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:
```
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 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.

Get the installation media.

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.

Build the Ubuntu base image.
```
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.
Set up Gitea, if you want sessions to publish. See gitea.md. Skippable.
Install the live-progress filter so you can watch a session. See ../filters.md — vm_agent_progress, with its api_key valve set to your OWUITOOLS_AUTH_TOKEN.
Raise the three timeouts. A session runs for minutes to hours and dies at the shortest clock. See ../advanced-params.md.

Checking it

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.

4.6 KiB Raw Blame History

vm_agent — the VM sub-agent