feat: enhance guest agent setup and terminal support for microVMs

This commit is contained in:
2026-09-25 21:15:53 +05:30
parent 6573f483e6
commit a4e9cefbc3
3 changed files with 54 additions and 35 deletions
+17 -11
View File
@@ -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
terminal support → start** once. Newly built v5 Ubuntu images include terminal
support; cached v4 templates are upgraded during new-VM provisioning. The same
guest-agent/kernel requirements described below apply to terminals.
**Vsock and the guest agent are configured by default for every microVM.**
Creation installs and enables the agent on every compatible image, including
cached older templates and custom images. Each stopped-disk boot also installs
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
with `uvm install --force` using your configured checksums to include the agent
and Python in new VMs. Restart the management server to load these routes.
disabled and with an empty TCP allowlist. Every Firecracker boot attaches the
vsock device, and creation/start/restart/resize ensure the guest service is
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, preserving guest data and
credentials. If Python is missing, the installed bootstrap service acquires it
inside the guest on the next boot; this one-time step needs guest internet access.
Installation stages and verifies a private disk copy when changes are needed,
preserving guest data and credentials. If Python is missing, the installed
bootstrap service acquires it inside the guest on boot; this one-time step needs
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: