Image system (IPSW + OCI images)

CiderStack uses Apple IPSW files as the source of truth for macOS, and wraps them in OCI-compatible images for versioning, distribution, and reuse across machines.

This guide covers how to add images (pull vs import), tagging conventions, and using a registry across your fleet.

IPSW vs image

You never run an IPSW directly; you create or pull an image (which references an IPSW), then create VMs from that image.

Adding images: pull vs import

Pull (from a registry)

Use pull when the image already exists in an OCI-compatible registry (your own or a team registry).

• Pros: No large download from Apple on each machine; same image ID and tag everywhere; good for fleets.
• Cons: Someone must have built and pushed the image first (usually via import on one host).

CLI:

cider pull ghcr.io/myorg/macos-base:latest
cider pull ghcr.io/myorg/image:tag --username user --password token

App: Images → pull from registry. Supply the image reference (e.g. myregistry.io/macos:15.0, ghcr.io/myorg/macos-images:sequoia-15.0.1).

After pull, the image is stored locally; create VMs with cider vm create myvm --image <tag-or-ref>.

Import (from an IPSW)

Use import when you have (or will download) an IPSW file and want to turn it into a CiderStack image on this host.

• Pros: Works offline; you control exactly which IPSW is used; no registry required for a single machine.
• Cons: IPSW files are large (10–15 GB); each host that needs that OS version must import or pull.

CLI:

# Download IPSW from Apple (optional)
cider ipsw download --latest
cider ipsw download --version 15.2 --output ~/Downloads
 
# Import IPSW as a local OCI image
cider image import /path/to/restore.ipsw
 
# List local images
cider image list

App: Images → add image → import IPSW (or download IPSW first, then import).

Typical flow:

1. Download the IPSW (cider ipsw download ...) or copy from another machine.
2. Import the IPSW (cider image import ...); CiderStack creates a local image.
3. Optionally push the VM or image to a registry so other hosts can pull (cider vm push myvm ghcr.io/myorg/image:tag).

Tagging conventions

Consistent tags make it clear what’s in an image and help automation.

Suggested patterns

• By macOS version

  • macos-14, macos-15, sequoia-15.0, sequoia-15.0.1
  • Good for: “I need Sonoma” or “I need Sequoia 15.0.1.”

• By purpose / stack

  • xcode-15-base, xcode-16-base, ci-runner-base
  • Good for: golden images for CI or development.

• By architecture

  • Some teams add arm64 when they have multi-arch registries: e.g. macos-15-arm64.
  • CiderStack is Apple Silicon only, so often omitted.

Examples

Use semantic, readable tags and avoid overwriting tags that production or CI rely on; prefer new tags for new builds (e.g. date or build id).

Using a registry across machines

Once images are in an OCI registry, every Mac in your fleet can pull the same image by tag.

Benefits

• One import, many pull: Import an IPSW (or build a golden image) once, push to the registry; all other hosts pull.
• Consistency: Same tag = same OS (and optionally same tools) on every host.
• Caching: Registries and local pull cache reduce repeated large transfers.
• Fleet Manager: When you scale with multiple Macs, a shared registry makes it easy to use the same base images everywhere.

Workflow

1. One host: Import IPSW (cider image import /path/to/restore.ipsw) or create a VM, install tools, then push it as an image: cider vm push myvm ghcr.io/myorg/image:tag.
2. Other hosts: Pull the image: cider pull ghcr.io/myorg/image:tag. Create VMs: cider vm create myvm --image <tag>.
3. Automation / CI: Use the same image reference in scripts and pipelines; no need to ship IPSW files.

Registry options

• Private registry: Any OCI-compatible registry (e.g. GitHub Container Registry, GitLab Registry, AWS ECR, self-hosted). Use for internal or proprietary images.
• Authentication: Use registry credentials (e.g. stored in Keychain or env) so CiderStack can pull from private registries.

Summary

• IPSW = Apple’s restore file; image = OCI artifact that contains an IPSW (and optional metadata/tags).
• Import: IPSW → local image (good for first-time setup, offline, or building the image you’ll push).
• Pull: Registry → local image (good for fleets and repeatable setups).
• Tagging: Use clear, consistent tags (e.g. macos-15.0, xcode-16-base) and avoid overwriting tags in use.
• Registry: Push once from one host, pull on every other Mac for consistent, cache-friendly image distribution across machines.

See also

• CLI Reference — All cider commands (image, ipsw, pull, push)
• Key Concepts — Host, VM, IPSW, image, snapshot, clone
• Quick Start — Create your first VM from an image
• Local GitHub runners — Golden images and ephemeral runners