Install, run, inspect, snapshot, and restore

Developer

The installer provides the CLI, VMM, guest kernel, and root filesystem for x86_64 or aarch64. Use flash run to start a VM with explicit resource limits, and flashnet to configure networking without granting CAP_NET_ADMIN to the VMM process. VMs started with a CPU template can be captured, restored on another host, or cloned into copy-on-write replicas that resume from the captured state. The examples below were run on a clean machine; commands, output, and expected error messages are shown as observed.

Install

Requirements: a Linux x86_64 or aarch64 host with /dev/kvm available to the user who will run the VMs. The installer includes the guest kernel and root filesystem.

curl -fsSL https://release.flashvmm.com/dist/flashvmm/stable/install.sh | sudo bash

Component	Size	Purpose
`flash`	4.0 MB	Command-line interface
`flashvmm`	6.5 MB	VMM binary, one process per VM
`bzImage`	3.3 MB	Guest kernel
`rootfs.ext4`	67 MB	Guest root filesystem

Grant KVM access once with sudo usermod -aG kvm "$USER", then start a new login session. VM commands can then run without sudo; each user receives a private registry under $XDG_RUNTIME_DIR/flashvm.

sudo flash self-update --show-trust   # confirms the install is genuinely signed
flash --version
/opt/flashvm/bin/flashvmm --version   # flashvmm is not on PATH — flash finds it next to itself

Run a VM

flash run --bundle /opt/flashvm/bundles/current --id vm1 \
  --cpu-template host-raw \
  --disk-bps 100000000 --disk-iops 10000 \
  --entry "sleep 600"
flash ls
flash rm vm1

Disk limits must be explicit

--disk-bps and --disk-iops do not have default values. If either is omitted, the command returns a named argument error rather than choosing a limit on the operator's behalf.

CPU templates are required for snapshots

A VM can run without a template, but flash snapshot will refuse to capture it. Templates cannot be added after creation, so any VM that may need to be captured should start with one. host-raw exposes the host's CPUID to the guest.

Run with networking

flash does not create tap devices. The privileged flashnet helper creates the tap, drops its capabilities, and then executes an unprivileged flash run. The VMM itself does not run through sudo.

flashnet --mode nat --uplink eth0 --vm-id demo -- \
  flash run --bundle /opt/flashvmm/bundles/current --id demo \
  --disk-mib 256 --disk-bps 50000000 --disk-iops 5000 \
  --nic '{NIC},mbps=100,pps=20000,ingress-mbps=100' --entry /mnt/demo/hello.sh

{NIC} is replaced with the generated tap configuration: tap=NAME,ip=...,gateway=.... Bridge, NAT, and routed modes are implemented directly rather than delegated to another networking tool. See Networking & flashnet for the complete device model.

Snapshot and restore

flash snapshot vm1 --path /var/tmp/vm1.snap
flash rm vm1
flash restore --from /var/tmp/vm1.snap --bundle /opt/flashvm/bundles/current \
  --id vm1 --disk-bps 100000000 --disk-iops 10000

Restore returns a VM under the identity it had when captured. The original VM must be removed first, and --id must match the captured ID. A different ID returns a named identity-mismatch error.

Clone

clone creates a new VM from a snapshot, while restore brings back the VM that was originally captured. Clone accepts the same flags as restore, but its ID does not need to match the source, and the source VM can continue running.

flash clone --from /var/tmp/vm1.snap --bundle /opt/flashvm/bundles/current \
  --id replica-1 --disk-bps 100000000 --disk-iops 10000 \
  --nic tap=tap1,ip=10.110.0.11/24,gateway=10.110.0.1,mbps=1000,pps=100000,ingress-mbps=1000

Replicas share memory copy-on-write and resume from the captured execution state rather than booting from the beginning. In a measurement of ten 512 MiB replicas from one snapshot, the group used 3.4% of the memory required by ten private copies and resumed in 15–37 ms.

Inspect a running VM

flash metrics vm1     # one JSON object: cpu, memory, disk I/O, per-NIC bytes
flash inspect vm1     # the fuller view: caps, limits, cmdline, share, source

metrics returns a live sample. inspect adds the VM's configured limits and devices. Because flash run can report running before the guest's survival is known, check flash ls again after a short interval and use workload activity as the final readiness signal.

