Lower the shields (SIP/AMFI)
Welcome to the shield room, Crawler. This guide shows you how to check and change System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI) in a Pomme-owned VM. Pomme performs each change as a journaled transaction, verifies the result on a fresh normal boot, and then returns the VM to the state that you request. The System finds this extremely thorough. The viewers find it extremely slow.
For background on the design of these workflows, see Security workflows.
Before you descend
Section titled “Before you descend”The System requires the following before it unlocks this room:
- Create a VM and make sure that its guest agent is
healthy. To check, run
pomme agent status VM_NAME. For details, see Check, update, and repair the guest agent. - End any active terminal sessions in the VM. Recovery security workflows don’t start while a terminal session is active. For details, see Use durable terminal sessions.
- Decide how Pomme authorizes the owner account. For details, see Provide owner authorization.
Scan the shields
Section titled “Scan the shields”To see whether SIP or AMFI is on, run the status command:
pomme sip status VM_NAMEpomme amfi status VM_NAMEReplace VM_NAME with the name of your VM.
Status commands read the configuration through the guest agent in normal
macOS. If the VM is already running normal macOS, it doesn’t restart. If the VM
is stopped, paused, or running Recovery, Pomme starts normal macOS for the
check. A fresh boot reports the stored configuration, the same values that a
check in Recovery would report. When the check finishes, Pomme puts the VM in
the state that --final-state requests, which by default is the state it was
in before the command. A quick peek, no dungeon detour. The viewers are
already changing the channel.
Pomme observes the guest through Recovery only when the guest agent can’t give a verified answer, for example on a VM whose guest agent predates these checks. Status commands never ask for or transmit an owner password. Not even to the System. The System asked.
Choose where you end up
Section titled “Choose where you end up”Every SIP and AMFI command accepts --final-state, which sets the state that
Pomme leaves the VM in after a successful run. The following values are
supported:
| Value | Final state |
|---|---|
previous |
The run state captured before the command started. This is the default. A VM that was paused in Recovery ends stopped, because Pomme had to stop it and booting Recovery again only to pause it restores nothing. |
stopped |
The VM is stopped. |
normal |
The VM runs normal macOS. |
recovery |
The VM runs Recovery. |
paused |
The VM is paused. A paused VM keeps the boot mode it had before the pause. |
A successful result reports the resolved finalState and whether Pomme
verified it (finalStateVerified).
If a command fails, Pomme doesn’t apply --final-state. Depending on the
failure, Pomme either restores the state captured at the start, leaves the VM
in its failure state for inspection, or reports that restoration is
incomplete.
Lower SIP, then AMFI
Section titled “Lower SIP, then AMFI”AMFI changes require SIP to be off, so you turn off SIP first. No flag bypasses this order. The System has seen Crawlers try. The System has the footage.
To turn off SIP and then AMFI, follow these steps:
-
Turn off SIP:
Terminal window pomme sip disable VM_NAME -
Turn off AMFI:
Terminal window pomme amfi disable VM_NAME
Replace VM_NAME with the name of your VM.
To turn off AMFI, Pomme boots normal macOS, writes and reads back the boot
arguments, and then restarts the guest to verify the effective arguments. AMFI
doesn’t boot Recovery on a VM whose SIP you turned off with
pomme sip disable: that boot policy already allows custom boot arguments, so
the guest agent only records the policy that it found. One less trip to
Recovery. The System has been told this counts as progress. Pomme changes the
LocalPolicy in Recovery only when the VM has a different boot policy that
doesn’t allow custom boot arguments, or when its guest agent predates this
step. If SIP is still on, the AMFI command stops with the following error:
Error: Changing AMFI requires SIP to be off while Pomme writes and verifies boot arguments. Run `pomme sip disable NAME` first, and restore AMFI before you turn SIP on again.Error code: amfi-requires-sip-disabled. For help, see https://pommevm.dev/reference/errors/#amfi-requires-sip-disabledIf the guest already has the requested setting, Pomme records the result without making a change and without asking for owner credentials.
Raise AMFI, then SIP
Section titled “Raise AMFI, then SIP”Restore the settings in the reverse order: AMFI first, then SIP. Last off, first on. The System recommends that you tattoo this somewhere visible.
To restore AMFI and then SIP, follow these steps:
-
Restore AMFI:
Terminal window pomme amfi enable VM_NAME -
Turn on SIP:
Terminal window pomme sip enable VM_NAME
Replace VM_NAME with the name of your VM.
Turning SIP on doesn’t boot Recovery. The guest agent runs csrutil clear in
normal macOS with the owner’s credentials, and Pomme then restarts the guest
and checks csrutil status on the new boot. A VM created with an earlier Pomme
release, whose guest agent can’t run csrutil clear, turns SIP on in Recovery
instead.
On a macOS 27 VM that’s enrolled in MDM, turning SIP on stops the guest from
receiving MDM push commands after its next restart, and pomme sip enable
prints a warning. For details, see
Receive push commands on macOS 27.
pomme amfi enable restores the exact AMFI configuration that Pomme saved when
it turned AMFI off. Like pomme amfi disable, it boots Recovery only when the
saved boot policy needs a LocalPolicy change. If AMFI is off but Pomme has no
saved configuration, for example because AMFI was turned off outside Pomme, the
command stops before it changes anything and reports the
amfi-baseline-missing error:
Error: Pomme has no recorded AMFI baseline for this VM, so it can't restore AMFI. Pomme didn't change the boot policy.Run `pomme amfi status NAME` to see the VM's AMFI state.Error code: amfi-baseline-missing. For help, see https://pommevm.dev/reference/errors/#amfi-baseline-missingProvide owner authorization
Section titled “Provide owner authorization”Changing SIP or AMFI requires an owner account in the guest. How Pomme gets authorization depends on whether the VM already has an owner.
Fresh VMs without an owner
Section titled “Fresh VMs without an owner”On a VM that Pomme verifies as fresh and Pomme-owned, the workflow creates the
owner account for you, without asking. It creates a pomme administrator,
turns on automatic login for that account, and finishes Setup Assistant. Free
labor. Enjoy it. A VM is fresh only when nobody has set it up, which means that Setup Assistant
hasn’t finished, and the guest has no user accounts and no volume owner. This
is the case for a macOS 26 VM that pomme create made, because only macOS 27
lets Pomme create the owner while it installs macOS.
If macOS refuses automatic login, for example because of Touch ID, Apple Pay, or App Store protections, the workflow stops.
VMs with an existing owner
Section titled “VMs with an existing owner”Pomme verifies an existing owner account but never replaces it or changes its password. Pomme accepts the owner’s credentials from one of the following sources:
- Both of the
POMME_AUTHORIZED_USERandPOMME_AUTHORIZED_PASSWORDenvironment variables. If you set only one of them, Pomme rejects the request. - The VM-scoped owner credential that Pomme stores in your login Keychain.
- An interactive prompt, when you run the command in a terminal.
For example, to supply the credentials through the environment, run the following:
POMME_AUTHORIZED_USER=OWNER_NAME \POMME_AUTHORIZED_PASSWORD="$(security find-generic-password -s MY_ITEM -w)" \ pomme sip disable VM_NAMEReplace the following:
OWNER_NAME: the short name of the guest’s owner account.MY_ITEM: the name of a Keychain item where you keep the password. You can use any other secret source that doesn’t put the password in your shell history.VM_NAME: the name of your VM.
Pomme passes the password to its credential boundary separately. It never places the password in command arguments or in the durable journal.
If Pomme finds no credentials, the command stops with the following error:
Owner credentials are required. Set both POMME_AUTHORIZED_USER and POMME_AUTHORIZED_PASSWORD, restore the exact VM-scoped Keychain item, or run from an interactive terminal.Resume an interrupted change
Section titled “Resume an interrupted change”Pomme records each step of a SIP or AMFI change in a per-VM journal. If a change stops partway, for example because the host restarted, the journal and the VM are kept. The dungeon remembers. The dungeon always remembers.
To resume, repeat the same command with the same --final-state value. For
example, if this command was interrupted:
pomme sip disable VM_NAME --final-state stoppedRun exactly the same command again. Pomme observes the guest, reconciles the retained journal, and continues without repeating an owner or security write that already happened.
You can’t change the requested action or final state of a retained operation. Pomme rejects a different request instead of rewriting the journal.
If you start a different operation while one is unfinished, Pomme stops before it changes anything:
Another unfinished Pomme security operation owns this VM.Finish the original operation first by repeating its command. One quest at a time, Crawler.
If Pomme can’t prove that cleanup finished, it reports restorationIncomplete
and doesn’t boot or restore the VM:
VM state restoration is incomplete. The account, credentials, and security journal were retained; repeat the same command after inspecting the VM.Record the replay
Section titled “Record the replay”When pomme sip disable changes SIP, it boots Recovery, because macOS turns
off SIP only there. That room can’t be skipped, so you might as well film it.
To keep screenshots of each automatic Recovery navigation step, add --debug:
pomme sip disable VM_NAME --debugPomme prints the private directory and the saved file names to standard error. The screenshots stay after the command finishes, whether it succeeds or fails. Because full-resolution screenshots can show local identifiers, delete the directory when you no longer need it. The sponsors would love to buy that footage. Don’t let them.
Next floor
Section titled “Next floor”- Enroll a VM in MDM, which turns off only the security settings that enrollment needs.
- Security workflows
pomme sipreferencepomme amfireference- Troubleshooting