SynVirt — Feature Inventory

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/FEATURES.md. Edit at the source, not here.

SynVirt — Feature Inventory

Document version: 0.15.0 · Audience: product, support, and contributors who need to know what the product does right now without reading code.

⚠️ Inventory drift (2026-06): the section-by-section detail below was last fully re-baselined at the 0.8.x surface and undercounts what 0.15.0 ships (data-plane splits R1 synvirt-network / R2 synvirt-storaged, migrator, snapshots + clone, telemetry, VNC + WebRTC Direct Console, cluster control plane, Backup P1, federation/Cloud). Until this file is re-baselined, treat CLAUDE.md §3 + CHANGELOG.md as the current-state source of truth.

This is a living inventory. If you ship a new capability, update the matching section the same PR. Deferred items at the bottom are the source of truth for the roadmap; each one should link (eventually) to an issue or a forthcoming master prompt.

1. Product summary

SynVirt is a turnkey on-premises hypervisor appliance:

Installs from a single live ISO onto bare metal or a lab VM
Boots a full Linux + KVM + libvirt stack, Open vSwitch for networking, and ZFS for storage
Exposes a browser dashboard (port 443) for operator use, a text-mode console on tty1 for appliance administration, and a REST API for automation
Runs fully offline after install — no cloud dependency, no CDN lookups, no telemetry

Currently-shipping version: 0.15.0 (e.g. build 0.15.0+build.1175).

2. Installation & first boot

Capability	Crate / asset	Surface
Bootable live ISO (BIOS + UEFI)	`iso-builder/live-build/` → `SynVirt-<version>-amd64.iso`	ISO file with checksum
Boot-time interactive TUI for pre-install config	`crates/live`	tty1
Browser-based install wizard	`crates/web-installer`	`http://<boot-ip>/` (pre-install)
Guided disk layout (OS disk + optional data pool)	`crates/web-installer/assets/install.js` + `crates/daemon/src/install/`	Wizard step + API
20 GB system partition (fixed since 0.7.6)	install planner	Automatic
Root-password PAM setup + seeded dashboard admin	`install.rs::seed_admin_record`	Wizard field
Boot splash with 12-step progress + recovery screen	`crates/boot-splash`	tty1
Interactive recovery (Retry / Reimport pool / Shell / Reboot)	`crates/boot-splash/src/recovery.rs`	tty1 on step failure

Offline guarantee: iso-builder/build.sh fetches Vue, Pinia, Tailwind, Lucide, Geist + JetBrains Mono fonts, xterm, and noVNC at build time. The appliance never reaches any of these CDNs at runtime.

3. Post-install operator surfaces

3.1 Web dashboard (Vue 3 SPA)

Crate: crates/web-ux/. Delivered by the daemon as static files on port 443. Architectural deep dive: docs/WEB_UX.md.

Screens (by hash route):

Route	Component	What it does
`#/`	`DashboardHome.js`	4-card “is everything OK?” summary
`#/vms`	`VmList.js` + `VmCard.js`	Live VM inventory with state pills
`#/vms/new`	`VmCreate.js`	Create-VM modal with smart defaults
`#/vms/:name`	`VmDetail.js`	Per-VM details + inline console + USB policy
`#/storage`	`StorageView.js`	Pool creation / destruction
`#/networks`	`NetworkView.js`	OVS bridge inventory (read-only)
`#/isos`	`IsoLibrary.js`	ISO upload / listing / delete
`#/settings`	`SettingsView.js`	Version + PAM session info

Cross-cutting features:

Live updates via server-sent events (/api/v1/events) — no polling
Toasts with 10 s undo window on destructive actions
Typed-name confirmation for deletions (type the resource name to enable the destroy button)
Command palette (CommandPalette.js, Ctrl+K)
Light theme as default (0.7.5); dark theme deferred
i18n-ready via assets/strings/en_us.json

3.2 Text-mode console on tty1 (post-install)