Update FlashVMM

sudo flash self-update              # by hand, any time
sudo flash self-update --dry-run    # see what's available first
sudo flash self-update --install-timer --interval 15min   # turn on auto-update — no reinstall needed

Automatic updates remain disabled until explicitly enabled. An update replaces the binaries in place and installs a new bundle in its own directory. Running VMs continue using the files they already opened; the new version applies to VMs started afterward.

Troubleshooting the install

Symptom	Cause and response
Installer exits 0, but the installation is incomplete	The installer can return 0 even when its initial update check fails. Confirm the installation with `flash --version` and `--show-trust`.
`cannot fetch …`	This can indicate a local write failure rather than a network problem. Check available storage with `df -h /`.
`manifest signature does not verify against this binary's trust anchor`	The installed binary trusts a different key from the one used to sign the release. Run the installation command again to establish the current trust anchor.
capture refused: no CPU template was requested	The VM was started without `--cpu-template`, which cannot be added later. Restart with at least `--cpu-template host-raw` before taking a snapshot.

Uninstall

sudo systemctl disable --now flashvm-self-update.timer
sudo rm -rf /opt/flashvm /var/lib/flashvm /usr/local/bin/flash \
            /etc/systemd/system/flashvm-self-update.{timer,service} \
            /var/lib/systemd/timers/stamp-flashvm-self-update.timer
sudo systemctl daemon-reload

Automate with MCP → Architecture

Command reference

`flash` CLI parameters

Every command and parameter below is available from the flash binary installed with FlashVMM. Required values, defaults, and creation-time constraints are called out where they affect how a command is used.

Complete command surface

Arguments shown without -- are positional. Run flash --help or flash <command> --help for the manual built into your installed version.

