feat: enhance guest agent setup and terminal support for microVMs

DEVELOPER.md

@@ -998,17 +998,28 @@ too. An unconfirmed cleanup is an unknown outcome. Stopping the agent service
 also kills its job scopes; dropping an HTTP connection does not cancel a job.
 
 The v5 Ubuntu builder installs Python, the terminal-capable service, and an
-ownership manifest. Creation provisions the VM ID/username in root-only
+ownership manifest. Agent setup is mandatory on every compatible image:
-`/etc/uvm-agent.json` before marking the disk ready. Cached v4 templates are also
+`create()` provisions the VM ID/username in root-only `/etc/uvm-agent.json` before
-configured; their original manifest-less agent is recognized by its exact
+marking the disk ready, and `_start_locked()` ensures the agent after confirmed
-published source digest. Earlier templates require an explicit stopped-disk
+runtime cleanup and pending resize, before booting. This covers stopped starts,
-`agent/install` request.
+restarts, and resizing. There is no image-marker allowlist for agent setup.
+An observed live or ambiguous VMM never permits offline agent writes.
+
+`_guest_agent_current()` checks the expected payloads, identity, file metadata,
+ownership manifest, and enabled service without mutating the disk. Current
+installations return immediately. The explicit `agent/install` operation forces
+a staged recheck for manual repair. The original manifest-less v4 agent is
+recognized by its exact published source digest.
+
 Provisioning and upgrades stage a sparse copy, replay/check ext4, validate guest
 path ownership and recorded agent-file hashes, enable the service, verify writes,
 and publish atomically. A root-only guest manifest records managed file hashes
 so later upgrades preserve guest edits. An older guest missing Python installs
 it through apt inside the guest on its next boot; no guest binaries execute on
 the host. This bootstrap requires working guest egress until the runtime is ready.
+Incompatible custom images or agent setup failures prevent boot with an actionable
+error; they are not silently skipped. New-VM failures roll back creation, while
+retained-VM failures preserve the private disk for retry.
 
 The guest needs systemd, Python 3.10+, built-in virtio-vsock, and cgroup v2 with
 `cgroup.kill` (Linux 5.14+). Host socket paths are derived from Settings, so the

README.md

@@ -387,10 +387,14 @@ files are private to the host account running Nest. One Nest server owns
 sessions for a given VM registry at a time, with up to 32 active sessions; the
 guest agent shares its eight connection slots between terminals and exec calls.
 
-For existing VMs, use **stop → Sessions → Guest terminal setup → Install / update
+**Vsock and the guest agent are configured by default for every microVM.**
-terminal support → start** once. Newly built v5 Ubuntu images include terminal
+Creation installs and enables the agent on every compatible image, including
-support; cached v4 templates are upgraded during new-VM provisioning. The same
+cached older templates and custom images. Each stopped-disk boot also installs
-guest-agent/kernel requirements described below apply to terminals.
+or updates it automatically; an already-current installation is a read-only
+check. Existing running VMs receive the setup on their next restart.
+The **Sessions → Guest terminal support → Repair / update terminal support**
+control is available for manual repair on a stopped VM. The guest-agent/kernel
+requirements described below apply to terminals.
 
 Terminal support adds the Python `websockets` dependency. In your micromamba
 environment, install the current project and launch with its interpreter:
@@ -421,14 +425,15 @@ uses guest root without a password prompt. A VM configured with username `root`
 still runs as root when `sudo` is false.
 
 Execution uses a guest systemd agent over Firecracker vsock. It works with SSH
-disabled and with an empty TCP allowlist. Rebuild the default Ubuntu template
+disabled and with an empty TCP allowlist. Every Firecracker boot attaches the
-with `uvm install --force` using your configured checksums to include the agent
+vsock device, and creation/start/restart/resize ensure the guest service is
-and Python in new VMs. Restart the management server to load these routes.
+installed and enabled before boot. Restart the management server to load this
+behavior, then restart older VMs once to apply it automatically.
 
-For an existing VM, call **stop → `POST /vms/{vm_id}/agent/install` → start**.
+Installation stages and verifies a private disk copy when changes are needed,
-Installation stages and verifies a private disk copy, preserving guest data and
+preserving guest data and credentials. If Python is missing, the installed
-credentials. If Python is missing, the installed bootstrap service acquires it
+bootstrap service acquires it inside the guest on boot; this one-time step needs
-inside the guest on the next boot; this one-time step needs guest internet access.
+guest internet access. The default Ubuntu template already includes Python.
 The guest needs Python 3.10+, systemd with cgroup v2, and a vsock-capable Linux
 5.14+ kernel; UVM's default Linux 6.1 kernel provides the required drivers.
 
