Skip to content

Use templates

This page shows you how to create templates, clone VMs from them, and manage the templates installed on your Mac.

Restoring a macOS image takes several minutes: about four minutes for a 20 GB image. A template holds the result of that restore so that new VMs can clone it instead of restoring the image again. Cloning the disk is nearly instant; Pomme still boots each clone to install and verify its guest agent.

A template contains only the following:

  • The restored disk image.
  • The VM’s auxiliary storage.
  • The hardware model.
  • A manifest that records the restore image’s digest and the disk size.

A standard template has no guest agent, credential, owner account, or journal. When you create a VM from a template, Pomme clones the disk image and auxiliary storage with APFS copy-on-write, under a new machine identifier and UUID. Each clone therefore has its own identity, and clones from the same template can run at the same time.

After cloning, Pomme runs the same journaled agent installation and verification as any other creation. For details, see Durable creation and journals.

  • Install Pomme.
  • Choose a template name. Template names follow the same rules as VM names: 1 to 64 ASCII letters, digits, periods, underscores, and hyphens, starting with a letter or a digit.

To create a template, run pomme template create with a macOS source:

Terminal window
pomme template create TEMPLATE_NAME --latest --disk-size 40GB

Replace TEMPLATE_NAME with the name of the new template.

Instead of --latest, you can use --version VERSION or --restore-image IPSW_PATH, as described in Create a VM.

Choose the disk size carefully: every VM that you clone from the template inherits it. The default is 60GB.

The --memory flag sets the guest memory used only while Pomme restores the image. The default is 4GB. It doesn’t affect VMs cloned from the template.

To clone a VM from a template, run the following command:

Terminal window
pomme create VM_NAME --from-template TEMPLATE_NAME --memory 4GB

Replace the following:

  • VM_NAME: the name of the new VM.
  • TEMPLATE_NAME: the name of an installed template.

You set the VM’s memory when you create it. You can’t set a different disk size, because the clone uses the template’s disk.

The creation plan pins the template’s restore image digest. If the template is replaced before an interrupted creation resumes, the resume fails instead of using the new template.

To list installed templates, run the following command:

Terminal window
pomme template list

The output looks similar to the following:

NAME VERSION BUILD DISK OWNER SECURITY
base 26.6.2 25G83 40GB - default
mdm-ready 26.6.2 25G83 40GB pomme sip-off,amfi-off

The OWNER column shows the owner account of a provisioned template, or - for a standard template. The SECURITY column shows sip-off,amfi-off for a template captured with System Integrity Protection (SIP) turned off and the AMFI override on, or default otherwise.

In JSON output, agentCredentialRetained is true for a provisioned template that kept its guest agent’s credential. VMs cloned from it get their agent without booting Recovery. For details, see How clones get their agent.

Creating the owner account that an authenticated workflow such as mobile device management (MDM) enrollment needs is another slow step. A provisioned template captures that work too, so that a VM cloned from it can run MDM enrollment as its first command.

To create a provisioned template, add --provisioned:

Terminal window
pomme template create mdm-ready --latest --disk-size 40GB --provisioned

To build a provisioned template from an existing standard template instead of restoring the image again, add --from-template:

Terminal window
pomme template create mdm-ready --from-template base --provisioned

You can use --from-template only with --provisioned.

Pomme builds a temporary VM, prepares the pomme owner account with automatic login, turns off SIP, turns on the AMFI override, and captures the result as the template. It also copies the temporary VM’s guest agent credential into a login Keychain item that belongs to the template. If it can’t, it warns you and creates the template without the credential.

To enroll a VM cloned from a provisioned template, run the following commands:

Terminal window
pomme create lab --from-template mdm-ready
pomme mdm lab --profile enroll.mobileconfig

For more information, see Enroll a VM in MDM.

A VM cloned from a provisioned template already contains the guest agent that Pomme installed in the temporary VM. Pomme uses the credential that it kept for the template to install that agent in normal macOS, without booting Recovery:

  1. Pomme boots the clone in normal macOS and authenticates the agent with the template’s credential.
  2. Pomme replaces the agent with the signed agent that the VM’s creation plan pins, and gives it a new credential that belongs only to the clone. The template’s credential stops working in the clone.
  3. Pomme shuts the clone down, boots it again, and verifies the agent with the clone’s own credential, as it does for every VM.

If creation stops during these steps, pomme create VM_NAME --resume continues them. JSON output from pomme create reports "agentInstallMethod": "template".

Clones of a provisioned template that didn’t keep the credential, such as a template created by an earlier version of Pomme, install the agent through Recovery, as before. So do clones whose template you delete before their creation finishes.

The template doesn’t store the owner’s password, and Pomme never prints it. Because each clone has its own VM UUID, the Keychain item from the VM that the template was captured from can’t follow the clone. Instead, the root guest agent recovers the password from the clone’s own /etc/kcpassword file. Pomme adopts the password for the clone after it proves the account’s administrator membership, Secure Token, and APFS ownership. You don’t need to know the password.

To delete a template, run the following command:

Terminal window
pomme template delete TEMPLATE_NAME

Pomme asks you to confirm. To skip the confirmation, add --force.

Deleting a provisioned template also deletes the agent credential that Pomme kept for it from your login Keychain. Pomme needs the Keychain unlocked to do that, and it keeps the template otherwise. Unlock the Keychain, and then run the command again.

If the template’s manifest can’t be read, Pomme refuses to delete the template, because it can’t tell which Keychain item belongs to it. The command reports the template-manifest-invalid error.