Crate: crates/console/ (renamed from dcui in 0.7.0). 20 screens on the primary VT after install:

#	Screen	Purpose
1	Dashboard	System summary
2	Lock	Screensaver / screen lock
3	Auth	PAM login
4	Config menu	Entry to configuration screens
5	Configure network	NIC selection + addressing
6	IPv4 edit	Static / DHCP settings
7	Test network	Ping / DNS check
8	DNS + hostname	DNS servers, search, hostname
9	NTP	Chrony config
10	Keyboard	Layout + variant
11	Restart agents	Systemd restart helpers
12	Logs	Unified journal viewer
13	Troubleshooting	Debug toggle entry point
14	Debug server config	Port + token
15	Debug server running	Active session listing
16	Debug server sessions	Historical sessions
17	USB export	Log bundle to USB stick
18	Factory reset	Wipe-to-fresh-install
19	Reboot / shutdown	Lifecycle
20	Maintenance mode	Operator-scheduled downtime

Colors: shared palette from crates/tui-theme/. Operates at 120×40 minimum; designs for 128×48 (1024×768 VGA at 8×16 font).

3.3 Debug HTTP server

Embedded in synvirt-console. Port 9443 with an XX-XXXX-XXXX one-time token. Paths:

Path	Purpose
`/debug/`	Index
`/debug/logs/live`	SSE stream of live journalctl
`/debug/logs/{daemon,libvirt,kernel}`	Category tail
`/debug/state`	JSON snapshot of host state
`/debug/bundle.tar.gz`	Full bundle (regenerates every 60 s)

USB export on console screen 17 writes the same bundle to a mounted USB stick with a SHA-256 verification step.

4. Virtual machines

4.1 Lifecycle

Operation	HTTP	Where
List	`GET /api/v1/vms`	`crates/daemon/src/api/vms.rs::list`
Detail	`GET /api/v1/vms/:name`	`vms.rs::get`
Create	`POST /api/v1/vms`	`vms.rs::create`
Start	`POST /api/v1/vms/:name/start`	`vms.rs::start`
Graceful shutdown	`POST /api/v1/vms/:name/shutdown`	`vms.rs::shutdown`
Force off	`POST /api/v1/vms/:name/force-off`	`vms.rs::force_off`
Reboot	`POST /api/v1/vms/:name/reboot`	`vms.rs::reboot`
Delete (+ storage)	`POST /api/v1/vms/:name/delete`	`vms.rs::delete`
Mount / eject ISO	`POST /api/v1/vms/:name/iso`	`vms.rs::change_iso` (0.7.9)
Get USB redirection policy	`GET /api/v1/vms/:name/usb-policy`	`api/usb_policy.rs` (0.8.0)
Set USB redirection policy	`PUT /api/v1/vms/:name/usb-policy`	`api/usb_policy.rs` (0.8.0)

VMs are created with smart defaults: 2 vCPU, 4 GB RAM, 40 GB disk, first available pool, vSwitch0, first ISO, start-now on. One click works for 80 % of first-time users.

4.2 Guest hardware profile (domain XML)

Generated by crates/synvirt-libvirt/src/xml.rs. Every VM gets:

KVM accelerated CPU (host-passthrough in prod; TCG fallback in dev when /dev/kvm is absent)
virtio disk(s) (qcow2 in 0.7.0 → zvol in 0.7.1+)
virtio NIC on an OVS bridge, optional VLAN
Guest agent channel (org.qemu.guest_agent.0)
virtio-vga for modern guests; std-vga fallback for legacy guests (Win 9x / NT / 2000) (0.9.0-alpha.2)
ich9 audio (HDA model) (0.8.0)
VNC listener bound to 127.0.0.1:5900+display; the browser reaches it through the console-gateway WebSocket bridge — never exposed on the network (0.9.0-alpha.1)

4.3 Browser guest console (0.9.0-alpha.1+)

