SmechVisor Overview

SmechVisor is a sovereign bare-metal hypervisor OS — a stripped-down SmechOS base running OpenRC only, with cloud-hypervisor for direct KVM access and smechvisord as the web control plane. Install-only. No desktop environment. No package manager UI. No unnecessary services.

Architecture

Layer	Component	Notes
Init	OpenRC	No systemd — 30,000 lines vs 1.5M
VMM	cloud-hypervisor v42.0	Rust VMM, direct /dev/kvm, no QEMU
GPU daemon	vhost-user-gpu	Decoupled, VirtIO device ID 16, Unix socket
Control plane	smechvisord	Rust/Axum, port 8080, serves dashboard + REST API
Base	musl + Clang	Independent userland, no glibc dependency
Kernel	Linux 6.12.16	KVM, VFIO, vhost modules compiled in
Bootloader	GRUB 2.12	IOMMU enabled by default in boot cmdline
Updater	spk-visor	Live OTA + network deploy

OpenRC runlevel order

sysinit   → devfs, dmesg, udev, cgroups
boot      → modules, localmount, hostname, networking
default   → vhost-user-gpu → smechvisord
shutdown  → mount-ro, savecache, killprocs

Design decision SmechVisor is install-only — there is no live boot mode. This follows the same philosophy as Proxmox VE, VMware ESXi, and Hyper-V Server. A hypervisor OS running live from removable media has no reliable persistent state and no meaningful use case for production operation.

Installing

Method 1 — Install ISO (recommended)

The install ISO contains all packages on-disc. No internet connection required during installation.

Download the install ISO from visor.smech.xyz/downloads and verify its checksum.

Write to USB:

sudo dd if=smechvisor-install-*.iso of=/dev/sdX bs=4M status=progress && sync

Boot the target machine from the USB. The TUI installer launches automatically.
The wizard: select timezone → hardware detection → partition disk (cfdisk) → choose EFI/swap/root → install from ISO → install GRUB → reboot.
Remove USB. SmechVisor boots into OpenRC. The smechvisord control plane is available at http://<host-ip>:8080.

Method 2 — Network Deploy via spk-visor

If you already have a running SmechVisor node, you can deploy to additional machines over the network using the Deploy Shim ISO. See the spk-visor documentation for the full workflow.

Method 3 — smechvisord daemon only

If you already have a compatible musl + OpenRC base, you can run smechvisord standalone without a full SmechVisor install:

chmod +x smechvisord
SMECHVISORD_WEB_DIR=/usr/share/smechvisord/web \
SMECHVISORD_BIND=0.0.0.0:8080 \
./smechvisord

Dashboard

The smechvisord daemon serves a dark industrial web dashboard on port 8080. It has three views:

View	What it shows
Node Overview	CPU model and core count, total/used RAM, system uptime, KVM availability (`/dev/kvm`), running VMs list
Provision VM	Form to launch a new VM — CPU count, memory (MB), disk image path. Spawns cloud-hypervisor directly.
HW Settings	IOMMU status, VFIO PCIe passthrough toggle, "Restart to UEFI Firmware" button

Topbar status indicator

A pulsing green dot in the topbar confirms smechvisord is running and reachable. The indicator goes red if the API stops responding (page auto-polls every 5 seconds).

Environment variables

Variable	Default	Purpose
`SMECHVISORD_BIND`	`0.0.0.0:8080`	Listen address and port
`SMECHVISORD_WEB_DIR`	`/usr/share/smechvisord/web`	Path to dashboard static assets

IOMMU & VFIO

PCIe passthrough in SmechVisor requires IOMMU to be active. The VFIO toggle in the dashboard gates on a three-way check before enabling:

Virtualization extensions — checks /proc/cpuinfo for vmx (Intel VT-x) or svm (AMD-V).
IOMMU groups populated — checks /sys/kernel/iommu_groups for at least one group.
Kernel cmdline — checks /proc/cmdline for intel_iommu=on or amd_iommu=on.

If any check fails, the toggle is blocked and the dashboard offers to reboot directly into UEFI firmware settings to enable the relevant option in BIOS.

Note The SmechVisor GRUB config enables intel_iommu=on amd_iommu=on iommu=pt by default. On most hardware this means IOMMU is active out of the box after install — no manual GRUB editing required. You still need to enable VT-d / AMD-Vi in BIOS/UEFI.

Enabling VFIO

# Via the dashboard -- go to HW Settings and toggle VFIO
# Or via spk-visor (CLI) on the SmechVisor node:
# The dashboard calls POST /api/vfio which runs:
modprobe vfio-pci       # enable
modprobe -r vfio-pci    # disable

API Reference

All endpoints are served by smechvisord on port 8080. The dashboard at / consumes these endpoints directly.

Method	Path	Description
`GET`	`/api/node`	Returns JSON with CPU info, total/used RAM, uptime, KVM availability
`GET`	`/api/vms`	Returns JSON list of running VM processes with PID, CPU, memory
`POST`	`/api/vms`	Spawn a new VM. Body: `{"cpus": 2, "memory_mb": 4096, "disk": "/path/to/disk.img"}`
`GET`	`/api/iommu`	Returns IOMMU readiness: vtx/svm present, iommu_groups count, cmdline flags
`POST`	`/api/vfio`	Toggle VFIO. Body: `{"enable": true}`. Blocked if IOMMU not ready.
`POST`	`/api/reboot-uefi`	Writes EFI OsIndications variable to trigger reboot into firmware setup
`GET`	`/`	Serves the SmechVisor dashboard (static HTML/CSS/JS)

Example: get node info

curl http://<host-ip>:8080/api/node

{
  "cpu_model": "AMD Threadripper PRO 9965WX",
  "cpu_cores": 24,
  "memory_total_mb": 262144,
  "memory_used_mb": 4096,
  "uptime_seconds": 3600,
  "kvm_available": true
}

Example: spawn a VM

curl -X POST http://<host-ip>:8080/api/vms \
  -H "Content-Type: application/json" \
  -d '{"cpus": 4, "memory_mb": 8192, "disk": "/var/lib/smechvisord/vms/vm01.img"}'