Command	Parameters	What it does
Global options
`flash`	`--dir PATH` `-h, --help` `-V, --version`	Selects the VM socket registry. The default is `/run/flashvm` for root and `$XDG_RUNTIME_DIR/flashvm` for other users. Help and version output are available globally.
Create, restore, and scale
`run`	`--bundle PATH` (required) `--disk-bps N` (required) `--disk-iops N` (required) `--id NAME` `--vcpus N` (default 1) `--mem-mib N` (default 512) `--mem-region-mib N` `--cpu-millis N` (default 1000) `--disk-mib N` (default 512) `--boot-grace-ms N` `--kernel-cmdline STRING` `--nic tap=NAME,mbps=N,pps=N,ingress-mbps=N[,ip=CIDR,gateway=ADDR]` (repeatable) `--share host_dir=DIR,tag=TAG,at=PATH` `--entry PATH` `--cpu-template NAME` `--vmm PATH` `--detach` `--pool`	Boots a FlashVM from a kernel and root filesystem bundle. Resource controls are applied when the VM is created; `--detach` returns after acceptance, while `--pool` prepares a warm spare for a later claim.
`restore`	`--from PATH` or `--from-url URL` `--total BYTES` (required with `--from-url`) `--bundle PATH` (required) `--disk-bps N` (required) `--disk-iops N` (required) `--id NAME` `--vcpus N` (default 1) `--mem-mib N` (default 512) `--cpu-millis N` (default 1000) `--disk-mib N` (default 512) `--nic SPEC` (repeatable) `--share SPEC` `--cpu-template NAME` `--vmm PATH` `--allow-bundle-mismatch` `--detach`	Rebuilds the captured VM from a local snapshot or a signed remote snapshot. The bundle and device configuration are supplied at restore time; CPU and memory topology must match the capture.
`clone`	Same parameters as `restore`	Creates a new FlashVM from a snapshot without changing the source VM. Give each clone its own ID and network identity.
`claim`	`id` `--entry PATH` `--entry-arg N` (default 0) `--disk-mib N` (required) `--cpu-millis N` (required) `--claim-id N`	Assigns a workload and its resource reservation to a warm spare created with `flash run --pool`, then wakes it for immediate use.
Operate and observe
`ls`	None	Lists the FlashVMs registered on the machine and reports the current state of each endpoint.
`logs`	`id` `--stream run\|console` `--since N` `--since-console N` `--limit N`	Reads a VM's workload log, guest console, or merged output. Cursor parameters support incremental collection without replaying earlier lines.
`inspect`	`id` `--nic INDEX`	Shows a VM's state, boot data, resource configuration, devices, share, and source. `--nic` adds detailed counters for one interface.
`metrics`	`id` `--window SECONDS`	Returns the VM's CPU, memory, disk, and network measurements in one call. `--window` sets the freshness limit for guest-reported fields.
`watch`	`id` `--stream lifecycle\|logs\|metrics\|guest` (default `lifecycle`) `--for SECONDS`	Streams lifecycle events, logs, metrics, or guest messages until interrupted or until the requested duration elapses.
`pause`	`id` `--max-ms N`	Freezes a guest for a bounded interval. The VM resumes automatically when the interval expires.
`resume`	`id`	Returns a paused guest to the running state.
`stop`	`id`	Stops the VM and closes its per-VM control socket.
`set`	`id` `--cpu-millis N` `--boot-grace-ms N` `--mem-mib N` `--disk-mib N` `--disk-bps N` `--disk-iops N` `--nic INDEX` `--mbps N` `--pps N` `--ingress-mbps N`	Updates live CPU, disk, or per-NIC limits. NIC rate parameters require `--nic`; a network rate of `0` removes that cap. Guest RAM is fixed at creation, so use `balloon` to reclaim pages, or `mem` to resize a reserved region live, while a VM is running.
`balloon`	`id` `--target-pages N`	Asks the guest to return memory pages to the host. Without a target, it reads the latest balloon request and result.
`mem`	`id` `--target-mib N`	Sets the live target for a virtio-mem region created with `--mem-region-mib`. Without a target, it reads the region's size, block granularity, requested size, and what's actually plugged in.
`snapshot`	`id` `--path PATH` (required)	Captures a VM's execution state to a snapshot file and waits for the operation to complete.
`snapshots ls`	`id`	Lists the snapshots created by a VM.
`snapshots show`	`id` `snapshot`	Shows one snapshot's identity, size, and base information.
`snapshots rm`	`id` `snapshot`	Deletes the selected snapshot.
Devices and workload access
`nic add`	`id` `--tap NAME`	Requests a NIC topology change. NICs are attached when a VM is created; use `run`, `restore`, or `clone --nic` to define them, and `set --nic` to change live rate limits.
`nic rm`	`id` `index`	Requests removal of a NIC by index. The VM's NIC topology remains fixed for its lifetime.
`share show`	`id`	Shows the VM's virtio-9p host-directory share.
`share add`	`id` `--host-dir PATH` `--tag NAME` `--guest-path PATH`	Requests a host-directory share. The share is a creation-time device; configure it with `run`, `restore`, or `clone --share`.
`share rm`	`id`	Requests removal of the virtio-9p share. Share topology remains fixed for the VM's lifetime.
`source show`	`id`	Shows the bundle, local snapshot, or remote snapshot source used to create the VM.
`source resign`	`id` `--url URL` (required) `--total BYTES` (required)	Replaces an expiring remote snapshot URL after confirming that the new URL identifies the same snapshot bytes.
`guest http`	`id` `path` `--method METHOD` (default `GET`) `--body STRING`	Sends an HTTP-style method, path, and body to the workload over the guest control channel.
`guest send`	`id` `topic` `payload` `--from N` (default 0)	Publishes a topic and payload to the workload with an optional sender identity.
`guest recv`	`id` `--for SECONDS`	Streams messages published by the guest until interrupted or until the requested duration elapses.
Lifecycle and maintenance
`version`	`id`	Reports the selected VM's VMM version and supported artifact formats. Use `flash --version` for the CLI version.
`rm`	`id`	Stops and removes a VM; the control socket disappearing confirms that the process is gone.
`reap`	None	Removes stale registry sockets whose VM process is no longer reachable while leaving inaccessible endpoints untouched.
`self-update`	`--dry-run` `--status` `--show-trust` `--install-timer` `--interval SPAN` (default `15min`) `--force`	Checks or installs the signed FlashVMM release, displays the compiled-in trust anchor, or enables scheduled updates. Artifacts are signature- and checksum-verified before replacement, and running VMs continue uninterrupted.