Full spec: docs/console-architecture.md. Capabilities:

VNC web console powered by noVNC. Framebuffer, keyboard, mouse.
Zero client-side install — any modern browser works.
Pop-out window for multi-monitor setups.
Ticket-based auth (HS256 JWT, 30 s TTL, single-use nonce).
HMAC key rotates every 24 h with a 30-minute grace window.
VNC never exposed on the network — the gateway is the only path, dialing 127.0.0.1:5900+display per VM via libvirt’s vncdisplay.

5. Storage

Backed by ZFS. crates/storage-zfs is the planned trait-backed wrapper; 0.7.0–0.8.0 implementation lives directly in crates/daemon/src/api/storage.rs.

Operation	HTTP
List pools	`GET /api/v1/storage`
Create pool	`POST /api/v1/storage`
Destroy pool	`DELETE /api/v1/storage/:name` (refuses `rpool`)
List available physical disks	`GET /api/v1/available-disks`

Supported layouts on create: stripe, mirror, raidz1, raidz2, raidz3. Purpose-tuned defaults (recordsize, compression, atime) pick a profile suited to the advertised use (VMs, bulk data).

zpool set cachefile=/etc/zfs/zpool.cache is applied automatically so zfs-import-cache.service imports the pool at the next boot without manual intervention.

Not yet: pool extension from the dashboard (attach vdev, replace disk). Tracked for 0.8.x+.

6. Networking

Open vSwitch with VLAN and bond support. Currently read-only from the dashboard (NetworkView) — bridges are provisioned at install time or via the text-mode console.

Operation	HTTP
List bridges	`GET /api/v1/networks`

Provisioning path today:

Live TUI configures physical interfaces + DHCP/static at install time
Console screen 5 (Configure network) edits the netplan file on the running appliance

Not yet: bridge create/delete from the dashboard, bond management UI. Tracked as crates/ovs refactor.

7. ISO library

Crate: crates/daemon/src/api/isos.rs. Storage location on disk: /var/lib/libvirt/images/isos/.

Operation	HTTP
List	`GET /api/v1/isos`
Upload	`POST /api/v1/isos?name=<file>.iso` (streamed, 32 GiB cap)
Delete	`DELETE /api/v1/isos/:name`

Dashboard IsoLibrary.js shows an upload progress bar fed by the XMLHttpRequest upload progress events (fetch() has no equivalent on the request side).

8. Guest integration

8.1 Guest-tools ISO (0.9.0-alpha.2+)

Crate: crates/guest-tools-iso/ (lib + bin). Produces /opt/synvirt/isos/guest-tools.iso at appliance build time.

Contents:

Path inside ISO	Purpose
`/windows/virtio-win-*.iso`	Red Hat signed virtio driver disc
`/windows/synvirt-agent.exe`	SynVirt modern guest agent (Win 7+)
`/install.bat`	Silent virtio + SynVirt agent install
`/install.sh`	Debian/RHEL-family install of qemu-guest-agent + SynVirt agent
`/autorun.inf`	Legacy Windows autorun hint
`/README.txt`	Operator quickstart
`/manifest.json`	SHA-256 of every file + pinned upstream versions

Built with xorriso -as mkisofs -J -r (Joliet + Rock Ridge) so both Windows and Linux read long filenames. Pinned upstream versions live at the top of iso-builder/build.sh.

8.2 Guest agents (runtime)

Windows: virtio-win (paravirt disk, network, balloon, serial)
- SynVirt guest agent (Windows service)
Linux: qemu-guest-agent from distro repos (Debian-family apt, RHEL-family dnf/yum) + SynVirt guest agent (.deb / .rpm / pkg)

8.3 Capabilities enabled by agents

Graceful shutdown / reboot from the dashboard
Filesystem quiesce hook (future snapshot support)
IP address + hostname reporting back into VmDetail

9. Security

