Creating VMs

Step by step on how to create VMs

On this page


  1. Install Anka and activate your license.
  2. Confirm your target macOS version is supported: Supported macOS versions.
  3. Create a VM (downloads IPSW, runs click scripts, installs macOS):
anka create --list                    # see available guest versions
anka create my-ci-vm 26.6.2           # VM name, then macOS version from --list
  1. When anka create finishes, the VM is stopped. User anka / password admin, SIP off, and VNC are already configured.
  2. Access the VM, modify resources, then optimize before pushing to a registry.

Creation can take 20–60+ minutes depending on download speed and macOS version. Use anka --debug create ... for verbose output.

Terms: A VM is the local object on the host. A tag is a named version of that VM. A template is what you store in a registry for CI. See VM clones and tags and Templates and Registries.

Prerequisites

anka commands run as your current user. Root and non-root users have separate VM libraries. Move VMs with export/import, the Anka Registry, or the Anka app.
  1. Anka Virtualization is installed.
  2. Network: The host needs outbound access to Apple endpoints for IPSW download and setup. See Apple’s documentation and whitelist required CDN URLs in corporate firewalls.
    • http_proxy / https_proxy do not work for anka create.
    • If you must block network during create, use ANKA_NETWORK_DISCONNECTED=true (see creation troubleshooting).
    • Antivirus (CrowdStrike, and similar) often blocks VM startup; disable or whitelist Anka.
  3. Hardware: The host must support the guest macOS version you want. See Supported macOS versions.
  4. ARM only: Use .ipsw files, not .app installers. Do not run sudo anka create over SSH; use VNC + Terminal or create as your normal user.
  5. ARM only: Guests built on macOS 15.x hosts do not run on 14.x hosts (14.x → 15.x is fine). This may be true with other macOS versions as it’s an incompatibility with host level APIs.

Headless hosts (CI nodes, SSH-only): After every host reboot, unlock the login keychain for the user that runs anka before anka create or anka start. Apple’s Virtualization APIs cannot access the keychain while it is locked, and VM create/start may fail (for example, “The virtual machine failed to start” or status 70). SSH alone does not unlock the keychain.

security unlock-keychain -p "${PW}" login.keychain-db

You do not need a GUI desktop session if you run this command (for example from a LaunchDaemon or your CI boot script).

When you can skip this: On a Mac where someone already signed in at the desktop after reboot, the login keychain is usually unlocked and this step is not needed.


Create with anka create

> anka create --help
usage: create [options] [name] [macOS version/installer file/installer url]

   Creates a VM Template

arguments:
  name                     VM name
  macOS version/installer file/installer url
                           MacOS version (see --list), installer file location, or installer URL to use for creation (example: 'latest')

options:
  -m,--ram-size <val>      Specify the VM RAM size (supported suffixes: T|G|M|K)
  -c,--cpu-count <val>     Specify the number of vCPU cores for the VM (3 or more is recommended)
  -d,--disk-size <val>     Specify the VM disk size (supported suffixes: T|G|M|K)
  --no-setup               Do not perform automated macOS setup
  -q,--quiet               Do not show progress
  -l,--list                List available macOS versions to install

You can bring your own .ipsw and .app files to use with anka create. This is an alternative to specifying the version from --list. It supports three different methods:

1. The specific macOS version from --list

ARM (Apple Silicon): anka create --list shows available .ipsw restore versions. Specify one by version number (for example 27.2.1) or use latest.

Intel: anka create --list shows archived macOS versions for .app installers as well as restore images.

bash$ anka create --list
+-----------------+---------+------------+
| version         | build   | post_date  |
+-----------------+---------+------------+
| 27.2.1 (latest) | 26B131  | 2026-11-09 |
+-----------------+---------+------------+
| 27.2            | 26B123  | 2026-10-26 |
+-----------------+---------+------------+
| 27.0.1          | 26A434  | 2026-09-28 |
+-----------------+---------+------------+
| 27.0            | 26A428  | 2026-09-14 |
. . .

