Fleet Manager Overview

Fleet Manager allows CiderStack to manage virtual machines across multiple Macs as a single distributed system. Instead of treating each Mac as an isolated host, Fleet Manager enables centralized con

Why Fleet Manager exists

Apple Silicon Macs are extremely capable, but Apple enforces a strict virtualization limit:

Only two macOS virtual machines may run concurrently per physical Mac.

This is a limitation of Apple’s Virtualization.framework, not CiderStack.

Fleet Manager exists to make this constraint manageable at scale.

By distributing workloads across multiple Macs, CiderStack allows you to:

• Run more VMs concurrently

• Centralize management

• Avoid manual balancing

• Scale horizontally using real Macs

---

What Fleet Manager provides

Fleet Manager enables:

• Centralized VM visibility

• Distributed VM placement

• Remote VM lifecycle management

• Secure node pairing

• Cross-host VM migration

• Remote command execution

• Fleet-wide image distribution

All without introducing a cloud control plane.

---

Architecture overview

Fleet Manager uses a manager / worker model.

┌───────────────────┐
│   Manager Node    │
│                   │
│  - UI & CLI       │
│  - Scheduling     │
│  - Orchestration  │
│  - Image control  │
└─────────▲─────────┘
          │ Secure RPC
          │
┌─────────┴─────────┐
│   Worker Node     │
│                   │
│  - Runs VMs       │
│  - Executes tasks │
│  - Hosts storage  │
└───────────────────┘

---

Manager node

The manager node acts as the control plane.

It is responsible for:

• Tracking connected worker nodes

• Monitoring available capacity

• Enforcing Apple’s VM limits

• Scheduling VM placement

• Coordinating migrations

• Dispatching remote commands

Typically, a single Mac runs as the manager.

---

Worker node

A worker node is any Mac capable of running virtual machines.

Worker nodes:

• Run macOS VMs locally

• Host VM disks and snapshots

• Execute commands on behalf of the manager

• Report status and capacity

Any Apple Silicon Mac can act as a worker.

---

Secure node pairing

Fleet nodes are paired using a secure handshake.

Pairing includes:

• One-time pairing codes

• Cryptographic node identities

• Mutual trust verification

Once paired, nodes communicate only with trusted fleet members.

No broadcast discovery or insecure networking is used.

---

Communication model

Fleet communication uses:

• Persistent RPC connections

• Encrypted transport

• Explicit trust stores

• No inbound internet exposure

All traffic stays within your network.

There is no external relay service.

---

VM placement and scheduling

When creating or starting a VM through Fleet Manager, CiderStack automatically:

• Evaluates available worker nodes

• Checks Apple’s per-host VM limit

• Selects a suitable node

• Executes the operation remotely

This process is automatic and transparent.

---

Cross-host VM migration

Fleet Manager supports live VM migration between nodes.

Migration includes:

• Disk images

• Auxiliary files

• Snapshot metadata

• VM configuration

During migration:

• Data is streamed securely

• Sparse files are optimized

• Integrity checks are verified

• Progress is tracked in real time

Once complete, the VM appears on the target node exactly as before.

---

Remote VM control

Fleet Manager allows full remote lifecycle management:

• Start and stop VMs

• Create VMs on remote nodes

• Clone VMs remotely

• Destroy VMs remotely

• Retrieve VM status

Operations behave the same as local VMs.

---

Remote command execution

Fleet supports remote command execution even when VMs are behind NAT.

Commands are proxied:

Manager → Worker RPC → Local VM

This enables:

• CI/CD workflows

• Remote automation

• Script execution

• Health checks

No inbound VM networking is required.

---

Fleet-wide image distribution

When using OCI images:

• Images can be pulled once and cached

• Tags remain consistent across nodes

• New workers can sync automatically

This ensures all VMs are built from identical macOS base images.

---

Fault tolerance

Fleet Manager is resilient by design:

• Workers can disconnect without data loss

• VMs remain local to their host

• Nodes can rejoin at any time

The manager does not own VM disks — workers do.

---

Licensing

Fleet Manager is available in Pro and Team tiers.

The free Personal tier supports:

• Local VMs

• Snapshots

• OCI images

Fleet features require an active license.

---

Typical fleet setups

Homelab

• 1 MacBook (manager)

• 2–4 Mac minis (workers)

CI build farm

• Mac Studio (manager)

• Multiple Mac minis (workers)

QA environment

• Dedicated manager node

• Ephemeral workers

• Snapshot-based cloning

---

Summary

Component	Role
Manager	Control plane
Worker	Executes VMs
Fleet	Trusted group of Macs
Scheduling	Automatic
Migration	Supported
Remote exec	Supported
Image sync	OCI-based
Cloud dependency	None

---

What’s next

From here you may want to explore:

• Fleet Setup & Pairing

• VM Migration

• Fleet Orchestration

• CLI Fleet Commands

• CI/CD Runner Guide