Area	Status
TLS on port 443	Self-signed cert at install, regeneratable
HTTP → HTTPS redirect	Host-header aware (0.7.6)
Dashboard auth	HTTP Basic Auth → PAM (`synvirt-daemon` service file)
Console TUI auth	PAM (`synvirt-console` service file)
First admin seeding	Root password from wizard → daemon PAM record
VNC network exposure	None. Bound to `127.0.0.1` per VM; the gateway is the only browser-facing path (0.9.0-alpha.1)
Ticket replay protection	UUID v4 nonce, atomic consume, dashmap (0.8.0)
Ticket TTL	30 seconds (0.8.0)
HMAC key rotation	24 h with 30-min grace window (0.8.0)
Cross-VM ticket reuse	JWT `sub=vm_uuid`, bridge enforces match (0.8.0)
Debug server access	Port 9443, `XX-XXXX-XXXX` token, operator-initiated only
RBAC / multi-user	Deferred (0.8.x or later)
Confidential computing (TDX / SEV-SNP)	Deferred (1.0)

10. Observability

Feature	Where
Structured `tracing` logs on every public async fn	daemon + console-gateway + libvirt wrapper
Trace IDs bubbled into error responses	`X-Trace-Id` header + JSON envelope `trace_id`
SSE `/api/v1/events` stream	daemon `events.rs`
Live log tail (SSE)	debug server `/debug/logs/live`
On-demand log bundle (tarball)	`/debug/bundle.tar.gz` or USB export
OpenAPI spec	`/api/v1/openapi.json` (autogenerated)
Swagger UI	`/docs`

Not yet: Prometheus metrics endpoint, time-series graphs (CPU / memory / disk). Tracked for 0.8.x+.

11. Appliance operations

Feature	Crate / path
Maintenance mode (lock write ops + banner)	`/var/lib/synvirt/maintenance.lock` + daemon middleware
Factory reset	Console screen 18
Reboot / shutdown	Console screen 19 + dashboard action
First-boot SSH drop-in (removed after first dashboard login)	`synvirt-debug-cleanup.service` gated on `/var/lib/synvirt/first-login.stamp`
Boot-step recovery on failure	`crates/boot-splash` recovery screen
Silent-fail-safe systemd enable	live-build hook + `install.rs` fallback

12. Platform support

Surface	Target
Host OS	Debian 13 (trixie)
CPU	Intel Haswell-EP or newer, AMD equivalent; VT-x + VT-d required
Storage	SATA + NVMe
NICs	1 / 10 GbE
RAM	32 GiB minimum
Guest OS	Any that supports KVM + virtio (Windows 10+, modern Linux, BSDs)
Browser	Evergreen Chromium-based + Firefox; WebUSB needs Chromium + HTTPS
Dev env	Debian 13 native (TCG fallback when `/dev/kvm` absent)

Hardware target is “servers 2015 and later.” The product differentiator is UX + backend quality, not hardware frontier features.

13. Deferred capabilities (not in 0.8.0)

Tracked for 0.8.x or later; order roughly by expected priority.

0.8.x

VM snapshots (create / revert / delete)
VM clone
CPU / memory / disk time-series graphs
Pool extension (attach vdev, replace disk) from dashboard
OVS bridge create / delete from dashboard
Bond management UI
Multi-user + basic RBAC
Backup role (S3 immutable, object lock) + crates/backup
Dark theme alternate

0.9

Replica role (async cross-cluster DR) + crates/replica
Live migration polish + UI
Predictive maintenance (local model, no cloud)
crates/compute trait + crates/compute-libvirt impl

1.0

Full role composition GA
Air-gap update via signed USB
Confidential computing (TDX / SEV-SNP) VMs
GPU passthrough UI with SR-IOV
i18n es_MX catalog

End of FEATURES.md. Keep in lockstep with what’s actually shipping. When a feature lands, move it out of §13 into its capability-specific section and cite the version.