@@ -497,6 +502,7 @@ defaults are username `root` and password `root`. A custom image must provide:
 - `/etc/passwd`, `/etc/shadow`, and `/etc/ssh/sshd_config`
 - `/etc/group` and `/bin/sh` when creating a new user
 - A root-owned, setuid `/usr/bin/sudo` and `/etc/sudoers` for custom login users
+- systemd and apt for the automatically installed vsock guest agent (Ubuntu 22.04+)
 
 Custom login users receive password-authenticated sudo access. Inside a new VM:
 

USAGE.md

@@ -836,10 +836,12 @@ has a 10,000-line scrollback. A truncation note appears when older output is
 discarded. Terminal input supports pastes up to 64 KiB at a time. Guest output
 is saved even while no browser is attached.
 
-For an older VM, stop it, open **Sessions → Guest terminal setup**, click
+Vsock and the guest agent are set up automatically for every microVM during
-**Install / update terminal support**, and start it again. This uses the existing
+creation and on each stopped-disk boot. This includes compatible older and custom
-stopped-disk agent upgrade endpoint. If the agent is still starting or installing
+images. Restart an older VM once to apply the setup; **Sessions → Guest terminal
-Python, wait for it to become ready before launching a session.
+support → Repair / update terminal support** remains available for manual repair
+while stopped. If the agent is still starting or installing Python, wait for it
+to become ready before launching a session.
 
 The terminal transport uses the guest agent over vsock. It logs in as the VM's
 configured username; `sudo` inside the terminal uses normal guest authentication.
@@ -1178,26 +1180,26 @@ print(result["exit_code"])
 
 #### Prepare New or Existing VMs
 
-The default Ubuntu template recipe v4 includes Python 3 and `uvm-agent.service`.
+The default Ubuntu template includes Python 3 and `uvm-agent.service`. UVM also
-Rebuild it with `uvm install --force` using the checksum settings from the
+installs the service automatically on compatible older/custom images during
-installation section, then create new VMs. Cached older templates and custom
+creation and before booting a retained private disk. Every VM gets a Firecracker
-images require the explicit agent installation below. Restart a running Nest or
+vsock device by default. Agent files, VM identity configuration, the ownership
-UVM API server to load the new code before making these requests.
+manifest, and the enabled service are checked; an already-current installation
+does not rewrite the disk.
 
-For an existing VM, run these requests in order, checking each succeeds:
+Restart a running Nest or UVM API server to load the new code. Existing VMs pick
+up the setup on their next start or restart. For a currently running VM:
 
 ```sh
 curl --fail-with-body -X POST -H "X-UVM-Token: $UVM_API_TOKEN" \
-  "$UVM_API_URL/vms/$VM_ID/stop"
+  "$UVM_API_URL/vms/$VM_ID/restart"
-curl --fail-with-body -X POST -H "X-UVM-Token: $UVM_API_TOKEN" \
-  "$UVM_API_URL/vms/$VM_ID/agent/install"
-curl --fail-with-body -X POST -H "X-UVM-Token: $UVM_API_TOKEN" \
-  "$UVM_API_URL/vms/$VM_ID/start"
 ```
 
-Installation returns `{"id":"...","status":"installed","restart_required":true}`.
+The explicit `POST /vms/{vm_id}/agent/install` endpoint is available for manual
-It requires a cleanly stopped, proven-offline private disk and does not start the
+repair while stopped. It returns
-VM itself. Updates are checked on a sparse copy before publication. Guest files,
+`{"id":"...","status":"installed","restart_required":true}` and does not start
+the VM itself. All agent installation requires a proven-offline private disk;
+updates are checked on a sparse copy before publication. Guest files,
 credentials, and SSH keys are retained; customized agent files are preserved
 rather than overwritten. Repeating installation also upgrades unedited managed
 agent files using their recorded checksums.
@@ -1206,7 +1208,7 @@ The guest image must provide systemd and apt (Ubuntu 22.04 or newer is the
 supported baseline). If Python 3.10+ is missing, a bootstrap service installs
 `python3` inside the VM on its next boot. This one-time install needs guest DNS,
 internet access, and working apt repositories. The service retries failed startup;
-execution returns 503 until it can connect. New v4 templates already include
+execution returns 503 until it can connect. Current default templates already include
 the runtime and do not need this download.
 
 The guest kernel needs built-in `CONFIG_VSOCKETS=y`, `CONFIG_VIRTIO_VSOCKETS=y`,