Skip the cutscene

Files and paths

This page lists the files and directories that Pomme creates on the host and in each guest. Consider it the floor plan, Crawler. Look, but don’t rearrange the furniture.

Path Description
~/.local/bin/pomme The executable installed by the install script or a local source build.
/opt/homebrew/bin/pomme The executable installed by Homebrew.
/usr/local/bin/pomme The executable installed by the Pomme package.

Pomme stores its data in ~/Library/Application Support/pomme. To use a different directory, set POMME_APP_SUPPORT_DIR.

Path Description
VMs/NAME.bundle One bundle for each VM.
Templates/NAME.bundle One bundle for each template.
RestoreImages/ Downloaded restore images (IPSW files).
AgentArtifacts/sha256/ An append-only store of signed Pomme executables, keyed by SHA-256 digest. VM creation adds the executable that it pins, and the local build script adds each build. Recovery installation uses the store to find the exact agent that a VM’s journal pins.
TerminalSessions/ Transcripts and metadata for durable terminal sessions in normal macOS.
Runtime/ Runtime state for running VM helpers.
RecoveryStaging/, RecoveryTerminalBootstrap/ Temporary, request-bound files that Pomme shares with a VM in Recovery.

Each VMs/NAME.bundle directory contains the following files:

File Description
Disk.img The VM’s disk image.
AuxiliaryStorage The VM’s auxiliary storage, which holds its NVRAM and boot firmware.
HardwareModel, MachineIdentifier The VM’s hardware identity.
Metadata.json Pomme’s record of the VM: macOS version and build, sizes, agent identity, provisioning route, and template.
SecurityWorkflowJournal.json The journal for SIP and AMFI workflows. It never contains the owner password.
MDMEnrollmentJournal.json The journal for MDM enrollment.
SaveFile.vzvmsave The saved machine state, when present.
Snapshots/ Named saved-state snapshots.
FirmwareBackups/ A copy of AuxiliaryStorage from before each pomme firmware repair that changed it, named for the UTC time of the repair.
pomme-helper.log The log of the VM’s background helper process. It starts with the Pomme version, the host’s macOS version, and the boot mode, and it records each failed request with its error code.
pomme-helper.previous.log The log of the previous helper process. Pomme moves pomme-helper.log here when it starts a new helper.
.pomme/ The VM’s creation journal and its signing key. After pomme agent update, it also holds the signed record of the updated agent’s digest.

Treat these files as internal. Their formats can change between Pomme versions. Reading them is fine. Editing them is a plot twist.

Location Description
Login Keychain Each VM’s guest agent credential and owner password, stored under a service name that starts with com.github.weswhet.pomme.vm and is scoped to the VM’s UUID. The Keychain must be unlocked.
$TMPDIR/pomme-*.sock The Unix socket for each VM’s background helper.
$TMPDIR/pomme-recovery-debug-* Screenshots that --debug keeps for each automatic Recovery navigation. Pomme doesn’t delete them.
~/Library/Caches/com.github.weswhet.pomme/update-check.json The result of the most recent update check. Deleting it only causes another check.
~/Library/Caches/com.github.weswhet.pomme/last-error.json The most recent error that pomme reported, with its code, causes, and the command’s arguments with private values removed. pomme bug-report reads it. Deleting it is safe.

Pomme installs the following files in each guest’s normal macOS:

Path Description
/usr/local/libexec/pomme The guest agent executable.
/Library/LaunchDaemons/com.github.weswhet.pomme.agent.plist The launchd job for the guest agent, with the label com.github.weswhet.pomme.agent.
/private/var/db/pomme/agent.token The guest agent’s private credential.

The guest agent writes to the unified log under the subsystem com.github.weswhet.pomme. To read those logs from the host, see View guest agent logs.