microVM guests

A microVM guest is an ordinary DNF host (zone IP, services, monitoring) running in a lightweight virtual machine, on another host of the fleet: the hypervisor. DNF relies on microvm.nix 🡕 and cloud-hypervisor. Typical use: a closed AI workspace per person or per team.

Declare a guest

Declare the host

The microvm-guest feature names the hypervisor, from the same zone. The static IP is mandatory: the interface and MAC address are derived from it. Like any host, the guest is only monitored with the monitoring-node feature.
etc/config.yaml
```
hosts:
  - hostname: "espace1"
    zone: "maison:1.40"
    profile: "ai-space"
    features: ["microvm-guest:serveur", "monitoring-node"]
```

Size it

Optional, 2 vCPU and 4096 Mio by default.

{
  darkone.system.microvm.guest = {
    vcpu = 4;
    mem = 6144; # Mio
  };
}

Pin the state version

A guest never goes through just install: create the file by hand, with the NixOS version of the first deployment.
usr/machines/espace1/install/state.nix
```
{ system.stateVersion = "26.05"; }
```
Initialize its secrets

The guest only reads its own secrets: see isolated hosts.
Fenêtre de terminal
```
just space-init espace1
```
Deploy the hypervisor
Fenêtre de terminal
```
just generate
just apply serveur
```

Deploy and update

A guest is not a deployment target: just apply <hypervisor> builds the guests, starts the new ones and restarts those that changed. Guests start with the hypervisor.

Item	Location
Persistent data	`/var/lib/microvms/<guest>/` on the hypervisor, closed to its accounts except root (`0770`) and mounted `nosuid,nodev`: a setuid file or a device created by the guest stays inert there
`/persist`, `/var/lib`, `/home`	virtiofs shares of this folder
Root `/`	In memory, wiped at each boot
Nix store	The hypervisor’s one in read-only, plus an in-memory layer for what the guest installs (`nix shell`, Home Manager), wiped at each boot

Network isolation

Each guest has its own vm-X-Y interface, routed in /32 by the hypervisor, which answers for it on the LAN (proxy ARP). The hypervisor’s link to the LAN is unchanged, there is no bridge.

Flow	Allowed
Guest → Internet	Yes
Guest → gateway DNS	Yes
Guest → LAN, tailnet, other guests	No
Guest → hypervisor	No
Gateway → guest	Yes (proxy, monitoring)
Other host → guest	Ping and SSH only

FAQ

How to connect to a guest?

Like any host, from an administration workstation: just enter <guest>. Its name is published by the gateways’ DNS, which must therefore be redeployed after adding the guest.

How to wipe a guest?

Remove it from etc/config.yaml, deploy the hypervisor, then delete /var/lib/microvms/<guest>/ on the hypervisor.