Get started

Linux: 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 never runs through sudo.

sudo flashnet --mode nat --vm-id demo -- \
flash run --bundle /opt/flashvmm/bundles/current --id demo --vcpus 1 --mem-mib 512 \
--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=...); the guest applies it and reports net: eth0=<addr> gw ok dns <resolver> in flash logs. --uplink is optional for NAT (the default-route interface is used). The NIC rates are optional. Bridge, NAT, and routed modes are implemented directly. macOS and Windows: NAT networking is user-mode and needs no elevation or host configuration; a VM can have up to 8 NICs, each on its own NAT segment. See Networking & flashnet for the complete device model.

flash snapshot vm1 --path /var/tmp/vm1.snap
flash rm vm1
flash restore --from /var/tmp/vm1.snap --bundle /opt/flashvmm/bundles/current \
--id vm1 --vcpus 1 --mem-mib 512 --cpu-template host-raw

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

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/flashvmm/bundles/current \
--id replica-1 --vcpus 1 --mem-mib 512 --cpu-template host-raw \
--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.

flash fork branches a VM while it runs: every child continues from the parent's state at that instant — same memory, same running program — with its own identity. The parent keeps running. Start the parent with --forkable and the first fork freezes its RAM in place (no copy); every later fork saves only the pages that changed since.

flash run --bundle /opt/flashvmm/bundles/current --id parent --vcpus 1 --mem-mib 1024 \
  --cpu-template host-raw --forkable --entry /your/agent --detach
flash fork parent --count 3                 # parent-fork1..3
flash fork parent --count 8 --nic pool=web  # each child its own NIC from a flashnetd pool (Linux)
flash rm parent-fork1                       # a child is an ordinary VM

Measured on bare metal (first fork / later diff fork): Linux x86_64 1 GiB 318 ms / 15 ms; macOS 512 MiB 18 ms / 166 ms; Windows x64 ~80 ms / ~65 ms; Windows arm64 ~100 ms / ~85 ms; Raspberry Pi 5 720 ms / 318 ms. Same command on every platform.

flash sleep saves a running VM to a file and ends its process: while it sleeps it uses no memory and no CPU. flash wake brings it back under the same name, carrying on from the instant it slept, with its share, network rules, caps and secret proxies. flash ls shows sleeping VMs; flash rm deletes one. A sleeping VM survives a reboot.

flash sleep myvm
flash ls                                                          # myvm  sleeping
flash wake myvm                                                   # a VM with no network card
flashnet --mode nat --vm-id myvm -- flash wake myvm --nic '{NIC}'  # one that had a card gets one again

Linux x86_64 needs the VM started with --cpu-template, as for any snapshot. A VM with a GPU grant cannot sleep. Same command on every platform; MCP tools flash_sleep and flash_wake.

Work inside a running VM with no network and no SSH: flash exec, flash cp and flash del ride a dedicated virtio-console port straight to the guest agent.

flash exec vm1 -- sh -c 'uname -a; df -h'      # streams; exits with the command's code
flash exec vm1 --json --timeout 60 -- ./job.sh   # one JSON object: exit_code, stdout, stderr, state
flash cp ./data vm1:/work/data                   # files and whole trees, permissions kept
flash cp vm1:/work/out.csv ./out.csv
flash del vm1:/work/data -r                      # / is always refused
flash execs vm1                                  # every exec is a resource
flash execs vm1 7 --kill                         # killed; the record and its output stay
flash execs vm1 7 --rm                           # the record is removed

Up to 64 concurrent execs per VM; 16 MiB of output kept per stream (live streaming is uncapped); timeouts kill the whole process tree (default 300 s); up to 1 GiB per file. A 100 MiB copy round trip takes ~0.6 s on macOS, ~0.9 s on Windows x64 and ~1.7 s on Linux x86_64. The REST form is resource CRUD: POST/GET /v1/flashvm/guest/execs, PATCH {"state":"killed"} and DELETE on /guest/execs/{id}, and PUT/GET/DELETE /v1/flashvm/guest/files?path=.

Compare two VMs, or a snapshot and a VM, file by file. Every mount is compared, RAM-backed ones included; changed text files come with a line diff.

flash fork vm1 --id vm1-try                       # try something in a copy
flash diff vm1 vm1-try                            # added, deleted, renamed, modified, with line diffs
flash diff vm1 vm1-try --patch > fix.patch        # just the patch (patch -p1 from the guest root)
flash diff vm1 vm1-try --json                     # for tools; MCP: flash_diff
flash diff before.snap vm1 --bundle ./bundle --vcpus 1 --mem-mib 256   # a snapshot side

The kernel's own trees are always skipped; logs, caches and root's shell history are left out unless --all; --exclude PATH leaves out more. A snapshot side is read through a short-lived clone, removed when the command returns. Nothing is stored.

