Preparing a build VM

Build a VM from a full base tag and thin tags on one producer host, or on each runner with an Ankafile

You can prepare a build VM on one producer host, or on each runner with an Ankafile.

anka create and from darwin: use the stored .base_<ProductBuild> tag. See Reuse a macOS build. The first create on a host downloads the IPSW. The next create for that ProductBuild on the same host clones that tag. A runner that only pulls the finished template receives macOS inside that template.

On a producer host

The order of the thin tags matters on the producer host. Start from a new VM, or from a vanilla full tag that you already have. Then pull each thin tag with --thin, in that order. Push the finished VM as a full tag. Do not use --thin on that last push. That composes the thin-tag stack into the final template. You do not start the VM to reinstall each tool.

Create a new VM:

❯ anka create build_vm 27.0.1
❯ anka pull --thin build_vm http://registry.example.com/v2/xcode:27.1
❯ anka pull --thin build_vm https://ghcr.io/homebrew/core/cmake:4.4.4
❯ anka push build_vm -t latest

Or pull a vanilla tag. Use this when the macOS base is already in a registry:

❯ anka pull 27.0.1 -t vanilla
❯ anka pull --thin 27.0.1 http://registry.example.com/v2/xcode:27.1
❯ anka pull --thin 27.0.1 https://ghcr.io/homebrew/core/cmake:4.4.4
❯ anka push 27.0.1 -t latest

To pull that vanilla tag from an OCI registry instead:

❯ anka pull 27.0.1 oci://registry.example.com/v2/27.0.1:vanilla

anka push uses the registry in ANKA_REGISTRY. To use a different registry, add the registry URL:

❯ anka push build_vm -t latest http://registry.example.com/v2

Leave push_mode at 1 (the default). Use --thin when you pull each thin tag. --thin on the final push would leave the macOS disk out, and a runner could not start the template. A push to the Anka Registry always includes the macOS disk.

A runner host does not have the thin tag order. It does not know which thin tags the producer used. It pulls the template as a full tag and starts it. That registry can be the Anka Registry. It can also be an OCI registry.

❯ anka pull build_vm
❯ anka start build_vm

On each runner with an Ankafile

An Ankafile stores the same steps, including the thin tag order. Each runner creates the VM from that file, so you do not need a producer host. The first FROM can create macOS, or pull a vanilla full tag. Push each tool as a thin tag with --thin so each later FROM line pulls one layer. The Ankafile composes the stack without starting the VM to install each tool by hand.

Create a new VM:

FROM darwin:27.0.1
FROM http://registry.example.com/v2/xcode:27.1
FROM https://ghcr.io/homebrew/core/cmake:4.4.4
FROM oci://hf.co/MaziyarPanahi/Llama-3.2-1B-Instruct-GGUF:Q4_K_M

Or pull a vanilla tag:

FROM oci://registry.example.com/v2/27.0.1:vanilla
FROM http://registry.example.com/v2/xcode:27.1
FROM https://ghcr.io/homebrew/core/cmake:4.4.4
FROM oci://hf.co/MaziyarPanahi/Llama-3.2-1B-Instruct-GGUF:Q4_K_M

❯ anka create build_vm ./Ankafile

For all Ankafile instructions, see Creating VMs with an Ankafile.