feat: Add guest execution agent and vsock support

- Introduced a standalone guest execution agent to facilitate command execution within the guest VM over Firecracker's vsock.
- Enhanced FirecrackerClient to support vsock configuration, validating guest CID and UDS path.
- Updated configuration to include vsock settings by default.
- Refactored FirecrackerProcessManager to manage runtime sockets more effectively.
- Implemented guest agent installation and provisioning in the image store.
- Added API endpoints for executing commands in the VM and installing the guest agent.
- Improved error handling for guest execution failures and agent availability.

README.md

@@ -339,6 +339,8 @@ The server exposes these routes:
 | `DELETE` | `/vms/{identifier}` | Delete a VM and release its resources; optional `timeout` query parameter |
 | `POST` | `/vms/{vm_id}/ports` | Set, open, or close private port rules for an exact VM ID |
 | `POST` | `/vms/{vm_id}/ports/sync` | Reapply a managed private port policy for an exact VM ID |
+| `POST` | `/vms/{vm_id}/exec` | Execute a command/script inside a running VM over vsock, with optional root privileges |
+| `POST` | `/vms/{vm_id}/agent/install` | Install/upgrade the execution agent on a stopped VM's private disk |
 | `GET` | `/vms/{identifier}/logs` | Read a bounded, non-following tail of a VM log |
 
 API port rules are objects such as `{"port": 80, "protocol": "HTTP"}`;
@@ -357,6 +359,39 @@ Bulk requests use an action (`start`, `stop`, `restart`, `delete`, or
 for each fixed target and do not prompt for confirmation. Interactive SSH
 remains CLI-only. The API and dashboard are not background reconcilers.
 
+### Execute Commands Without SSH
+
+Use an exact VM ID from create/list:
+
+```sh
+curl -X POST \
+  -H "X-UVM-Token: $UVM_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"command":"whoami","sudo":true,"timeout_seconds":60}' \
+  "http://127.0.0.1:8000/vms/<vm-id>/exec"
+```
+
+The response contains `exit_code`, `stdout`, `stderr`, `timed_out`, and
+`truncated`. Commands and multiline scripts run through `/bin/sh` inside the
+guest. `sudo: false` (the default) uses the VM's configured username; `true`
+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.
+
+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.
+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.
+
+See [execution examples and limits](USAGE.md#execute-commands-without-ssh) for
+programmatic calls, local script submission, timeout behavior, and upgrade steps.
+
 ### API Security
 
 The server controls privileged host operations. `UVM_API_TOKEN` is required
@@ -654,7 +689,7 @@ guest connectivity on an isolated Linux host.
 - No quotas or cgroup CPU, memory, I/O, or process limits are applied.
 - Firecracker is launched directly by this local CLI. Jailer/cgroup hardening
   is not implemented by the current command set.
-- No VM autostart, background reconciliation, guest readiness probing,
+- No VM autostart, background reconciliation, guest application health probing,
   snapshots, DHCP, public-port publishing, or multi-host scheduling.
 - The API uses one shared token, not users, roles, or tenants. UVM is not a
   hardened multi-tenant platform.