flash run ... --nic '{NIC}' --egress public          # the internet, nothing private (LAN, host, metadata)
flash run ... --nic '{NIC}' --egress 'deny:pastebin.com'                  # public minus a blocklist
flash run ... --nic '{NIC}' --egress 'allow:pypi.org,*.github.com,10.0.0.0/8'   # only these
flash run ... --nic '{NIC}' --egress-file policy.json                    # {"policy": "public", "deny": [...]}
flash set vm1 --egress none                                              # change it on the running VM
flash connections vm1            # every connection and DNS question: allowed, or REFUSED and why
flash connections vm1 --follow

# an API the VM can use but never holds the key for
flash run ... --nic '{NIC}' --egress none \
  --secret-proxy model=~/.keys/model,upstream=https://api.example.com,header=x-api-key,max-calls=200
#   inside the guest: $FLASH_PROXY_MODEL_URL  (http://<host>:7730/<token>/)
flash proxies vm1                # URL, caps, calls, bytes, refused
flash proxies vm1 model          # each call: method, path, status, bytes, ms
flash proxies vm1 model --max-calls none

Enforced in FlashVMM's own network path on Linux, macOS and Windows. Under allow: a name is reachable at the addresses the guest's own lookup returned; any other name is answered REFUSED before it leaves the host. The policy survives restore and fork, and flashnet pool create --egress gives it to every claim. Measured overhead: within noise. A secret proxy reaches the host whatever the policy; the key is read by flash, held only in FlashVMM's memory, and masked in anything the upstream echoes.

flashpoold keeps pools of parked spares; a claim wakes one in milliseconds. Only the shape is required.

flash pool create --vcpus 1 --mem-mib 512 --count 3 --wait-idle 120
flash pool ls
flash claim <member-id> --entry /your/workload        # add --cpu-millis / --disk-mib only to cap it

A GPU pool loads one AI model on the host's GPU once and shares it with every VM you allow. The VMs send it requests over their network card and get answers back; none of them touches the GPU or needs a driver. flashgpud runs the pools: Metal on Apple Silicon, Vulkan on Linux and Windows (NVIDIA, AMD and Intel alike). The model is any GGUF file.

flash gpu info                                  # backend (metal | vulkan | none), the GPU, its memory
flash gpu pool create --id qwen --model ~/models/qwen2.5-1.5b-instruct-q4_k_m.gguf --slots 4 --wait-ready 300

# a VM allowed to use it (flashnet's {NIC} gives the network card the pool is reached through)
flashnet --mode nat --vm-id agent1 -- flash run --id agent1 --vcpus 1 --mem-mib 512 \
  --nic '{NIC}' --gpu-pool qwen --entry /your/agent --detach

flash gpu grant ls --gpu-pool qwen              # which VMs may use it, requests running and waiting
flash gpu pool set qwen --slots 8               # more requests at once (the engine restarts only if a value changes)
flash gpu pool rm qwen

Inside the VM, the workload and every flash exec command get two variables: FLASH_GPU_URL (the pool's address) and FLASH_GPU_TOKEN (this VM's own key). The pool speaks the common chat-completions format:

curl -s "$FLASH_GPU_URL/chat/completions" \
  -H "Authorization: Bearer $FLASH_GPU_TOKEN" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Summarize this log in one line."}],"max_tokens":200}'
# add "stream": true for the answer token by token

No GPU? When flash gpu info says none, or the GPU can't run the model, create the pool with --gpu-layers 0: the same pool runs on the CPU and the VMs use it exactly the same way.

Measured from inside a VM, one request at a time, Qwen2.5 1.5B (Q4_K_M): about 258 tokens/s on an Apple M4 Max and about 67 tokens/s on a mini PC's integrated AMD Radeon 780M. --slots sets how many requests run at once; more wait in line, and requests from VMs that are gone are dropped. A VM holding a grant is not snapshotted or slept. Warm pools take --gpu-pool too. MCP tool flash_gpu; socket API in flashgpud-openapi.yaml beside the binary.

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; a cap that was not passed reads 0 (uncapped), and flash ls shows such a VM as uncapped. Use workload activity as the final readiness signal.

sudo flash self-update              # by hand, any time (Windows: elevated prompt, no sudo)
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

On Linux, automatic updates stay off until enabled; an update replaces the binaries in place and installs a new bundle in its own directory, and running VMs keep the files they already opened. On macOS and Windows (0.1.40 and later), flash self-update verifies the same signed release and installs the notarized .pkg or the .msi; on Windows it waits until no VMs are running. Re-running the install also works — a new MSI upgrades the old one in place.

Linux:

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

macOS: remove the installed files and the package receipt.

sudo rm -rf /opt/flashvmm /usr/local/bin/flash
sudo pkgutil --forget com.elysianedge.flashvmm

Windows: Settings → Apps → Installed apps → FlashVMM → Uninstall, or from an elevated prompt:

Get-CimInstance Win32_Product -Filter "Name='FlashVMM'" | Invoke-CimMethod -MethodName Uninstall