Creation config file
Welcome to the rulebook, Crawler. A creation config file describes one or more
VMs that pomme create --config creates in a single batch. This page describes
every field that the file can contain. It’s a reference page, so the System has
been asked to keep its commentary to a minimum. The System resents this. For a
task-oriented introduction, see
Create VMs from a config file.
File formats
Section titled “File formats”Pomme reads the same schema from four formats. Pick your favorite. It chooses the parser from the file extension:
| Extension | Format |
|---|---|
.json |
JSON |
.yaml, .yml |
YAML |
.toml |
TOML |
.pkl |
Pkl. Pomme evaluates the file with pkl eval --format json, so the pkl executable must be on your PATH. |
To create a starter file interactively, run pomme config init.
Example
Section titled “Example”The following YAML file creates two VMs: one from the latest selector and
one for macOS 26.6.2:
schemaVersion: 1name: labversions: - latest - 26.6.2hardware: diskSize: 40GB memory: 4GBboot: noneThe same config in TOML, for Crawlers with strong opinions about indentation:
schemaVersion = 1name = "lab"versions = ["latest", "26.6.2"]boot = "none"
[hardware]diskSize = "40GB"memory = "4GB"Fields
Section titled “Fields”Here’s every top-level field. There are six. The System counted them twice.
| Field | Type | Required | Description |
|---|---|---|---|
schemaVersion |
Integer | Yes | The schema version. Must be 1. |
name |
String | Yes | The base name for the VMs that the config creates. It follows the VM name rules. |
versions |
Array of strings | Yes | One or more macOS selectors. Each selector is a version such as 26.6.2, a build such as 25G83, or latest. Pomme creates one VM for each selector. |
ipswDevice |
String | No | The Apple silicon Mac model identifier, such as Mac16,10, that Pomme uses to resolve versions. Defaults to the host’s model. |
hardware |
Object | No | The VM hardware. See hardware. |
boot |
String | No | The state that each VM is left in after creation: normal, recovery, or none. |
hardware object
Section titled “hardware object”| Field | Type | Default | Description |
|---|---|---|---|
diskSize |
String | 60GB |
The virtual disk size. |
memory |
String | 8GB |
The guest memory size. Must be at least 4 GiB. |
Sizes are a positive number followed by an optional unit: B, K, M, G,
or T, optionally followed by B or iB, in any letter case. All units are
binary, so 40GB and 40GiB both mean 40 × 1024³ bytes. Yes, both. The
System doesn’t want to hear about it.
boot values
Section titled “boot values”| Value | Result |
|---|---|
normal |
The VM keeps running in normal macOS after Pomme verifies its guest agent. |
none |
Pomme shuts the VM down after it verifies the guest agent. |
recovery |
Pomme restarts the VM in Recovery. |
VM names
Section titled “VM names”Each selector in versions creates a VM named NAME-VERSION, where NAME is
the config’s name and VERSION is the macOS version that the selector
resolves to. For example, with name: lab, the selector latest might create
a VM named lab-26.6.2.
Both name and each generated name must follow these rules:
- Contain 1–64 characters.
- Contain only ASCII letters, digits, periods (
.), underscores (_), and hyphens (-). - Start with a letter or digit.
Selectors in versions can’t be empty or repeated, and two selectors can’t
resolve to the same VM name. If any generated name matches an existing VM,
Pomme rejects the whole config before it creates anything. No partial credit.
Validation
Section titled “Validation”Pomme rejects a config that contains a key it doesn’t define, at any level, so a misspelled key causes an error instead of having no effect. Typos get caught, Crawler. The System finds this disappointing.
Creation configs describe only VM provisioning. Pomme rejects the following keys from older config versions with an error that names the replacement:
| Key | Replacement |
|---|---|
credentials |
The explicit security commands, such as pomme sip. |
workflow |
The boot field or the --boot flag. |
mdm |
The pomme mdm command. |
restore, replaceExisting, failureCleanup |
None. Regenerate the file with pomme config init. |
To check a config, use these commands:
pomme config validate FILEchecks the schema without contacting any server.pomme config render FILEalso resolves each selector to an exact macOS version and build, and prints the VM names and creation plan.