Release notes
This page lists changes in each version of Pomme, newest first.
Pomme 0.5.0
Section titled “Pomme 0.5.0”Pomme 0.5.0 adds pomme install, which installs a macOS installer package
from the host in a running VM, and fixes Backspace in guest terminals after
you switch users. Like 0.4.1, it’s beta software, and it was released before
the release qualification matrices for Tahoe and Sequoia ran. For what
qualification covers, see
Supported macOS versions.
To update, run pomme update.
Features
Section titled “Features”pomme install VM_NAME --pkg PATHinstalls a flat macOS installer package from the host in a running VM. Pomme copies the package into a new root-only folder in the guest, runs/usr/sbin/installerasrootwith the startup volume as the target, and removes the copy afterwards. Pomme waits up to 30 minutes for the installer unless you pass--timeout. If the wait ends first, the installer keeps running in the guest and Pomme leaves the copy in place. A failed installation prints the installer’s output, reportsguest-package-install-failed, and exits with the installer’s status. For details, see Install packages.
- In
pomme shellandpomme exec --pty, Backspace now erases characters on the screen after you switch to another user, for example withsu - pomme. The guest terminal had noTERM, so zsh redrew each erased character as a space. Pomme now setsTERMto the host’s terminal type when macOS includes a description of it, and toxterm-256colorotherwise. To choose a different type, pass--env TERM=VALUE. For details, see Run guest commands.
Pomme 0.4.1
Section titled “Pomme 0.4.1”Pomme 0.4.1 fixes failures in pomme amfi enable, pomme amfi disable,
pomme create, and pomme template create --provisioned. Like 0.4.0, it’s
beta software, and it was released before the release qualification matrices
for Tahoe and Sequoia ran. For what qualification covers, see
Supported macOS versions.
To update, run pomme update.
pomme amfi disableno longer fails withsecurity-operation-pendingwhen you run it again afterpomme amfi enableand a SIP change. Pomme required the boot policy to match the one it saw when it finished enabling AMFI, byte for byte, butpomme sip enableandpomme sip disablerewrite the policy. Pomme now recognizes a finished enable from its own record and the unchanged boot arguments. To finish an operation that already stopped with this error, update Pomme and run the command that the error suggests, such aspomme amfi disable NAME --final-state previous. The VM keeps its earlier agent until the operation finishes, so if the command then fails withsecurity-change-unverified, run it again.pomme amfi enableandpomme amfi disableno longer fail withsecurity-change-unverifiedwhen they continue a few seconds after they restart the VM. Right after a boot,diskutilcan return incomplete information about the startup volume, so the guest now repeats its read-only checks for up to 15 seconds before it refuses.pomme createno longer fails withprovisioning-phase-failedwhen installing the Pomme agent in Recovery takes longer than 5 seconds, for example on a busy host. The installation now gets 30 seconds.pomme template create --provisioned,pomme sip disable, and the other commands that create the owner account wait up to 30 seconds for macOS to report the new account as a volume owner, as intended. A retry limit ended the wait after about 3 seconds, and a provisioned macOS 26.6.2 template failed with “Pomme couldn’t parse the guest’s report of the startup volume’s owners.” When that report still doesn’t parse, the unified log now records its layout but leaves out identifiers and other values that could identify an account.
Pomme 0.4.0
Section titled “Pomme 0.4.0”Pomme 0.4.0 writes its diagnostics to the host’s unified log, and makes
pomme sip disable and the other commands that leave Recovery faster. A stop
from Recovery now takes under a second when the Pomme agent in Recovery is
connected, instead of 30 seconds. pomme sip disable, pomme amfi disable,
and pomme mdm no longer ask before they create the owner account on a fresh
VM. Like 0.3.0, it’s beta software, and it was released before the release
qualification matrices for Tahoe and Sequoia ran. For what qualification
covers, see
Supported macOS versions.
To update, run pomme update.
Features
Section titled “Features”- Pomme writes its diagnostics to the host’s unified log under the subsystem
com.github.weswhet.pomme, so you can read what a failed command did after its Terminal window is closed. The log records each command’s start and end, progress steps, warnings, and reported errors with their error codes, and leaves out passwords, tokens, and other secrets. For the commands that read it, see Collect Pomme’s logs.
pomme sip disable,pomme amfi disable, andpomme mdmno longer ask before they create thepommeowner account on a verified fresh VM, such as a macOS 26 VM thatpomme createmade. Pomme creates an owner only on a VM that nobody has set up, so the question added nothing.-fand--forceare still accepted but have no effect, and thesecurity-confirmation-requirederror is gone.pomme create --experimental-recoveryno longer prints “Pomme couldn’t record the agent installation attempt” for macOS 27 VMs. The message was harmless: creation still verified the agent and finished.pomme restartno longer fails with “No running VM helper is listening” when it stops a running VM. The start could find the stopped VM’s helper before it finished exiting.pomme startright afterpomme stophad the same problem.- For a VM created with
--experimental-recovery,pomme restart --mode recoveryand the commands that boot Recovery, such aspomme sip disable, let the guest shut itself down in a few seconds before the Recovery boot, instead of waiting up to 30 seconds and then powering it off. - A stop from Recovery no longer waits 30 seconds before it powers the VM
off. When the Pomme agent in Recovery is connected, as it always is for a
VM created with
--experimental-recovery, Pomme runssyncin the guest first and then powers the VM off.pomme stop,pomme restart, and the commands that leave Recovery, such aspomme sip disable, finish up to 30 seconds sooner.
Pomme 0.3.0
Section titled “Pomme 0.3.0”Pomme 0.3.0 boots macOS Recovery only for changes that macOS allows nowhere
else, and does everything else in normal macOS through the guest agent. Status
checks, AMFI changes, and new clones of provisioned templates no longer boot
Recovery, and a typical pomme mdm enrollment boots it once instead of five
times. It also adds an experimental way to reach Recovery without navigating
its screens, and a repair for VMs that a guest update left short of memory.
Like 0.2.3, it’s beta software, and it was released before the release
qualification matrices for Tahoe and Sequoia ran. For what qualification
covers, see
Supported macOS versions.
To update, run pomme update.
Features
Section titled “Features”pomme create --experimental-recoveryprepares the new VM’s Recovery image on the host with an embedded agent that starts on its own, so Pomme reaches a Recovery terminal without navigating Recovery’s screens. Pomme keeps the original image for normal boots and switches images only while the VM is stopped. The prepared image’s seal is broken, though SIP and AMFI don’t change, and a macOS update in the guest returns the VM to the standard Recovery route. The flag works with direct creation and config batches, and--resumekeeps the choice. For details, see Try experimental image preparation.pomme firmware inspectandpomme firmware repairfind and fix a VM that a macOS 26.7 or 15.8 update in the guest left with about 1.75 GB of memory, an update that never finishes, and a Recovery that doesn’t start. The update installs the macOS 27 boot firmware, and the repair restores the firmware that the VM was installed with, after it saves a backup.pomme inspectnow reports a VM’s boot firmware, and Pomme warns before it boots such a VM into Recovery. For details, see A guest update hangs and the VM has less memory.
Changes
Section titled “Changes”pomme sip statusandpomme amfi statusread the configuration through the guest agent in normal macOS from any starting state. A stopped, paused, or Recovery VM starts normal macOS for the check instead of Recovery, and then returns to the state that--final-staterequests. JSON output reports"source": "normalAgent". For details, see Check the current status.pomme amfi disableandpomme amfi enabledon’t boot Recovery on a VM whose SIP you turned off withpomme sip disable, because that boot policy already allows custom boot arguments. Pomme changes the LocalPolicy in Recovery only for a different boot policy. This needs a guest agent from this release; runpomme agent update VM_NAMEto update an existing VM.pomme mdmreads AMFI through the guest agent before and during enrollment, so turning off SIP is the only step that boots Recovery.- A VM cloned from a template that you create with
pomme template create --provisionedgets its agent in normal macOS instead of Recovery. The template keeps its agent’s credential in your login Keychain, andpomme template listreports it inagentCredentialRetained. Clones of templates created with an earlier release still use Recovery. For details, see Use templates. pomme create --resumeandpomme agent repairfirst check whether normal macOS can prove an agent that an interrupted installation already put in place, and boot Recovery only when it can’t.- Hosts and guests on macOS 27 or later use first-boot provisioning instead of a Recovery agent installation, as long as the guest is no newer than the host. Before, only macOS 27 guests did.
- On a macOS build that Recovery automation doesn’t support, only
pomme sip disableis refused up front.pomme sip enable, status checks, and AMFI changes on the standard boot policy run there. --final-state previousleaves a VM that was paused in Recovery stopped, instead of booting Recovery only to pause it again. If Pomme can’t reach a requested final state after a Recovery session, it no longer boots Recovery again on the way back.- The progress spinner on an interactive terminal spells
pommein lowercase letters, one letter at a time. It draws each letter one dot at a time in its own color and then replaces it with the next, which starts beside the dot where the last one ended. The spinner is one column wider than before.--progress plainoutput is unchanged.
- Creating a VM from a template no longer fails with “A host operation failed” when the restore image that the template came from has since been removed from the Mac. A clone copies the template’s installed disk and doesn’t need the image.
- The guest agent’s AMFI status read in normal macOS could time out after 5 seconds just after the guest started, so Pomme used Recovery instead. It now has the same time limit as the other AMFI operations.
Pomme 0.2.3
Section titled “Pomme 0.2.3”Pomme 0.2.3 fixes macOS 27 VM creation and lets pomme delete --force delete
a VM whose provisioning records don’t match. Like 0.2.2, it’s beta software,
and it was released before the release qualification matrices for Tahoe and
Sequoia ran. For what qualification covers, see
Supported macOS versions.
To update, run pomme update.
- Creating a macOS 27 VM no longer fails right after the guest restarts with “Pomme couldn’t pass the owner’s credential to a guest command.” The guest’s directory service can take more than 5 seconds to check the owner’s password just after it starts, and Pomme stopped waiting at 5 seconds. It now waits up to 30 seconds.
pomme delete NAME --forcedeletes a VM whose provisioning records don’t match its bundle, such as a bundle that was moved or copied. Before, it stopped withprovisioning-ownership-mismatch, and the error’s hint suggested the same command. Pomme removes only the bundle and keeps the VM’s Keychain items, because it can’t prove which items are the VM’s. JSON output reports this in the newcredentialsRetainedfield. For details, see Deleting a VM.
Pomme 0.2.2
Section titled “Pomme 0.2.2”Pomme 0.2.2 lets an MDM-enrolled VM on macOS 27 receive push commands.
Like 0.2.1, it’s beta software, and it was released before the release
qualification matrices for Tahoe and Sequoia ran. For what qualification
covers, see
Supported macOS versions.
To update, run pomme update.
- On macOS 27, an MDM-enrolled VM can receive push commands. macOS 27 skips
a boot task in a VM, so the guest couldn’t create its push identity and never
sent
TokenUpdate. The Pomme agent now runs that task at every startup, andpomme mdmleaves SIP off on macOS 27, which the task needs. The result reportspushIdentity. For details, see Receive push commands on macOS 27.
Pomme 0.2.1
Section titled “Pomme 0.2.1”Pomme 0.2.1 gives every error a stable code, adds pomme bug-report, and
checks free space before it creates a VM. Like 0.2.0, it’s beta software, and
it was released before the release qualification matrices for Tahoe and
Sequoia ran. For what qualification covers, see
Supported macOS versions.
To update, run pomme update.
Features
Section titled “Features”- Every error now has a stable code, such as
vm-not-found. Pomme prints it after the message, with a link to its entry on the new Errors page, which describes each code’s cause and resolution. pomme bug-report [NAME]collects the Pomme version, this Mac’s details, the last error, and a VM’s inspect output, helper logs, and guest logs into one redacted Markdown file to attach to an issue. It never uploads anything.- In JSON and JSONL output, every failed result has
errorCode,hint, andcausesfields. For details, see Structured output. - The documentation site has a Crawler mode: the switch next to the theme selector retells the guides in the voice of a sarcastic game-show System. Its facts, commands, and examples match the normal pages, and pages that it doesn’t retell show their normal text.
Changes
Section titled “Changes”- Error messages say what happened, give the operating-system or framework reason when there is one, and name the next step. For example, a guest command that doesn’t exist reports the missing path instead of “The requested operation could not be completed,” and a failed creation phase names the phase and its cause.
- With
--format jsonor--format jsonl, an error that stops a command before it starts an operation, such as a VM that doesn’t exist, now prints a failed result on standard output. Before, standard output stayed empty. - A command that acts on several VMs, such as
pomme stop a b, finishes every VM when one of them fails, and reports each failure in that VM’s result. Before, it stopped at the first error. - When a VM helper starts, Pomme keeps the previous helper’s log as
pomme-helper.previous.loginstead of erasing it. Each log starts with the Pomme version, the host’s macOS version, and the boot mode, and it records every failed request with its error code. pomme log --lastand other flags report the flag and the rule that a value broke, instead of an unknown control command.pomme createandpomme template createcheck free space before they download or write anything, and stop with thehost-disk-space-insufficienterror when a volume doesn’t have room for the rest of the restore image and the installed system. A config batch is checked as a whole. Before, creation could download and install for a long time before it ran out of space. A dry run reports the check in itsdiskSpacefield.
Pomme 0.2.0
Section titled “Pomme 0.2.0”Pomme 0.2.0 fixes pomme start on a paused VM and redraws the progress
spinner. Like 0.1.0, it’s beta software, and it was released before the
release qualification matrices for Tahoe and Sequoia ran. For what
qualification covers, see
Supported macOS versions.
To update, run pomme update.
pomme startnow resumes a paused VM, as its help describes. Before, it left the VM paused, waited for the guest agent until--timeoutelapsed, and then reported that the agent didn’t connect. Its JSON output includes"resumed": truewhen it resumed the VM. If the VM is paused in the other boot mode,startreports that it’s paused instead of running.
Changes
Section titled “Changes”- The progress line on an interactive terminal shows a square spinner whose
dots fill in and empty as they swirl around it, in a new color each lap.
The elapsed time now appears right after the spinner, ahead of the VM name
and the current step. The spinner also advances at a steady rate; before,
macOS could delay its timer and skip frames.
--progress plainoutput is unchanged.
Pomme 0.1.0
Section titled “Pomme 0.1.0”Pomme 0.1.0 is the first release of Pomme. It’s beta software, and it was
released before the release qualification matrices for Tahoe and Sequoia were
complete. For what qualification covers, see
Supported macOS versions.
Each change to the main branch that passes CI also publishes an alpha, such
as 0.1.0-alpha.3.
Pomme 0.1.0 begins with an independent history and its own host, control, guest agent, Recovery, packaging, and state identity.
Features
Section titled “Features”- The
pommecommand creates and controls Pomme-owned macOS VMs. Normal macOS runs the persistent, authenticated Pomme guest agent. Bounded Recovery workflows use an expiring, request-bound Pomme Recovery session. Both speak PommeAgentProtocol version 1, and the host helper speaks PommeControlProtocol version 1. pomme mdm VM --profile FILEenrolls a VM in MDM from any state. It creates a missing VM, resumes incomplete creation, finishes a retained standalone SIP or AMFI operation, and then enrolls. You can repeat the command safely after any failure.--dry-runreports the plan without changing the VM.--final-security disabledkeeps the SIP and AMFI changes that enrollment made.- When only the profile’s own certificate payloads validate the MDM server,
Pomme installs them as a separate
com.github.weswhet.pomme.mdm-trust.*configuration profile.
pomme agent update VMreplaces the guest agent in a running VM with the agent from the host’spommebuild. It doesn’t use Recovery or restart the guest. SIP, AMFI, and MDM workflows accept the updated agent. For details, see Update the agent.- VMs start faster. launchd no longer throttles the guest agent’s CPU and disk
access, which during boot delayed the agent by up to 22 seconds. Because
pomme startwaits for the agent, it now returns about 9 seconds after it begins. Programs thatpomme execruns are no longer throttled either. An existing VM gets this change after you update its agent and restart the VM. pomme startchecks for the agent every 50 milliseconds instead of every half second, so it returns sooner after the agent connects.- Release builds strip the symbol table from the
pommeexecutable, which halves its size.pomme agent updatecopies the smaller executable into a VM in about half the time. - After the agent verifies the digest of its executable once, later starts check the code directory hash that the kernel validated instead of reading the whole executable again. For details, see Digest pinning.
- Pomme publishes signed releases. To install the newest release, run
brew install weswhet/tap/pommeorcurl -fsSL https://pommevm.dev/install.pl | perl. To install the newest alpha, runcurl -fsSL https://pommevm.dev/install.pl | POMME_CHANNEL=alpha perl. For details, see Install Pomme. pomme updateupdates Pomme the way that you installed it: withbrew upgradefor Homebrew, and with the install script otherwise.pomme update --checkreports whether an update is available. For details, see Update Pomme.- About once a day, a release build checks for a newer version in the
background, and an interactive command prints a notice when one is
available. The check never runs for JSON output, without a terminal, or when
you set
CIorPOMME_NO_UPDATE_CHECK. - VM creation keeps a copy of the agent executable that it pins, so
pomme agent repairandpomme create --resumecan still install that agent after you update Pomme. - Most commands accept
--progress auto|plain|offto control the progress display on standard error.
Command-line syntax
Section titled “Command-line syntax”A command takes at most one kind of positional value: the VM, or the file or endpoint that it acts on. Every other value is a named flag:
- The
pomme jobscommands that act on one job take its ID with--job, and thepomme sessionscommands that act on one session take its ID with--session. For example,pomme jobs logs dev --job JOB_ID. pomme snapshot create,restore, anddeleterequire the snapshot name with--snapshot. For example,pomme snapshot create dev --snapshot clean.pomme shellonly opens a durable shell session, attached or with--detach. It keeps the user, group, working directory, and environment flags, and no longer accepts--timeout,--stdin,--pty,--guest-stdin,--guest-stdout, or--guest-stderr. To run a one-shot shell expression, usepomme exec VM -- /bin/sh -c 'EXPRESSION'.- The
pomme uicommands that act on a VM name it with--vm, which falls back toPOMME_VM_NAME.pomme ui keytakes the key with--key,pomme ui typetakes exactly one of--textor--text-env, andpomme ui key-sequencetakes its keys after--. For example,pomme ui key-sequence --vm dev -- down return. - The unavailable
pomme ui ai settingscommand is removed, andpomme toolsno longer reportsuiCapabilities.settingsAI. - The
pomme toolsandpomme agent-helpJSON output starts atschemaVersion1.
New flags
Section titled “New flags”pomme stop,pomme pause,pomme resume, andpomme deleteaccept--all(-a) in place of VM names. Each acts on the VMs that it applies to:stopon running and paused VMs,pauseon running VMs,resumeon paused VMs, anddeleteon every VM. For details, see Act on every VM.- Every
--forceflag also accepts-f.
Compatibility
Section titled “Compatibility”- The MDM enrollment journal is now schema 6. Pomme reads schema 3–5 journals
with
--final-security restoreand rewrites them as schema 6 on their next update.