bash$ anka create my-ci-vm 27.2.1
75% [|||||||||||||||||||||||||||||||||||||||||||||               ] 16:15 ETA
2. The location/path to the ipsw or .app on the host
bash$ anka create --cpu-count 5 --disk-size 100G 27.2.1 ~/Downloads/UniversalMac_27.2.1_26B131_Restore.ipsw
. . .

Intel only (.app installer):

bash$ anka create --cpu-count 5 --disk-size 100G 15.7.4 /Applications/macos-15.7.4.app
. . .
3. The URL to download the ipsw from (.app not supported)
bash$ anka create --cpu-count 5 --disk-size 100G 27.2.1 https://myCompanyIntranet/UniversalMac_27.2.1_26B131_Restore.ipsw
. . .
ARM USERS: The ipsw files will be downloaded into img_lib_dir. You can find the location of this directory with anka config img_lib_dir. These (and other temporary) files can be deleted with anka delete --cache.

A few tips when creating VMs:

  • We recommend naming your initial VM after the version of macOS.

  • Remember that VM templates are created under a specific user and will not be available to other users.

  • VM performance is important to our users. When setting CPUs for the VMs, 2 CPUs is usually not enough and can cause instability inside of the VM. Please see Modifying Your VM for more information.

  • If you experience issues, run anka --debug create. . . and provide it to Veertu’s support.

  • You can re-enable SIP on intel VMs with anka modify {vmNameOrUUID} set custom-variable sys.csr-active-config 0 post-create.

RAM, DISK, and CPU are all set from the defaults under the Anka configuration:

❯ anka config | grep default
| default_disk                | 137438953472                                                                      |
| default_nvcpu               | 4                                                                                 |
| default_ram                 | 4294967296                                                                        |
INTEL USERS: Suspending VMs can sometimes produce a VM which is frozen on start. Usually this is because the hardware & cpu type you created the VM and suspended it on is different from the one you’re trying to start it on. Be sure to suspend your VMs on the same hardware that will be running VMs.
Anka Develop license (default): While you can create as many VMs as you wish, the free Anka Develop license only allows you to run one VM at a time and will only function on laptops (Macbook, Macbook Pro, and Macbook Air). It only supports a stopped VM state.
Be aware of the user you’re executing Anka CLI commands as. If you create VMs as root, they won’t be available to other users on the system and vice versa.

After anka create, Anka sets up macOS, creates user anka with password admin, disables SIP, enables VNC, and stops the VM.

To create a VM from a file that also lists the OCI tags to pull, see Creating VMs with an Ankafile.


Reuse a macOS build

The first anka create for a macOS build still downloads the IPSW and installs it. After the install, Anka stores a tag named .base_<ProductBuild> on that VM and deletes the downloaded IPSW from the image library.

The next anka create for the same ProductBuild clones that tag. It does not download the IPSW again. The clone copies the tag onto the new VM, so later creates can still reuse the disk data after you delete the first VM.

❯ anka create vm1 latest
❯ anka create vm2 latest

vm1 installs from the IPSW. vm2 clones the stored tag.

latest and an explicit version or IPSW share a tag only when they resolve to the same ProductBuild.

FROM darwin:<version> in an Ankafile also uses this tag.

Set ANKA_CREATE_FORCE=1 to skip the stored tag and install from the IPSW again:

❯ ANKA_CREATE_FORCE=1 anka create vm3 latest

Child pages in this section:

TopicPage
Supported macOS versionsSupported macOS versions
Anka.app (GUI)Creating VMs (GUI)
Click Scripts feedClick Scripts feed
AnkafileCreating VMs with an Ankafile
Clones, tags, templatesClones and tags
Export and importExport and import
Host directory mountsHost directory mounts
Post-create tuningOptimizing your VM
RegistriesTemplates and Registries
Creation failuresVM creation is stuck or failing

What’s next?