> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update macOS by rebuilding on a new base image

> Move CI images to a new macOS version by rebuilding on MacStadium's base image for that version, instead of updating macOS inside an existing VM.

When you move CI to a new macOS version, rebuild your CI image on the base image for that version instead of running Software Update inside a VM you already have. A scripted rebuild is repeatable, starts clean, and avoids the problems in-place updates run into.

## Why not update in place

* **In-place updates to some versions currently fail inside VMs.** Updates to macOS 15.x and 26.x targets either never finish booting or leave the VM with capped memory. A workaround exists, but it adds steps to every update. See the known issue in the [Orka compatibility matrix](https://docs.macstadium.com/orka/orka-overview/compatibility-matrix.md).
* **Resized VMs can fail to update.** If your image was grown with `orka vm resize`, a macOS update inside it might fail. See the limitations in [Apple silicon Mac servers in Orka](https://docs.macstadium.com/orka/orka-resources/apple-silicon-based-support.md).
* **An updated image carries its history.** Leftover files, caches, and settings from every earlier version stay in the image. A rebuild contains only what your build script puts there.

## Script the image build

Keep the steps that turn a base image into your CI image in a script or a [Packer template](https://docs.macstadium.com/orka/orka-devops-integrations/packer.md): install Xcode and toolchains, configure macOS, then push. A macOS update then becomes:

1. Point the build at the base image for the new version, such as `ghcr.io/macstadium/orka-images/tahoe:<TAG>`, or `ghcr.io/macstadium/orka-images/golden-gate:latest` for macOS 27. The [orka-images repository](https://github.com/macstadium/orka-images) lists the available images and tags.
2. Run the build and push the result to a new versioned tag.
3. Deploy a VM from the new tag and run real jobs on it.
4. Point your pipelines at the new tag.

Keep the previous tag in your registry until the new one has run cleanly for a while, so you can roll back by switching the tag back.

## Check host requirements first

Each guest macOS version needs a minimum host macOS version. For example, macOS 27 guests need hosts on macOS 26.6.2 or later. Check the [Orka compatibility matrix](https://docs.macstadium.com/orka/orka-overview/compatibility-matrix.md) before you move, and contact [MacStadium support](mailto:support@macstadium.com) if your nodes need a host update first.

## Related pages

* [Orka compatibility matrix for macOS and hardware](https://docs.macstadium.com/orka/orka-overview/compatibility-matrix.md)
* [Packer plugin for automated Orka image builds](https://docs.macstadium.com/orka/orka-devops-integrations/packer.md)
* [Building a hardened custom image](https://docs.macstadium.com/orka/oci-images/building-a-hardened-custom-image.md)


## Related topics

- [Manage macOS VM images with the Orka CLI](https://docs.macstadium.com/orka/orka-cli-reference/image-management.md)
- [Start from a larger base image instead of resizing](https://docs.macstadium.com/orka/orka-best-practices/start-with-a-larger-disk.md)
- [VDI golden image management](https://docs.macstadium.com/remote-desktop-vdi/configuration/image-management.md)
- [MacStadium VDI day-2 operations guide](https://docs.macstadium.com/remote-desktop-vdi/operations/day-2-operations-guide.md)
- [Buildkite agents on Orka macOS VMs](https://docs.macstadium.com/orka/orka-devops-integrations/buildkite.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.