Key Concepts
Before diving deeper into CiderStack, it helps to understand a few core concepts. These terms appear throughout the UI, CLI, and documentation. Once they click, the platform becomes very intuitive.
Host
A host is a physical Mac running CiderStack.
Examples include:
MacBook Pro
Mac Studio
Mac mini
Each host provides CPU, memory, storage, and networking resources for virtual machines.
Virtual Machine (VM)
A virtual machine (VM) is a fully isolated instance of macOS running on a host.
Each VM has:
Its own macOS installation
Dedicated CPU and memory allocation
Independent storage
Separate networking
Its own lifecycle and snapshots
VMs behave like real Macs — they can run Xcode, enroll in MDM, install updates, and reboot independently of the host.
IPSW (Apple Restore Image)
An IPSW is Apple’s official macOS restore image.
These files are published by Apple and are used to install macOS on both physical Macs and virtual machines.
CiderStack relies exclusively on real Apple IPSWs, which means:
No modified installers
No emulation layers
No third-party operating systems
Every macOS VM is installed using the same restore process Apple uses internally.
Images (OCI-based)
In CiderStack, an image is not the IPSW file itself.
Images are stored and distributed as OCI-compatible container images.
Each image contains:
A macOS IPSW
Metadata describing the operating system version and architecture
Versioned tags for repeatable builds
This allows CiderStack to manage macOS base images using modern container-style workflows.
Image sources
Images can be added in two ways:
Pulled from an OCI-compatible container registry
Created locally by importing an IPSW
Once available, images can be reused to create any number of virtual machines.
Why OCI images?
Using OCI-compatible images enables:
Versioned macOS base images
Reproducible VM builds
Fast image distribution across fleets
Registry-backed caching
Consistent environments between machines
This approach combines Apple’s native virtualization with modern infrastructure practices.
Example image tags
Each tag represents a fully defined macOS base image backed by an official Apple IPSW.
IPSW vs Image
IPSW
Apple’s macOS restore file
Image
OCI artifact containing an IPSW
Registry
Storage backend for images
Tag
Versioned macOS release
Snapshots
A snapshot is a point-in-time capture of a VM’s disk state.
Snapshots allow you to:
Roll back changes instantly
Test software safely
Preserve clean environments
Recover from failed updates
Snapshots are powered by APFS and are nearly instant to create.
Instant Clones
An instant clone is a new VM created from a snapshot.
Thanks to APFS copy-on-write:
Clones take seconds to create
Storage is shared until data changes
Multiple identical VMs can exist with minimal disk usage
This makes CiderStack ideal for CI runners and test environments.
Shared Folders
Shared folders allow directories on the host to be mounted directly inside a VM.
Common use cases include:
Sharing source code
Running build scripts
Accessing artifacts
Avoiding unnecessary file duplication
Changes are reflected immediately between host and VM.
Networking
Each VM includes built-in networking provided by macOS virtualization.
Depending on configuration, VMs can:
Access the internet
Reach internal services
Communicate with the host
Networking is isolated and requires no kernel extensions.
Fleet
A fleet is a group of Macs managed together.
Rather than managing VMs per machine, Fleet allows you to think in terms of:
Total available compute
Distributed VM placement
Central orchestration
A fleet may include one or many Apple Silicon Macs.
Manager Node
The manager node coordinates the fleet.
It is responsible for:
Tracking host capacity
Scheduling VM placement
Enforcing Apple’s VM limits
Handling orchestration requests
Typically, a fleet has a single manager.
Worker Node
A worker node is a Mac that runs virtual machines.
Worker nodes:
Execute VM workloads
Report available capacity
Can join or leave the fleet dynamically
Any Mac can function as a worker.
Apple VM limits
Apple enforces limits on the number of macOS virtual machines per physical host.
CiderStack automatically:
Detects host capabilities
Enforces Apple’s limits
Distributes workloads across available Macs
No manual balancing is required.
Orchestration
Orchestration allows you to manage multiple VMs as a single group.
Examples include:
Creating multiple VMs at once
Scaling CI runner pools
Destroying VM groups by name or prefix
Automatically placing workloads across hosts
Orchestration is available through the CLI and Fleet Manager.
Local-first design
CiderStack is designed to run entirely on your own infrastructure.
No required cloud services
No external control plane
No mandatory telemetry
Fleet communication occurs directly between your Macs.
Your infrastructure stays yours.
Summary
Host
Physical Mac
VM
macOS virtual machine
IPSW
Apple restore image
Image
OCI-based macOS base image
Snapshot
Point-in-time disk state
Clone
VM created from snapshot
Fleet
Group of Macs
Manager
Schedules workloads
Worker
Executes VMs
Orchestration
Multi-VM lifecycle control
What’s next
Now that you understand the core concepts, you can explore:
Snapshots & Instant Clones
Shared Folders
Networking
Fleet Manager
Orchestration commands
Last updated
Was this helpful?