Initial Commit
This commit is contained in:
@@ -0,0 +1,114 @@
|
||||
# `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.
|
||||
Reference in New Issue
Block a user