Live migration
Moving a running VM to another host without stopping it — what has to be true first, what the preflight checks, and the list of things that rule a guest out.
Live migration moves a running VM to another host in the cluster. The guest keeps serving while it happens, and is paused only for the final storage sync at the end.
It has real prerequisites, and most of the work is arranging them before you need to move anything. The good news is that the preflight will tell you exactly which one you have missed.
How it works
Two transfers happen at once, over different paths:
- Storage moves by incremental ZFS replication — the same mechanism as scheduled replication, so if you have been replicating this guest already, most of it is on the target before you start.
- RAM and device state stream directly to the target’s QEMU over the agents’ mutual TLS gRPC connection.
The guest runs through the bulk of both. It is paused only for the last incremental storage sync, which is small because everything before it has already moved.
What has to be true first
The cluster needs a common CPU model
This is the prerequisite people miss. A guest started with the host’s CPU passed straight through cannot be resumed on a machine that lacks those features — so a migratable guest runs on a CPU model that every host in the cluster can provide.
Work out that model and store it:
hoster cluster qemu-cpu calculate
hoster cluster qemu-cpu show
calculate inspects the cluster and writes the common model into the cluster
configuration; --dry-run computes and validates it without writing. Both take
--json.
Do this when the cluster is formed, and again whenever you add a host with a different processor — a new node with a smaller feature set changes what “common” means.
The guest has to opt in
At deploy time:
hoster vm deploy --os-template almalinux9 --name web-01 --live-migration-enabled
Or afterwards, for a guest that already exists:
hoster vm set-config live-migration web-01 --set-true
hoster vm set-config live-migration web-01 --set-false
The same setting has two different names. At deploy it is a flag,
--live-migration-enabled; afterwards it is aset-configsubcommand with--set-true/--set-false. Same property, two spellings — see Changing a guest after deploy, where the rest of that pattern lives.
Changing it on a running guest does not retrofit the CPU model onto the running QEMU process — the guest has to be restarted to pick it up.
Checking before committing
Run the preflight. It validates everything and prints the plan without moving anything:
hoster vm migrate web-01 --remote-host hoster0104 --preflight
hoster vm migrate web-01 --remote-host hoster0104 --preflight --json
Take a screenshot of `hoster vm migrate --preflight` output on a guest that passes, and another on one that fails, so both shapes are visible.
Migrating
hoster vm migrate web-01 --remote-host hoster0104
--ratelimit caps the storage sync in MB/s, which matters when the two hosts share a
link with something you care about more:
hoster vm migrate web-01 --remote-host hoster0104 --ratelimit 200
The target must be a cluster member. Migrating to a host that is merely reachable is not supported, and the command says so rather than trying.
What rules a guest out
The preflight checks all of these. They are worth reading before designing a guest you intend to move, because several are decisions made at deploy time:
| Requirement | Why |
|---|---|
| Live migration enabled, running the cluster’s common CPU model | the target must be able to execute what the guest is running |
| Exactly one enabled NIC, on an external network | the guest’s addressing has to be reproducible on the target |
| Target host has an enabled external bridge on the same subnet | the guest keeps its address, so the subnet has to exist there |
| Identical QEMU versions on both hosts | device state is not portable across versions |
| No PCI passthrough | a physical device cannot follow the guest |
| No nested virtualisation, TPM, Secure Boot, or VirtioFS shares | state that cannot be serialised and moved |
The passthrough one is the trade-off worth planning around: a guest with a GPU is a guest that lives on that machine. If a workload needs both hardware and mobility, it needs two guests.
MicroVMs cannot be live-migrated. There is no
hoster microvm migrate; the migration path is QEMU-specific. A microVM moves by replication and restart, not by migration — which is usually acceptable given how fast one boots, but it is a real difference from the parity the two guest types otherwise have.
When it fails
The preflight is the diagnostic. Run it with --json and the plan tells you which
requirement was not met, rather than leaving you to guess between “the network” and
“the guest”.
If a migration is interrupted, the guest is still on the source host — the design is to
keep running there until the final sync succeeds. Check with hoster vm list on both
hosts before trying anything else.
Next
- Clustering — migration is a cluster feature; this is where the cluster comes from.
- Snapshots, replication and the scheduler — replication is half the machinery here, and running it in advance makes a migration shorter.
- Restoring a guest — what to do when a guest cannot be moved and the host it is on is already gone.
Something unclear on this page?
Ask about this specific page and we will come back to you. Your question arrives with a link to it, so you do not have to describe where you were.