Images & Registries

CiderStack uses OCI-compatible images and registries to store and distribute macOS base images. This approach allows macOS virtual machines to be managed using the same modern workflows that power to

What is an image?

In CiderStack, an image is a versioned macOS base artifact.

An image contains:

• An official Apple macOS IPSW

• Metadata describing the OS version and architecture

• A tag identifying the image version

Images are immutable and reusable.

They are used as the starting point for creating virtual machines.

---

IPSW vs image

It’s important to distinguish between the two:

Term	Description
IPSW	Apple’s macOS restore file
Image	OCI artifact containing an IPSW
Registry	Storage backend for images
Tag	Versioned macOS release label

CiderStack never modifies IPSW files — it simply packages and distributes them safely using OCI standards.

---

Why OCI?

OCI (Open Container Initiative) defines an open standard for storing and distributing artifacts.

CiderStack uses OCI registries because they provide:

• Versioned image tags

• Content-addressed storage

• Built-in deduplication

• Secure distribution

• Familiar tooling

Although OCI is commonly associated with containers, it works extremely well for large binary artifacts, including macOS restore images.

---

What this enables

Using OCI registries allows CiderStack to:

• Avoid repeated IPSW downloads

• Share images across multiple Macs

• Cache images locally and remotely

• Ensure identical base OS versions

• Support reproducible VM builds

This is especially powerful in fleet and CI environments.

---

Example image tags

Images are referenced using familiar tag syntax:

macos-sonoma:14.4
macos-ventura:13.6
macos-sequoia-beta:15.0b

Each tag represents a specific macOS version backed by an official Apple IPSW.

---

Supported registries

CiderStack works with any OCI-compatible registry, including:

• Local on-prem registries

• Private registries

• Air-gapped registries

• Cloud container registries

No proprietary image service is required.

---

Pulling images

When an image is requested, CiderStack:

1. Checks the local cache

2. Pulls the image from the configured registry if needed

3. Verifies image integrity

4. Makes the image available for VM creation

Images are downloaded once and reused across all VMs on that host.

---

Pushing images

You can also publish images to a registry.

This enables:

• Prebuilt macOS base images

• Team-wide OS standardization

• Central image distribution

• Fleet-wide version consistency

A single image can be consumed by many Macs.

---

Image caching

Images are cached locally after being pulled.

This means:

• VMs can be created offline after download

• Fleet nodes avoid redundant transfers

• Storage is deduplicated automatically

Large IPSW files are stored only once per host.

---

Fleet-wide image distribution

When using Fleet Manager:

• Images can be pulled once and reused across nodes

• Multiple Macs share the same tagged image versions

• New nodes can synchronize images automatically

This ensures every VM in the fleet starts from the same base OS.

---

Security model

OCI images provide strong integrity guarantees:

• Content-addressed layers

• Digest verification

• Immutable tags (when enforced)

CiderStack validates image contents before use.

---

Image lifecycle

A typical lifecycle looks like:

1. Import or download IPSW

2. Package as an OCI image

3. Tag with macOS version

4. Push to registry

5. Pull across fleet

6. Create VMs from image

At no point is macOS modified or repackaged.

---

Designed for macOS virtualization

Although OCI registries are commonly used for containers, CiderStack uses them purely as a distribution mechanism, not a runtime environment.

macOS VMs still run using:

• Apple Virtualization.framework

• Native macOS restore workflows

• Real IPSW installation processes

OCI simply handles image transport and versioning.

---

Summary

Concept	Description
IPSW	Apple restore image
Image	OCI artifact containing IPSW
Registry	Image distribution backend
Tag	Versioned macOS release
Cache	Local image storage
Fleet	Shared image consumption

---

What’s next

Now that you understand images and registries, you can explore:

• Shared Folders

• Networking

• Fleet Manager Overview

• CI/CD workflows