kstyagi/nest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: enhance guest agent setup and terminal support for microVMs

Browse Source
This commit is contained in:
kstyagi
2026-09-25 21:15:53 +05:30
parent 6573f483e6
commit a4e9cefbc3
3 changed files with 54 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
USAGE.md
+21 -19
View File
@@ -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
**Install / update terminal support**, and start it again. This uses the existing
stopped-disk agent upgrade endpoint. If the agent is still starting or installing
Python, wait for it to become ready before launching a session.
Vsock and the guest agent are set up automatically for every microVM during
creation and on each stopped-disk boot. This includes compatible older and custom
images. Restart an older VM once to apply the setup; **Sessions → Guest terminal
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`.
Rebuild it with `uvm install --force` using the checksum settings from the
installation section, then create new VMs. Cached older templates and custom
images require the explicit agent installation below. Restart a running Nest or
UVM API server to load the new code before making these requests.
The default Ubuntu template includes Python 3 and `uvm-agent.service`. UVM also
installs the service automatically on compatible older/custom images during
creation and before booting a retained private disk. Every VM gets a Firecracker
vsock device by default. Agent files, VM identity configuration, the ownership
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"
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"
"$UVM_API_URL/vms/$VM_ID/restart"
```
Installation returns `{"id":"...","status":"installed","restart_required":true}`.
It requires a cleanly stopped, proven-offline private disk and does not start the
VM itself. Updates are checked on a sparse copy before publication. Guest files,
The explicit `POST /vms/{vm_id}/agent/install` endpoint is available for manual
repair while stopped. It returns
`{"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`,