VM Migration (Deep Dive)
VM Migration allows a macOS virtual machine to be moved safely between Macs in a CiderStack fleet.
Migration transfers the full VM — disk images, metadata, auxiliary files, and snapshots — while preserving the VM’s identity and state.
This makes it possible to rebalance workloads, upgrade hardware, or recover from failures without rebuilding machines.
What VM migration includes
When a VM is migrated, CiderStack transfers:
Primary disk image
Auxiliary storage files
Hardware model and machine identifiers
Snapshot data and metadata
VM configuration (
vm.json)
After migration completes, the VM appears on the target node exactly as it did on the source.
What migration does not include
Migration does not:
Reinstall macOS
Regenerate machine identity
Modify snapshots
Change disk formats
Require IPSW re-download
The VM remains the same system — only its physical host changes.
When migration is useful
Common migration scenarios include:
Moving VMs to faster hardware
Draining a host for maintenance
Rebalancing Apple’s 2-VM runtime limit
Consolidating storage
Recovering from partial node failure
Scaling CI runner pools
Migration is fully supported for both GUI and CLI workflows.
Migration prerequisites
Before migrating a VM:
Both source and target nodes must be paired
Target node must have sufficient disk space
VM must be powered off
Network connectivity must be available
CiderStack will validate these conditions automatically.
High-level migration flow
Migration stages
1. Manifest creation
Before any data is transferred, CiderStack generates a migration manifest.
The manifest includes:
File paths
File sizes
Sparse regions
Checksums
Snapshot references
This ensures the migration is deterministic and verifiable.
2. Sparse file optimization
VM disk images are sparse files.
During migration:
Zero-filled regions are skipped
Only allocated blocks are transmitted
APFS holes are preserved
This significantly reduces transfer size and time.
3. Secure streaming
Migration data is streamed:
Over encrypted Fleet RPC connections
In bounded chunks
With progress reporting
No temporary files or shared storage are required.
4. Integrity verification
After transfer:
Checksums are validated
File sizes are verified
Manifest consistency is confirmed
If verification fails, the migration is aborted safely.
5. Registration on target node
Once validated:
Files are placed into the VM directory
Metadata paths are updated
The VM is registered locally
The VM is now owned by the target node.
Task tracking
All migrations appear in the Tasks panel.
Displayed information includes:
Current stage
Bytes transferred
Transfer speed
Estimated time remaining
Tasks continue running even if dialogs are closed.
VM identity preservation
During migration:
Machine identifiers remain unchanged
macOS activation is preserved
MDM enrollment remains valid
SSH keys remain intact
From macOS’s perspective, nothing has changed.
Snapshot handling
Snapshots are migrated as part of the VM.
This includes:
Snapshot disk layers
Snapshot metadata
Snapshot hierarchy
After migration:
All snapshots remain available
Restore points continue to function
Clone operations remain valid
Storage layout after migration
On the target node, files are placed into the standard structure:
Paths are automatically updated during import.
Performance considerations
Migration speed depends on:
Disk size actually in use
Network bandwidth
Storage performance
Snapshot depth
Sparse optimization often reduces transfer size by 70–90%.
GUI migration
To migrate a VM using the GUI:
Select the VM
Choose Migrate VM
Select a destination node
Confirm migration
Progress is displayed in real time.
CLI migration
CLI migrations use the same backend pipeline as the GUI.
Failure handling
If migration fails:
Source VM remains untouched
Partial data on target is cleaned up
No corruption occurs
You can retry the migration safely.
Best practices
Stop the VM cleanly before migration
Avoid migrating during heavy disk writes
Use wired networking when possible
Keep snapshots tidy for faster transfers
Ensure target disk has adequate free space
Security model
VM migration is:
Encrypted in transit
Authenticated per node
Restricted to trusted fleet members
Never exposed externally
No data is sent outside your network.
Summary
Transfer type
Streaming
Disk optimization
Sparse-aware
Encryption
Yes
Snapshot support
Full
Identity preserved
Yes
Downtime
VM must be powered off
GUI & CLI
Both supported
What’s next
After mastering migration, you may want to explore:
CI/CD Runner Workflows
Remote VM Creation
Fleet Monitoring
CLI Reference
Last updated
Was this helpful?