How to Force EXC_GUARD Patch on iOS 26.x Bases with vphone-cli

Use the --force-exc-guard CLI flag or set FORCE_EXC_GUARD=1 to manually enable the Mach-port guard disable patch when working with iOS 26.x bases in vphone-cli.

The vphone-cli tool automatically applies the EXC_GUARD disable patch for iOS 18 bases to prevent crash loops, but treats iOS 26.x as stable without this modification. When you need to force EXC_GUARD patch even on 26.x bases with vphone-cli, the repository provides explicit opt-in mechanisms through command-line arguments and environment variables.

Why iOS 26.x Requires Explicit Opt-In for EXC_GUARD Patches

By default, vphone-cli only disables EXC_GUARD (specifically GUARD_TYPE_MACH_PORT) for iOS 18 bases where the kernel crash-loop makes the patch mandatory. The firmware pipeline evaluates whether to apply the guard-disable logic based on the iOS base version and an explicit override flag.

In sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift, the decision logic evaluates:

let applyExcGuard = iosBaseIs18 || forceExcGuard

When iosBaseIs18 is false (as with 26.x bases) and forceExcGuard remains false, the system skips the EXC_GUARD patch to avoid unnecessary kernel modifications. This conservative approach prevents altering stable 26.x kernels unless explicitly requested.

Force the Patch Using the CLI Flag

The most direct method to enable the patch for a single operation is the --force-exc-guard argument.

vphone-cli fw patch myphone --variant regular --force-exc-guard

After patching completes, you must restore or install the custom firmware (CFW) again so the device boots with the modified kernel image:

vphone-cli restore myphone

The flag definition resides in sources/vphone-cli/VPhoneFWCLI.swift, where the @Flag property wrapper exposes the --force-exc-guard option to the command interface.

Alternative Activation Methods

Using Environment Variables

You can export the FORCE_EXC_GUARD variable before executing any firmware patch command. This approach works across all vphone-cli subcommands without modifying the invocation syntax.

FORCE_EXC_GUARD=1 vphone-cli fw patch myphone --variant jb

Using the Makefile Wrapper

For automated workflows or dev variants, the repository's Makefile automatically translates the FORCE_EXC_GUARD make variable into the CLI flag. Set it when invoking any fw_patch* target:

make fw_patch_dev VM=myphone FORCE_EXC_GUARD=1

The Makefile logic (around line 354) conditionally appends --force-exc-guard when the variable equals 1 or true:

$(if $(filter 1 true yes,$(FORCE_EXC_GUARD)),--force-exc-guard,)

After Makefile-based patching, complete the installation with:

make cfw_install_dev VM=myphone

How the Patch Applies to the Kernel

When forceExcGuard evaluates to true, the KernelPatcher class in sources/FirmwarePatcher/Kernel/KernelPatcher.swift executes the guard-disable routine. The patcher checks the combined condition:

if isDev || applyExcGuard {
    patchExcGuardBehavior()
}

The patchExcGuardBehavior() method injects the necessary kernel modifications to disable GUARD_TYPE_MACH_PORT exceptions. This occurs during the firmware pipeline's kernel processing stage, ensuring the patched image contains the disabled guard behavior before serialization to disk.

Summary

• Default behavior: vphone-cli automatically patches EXC_GUARD only for iOS 18 bases, leaving iOS 26.x untouched.
• Force activation: Use --force-exc-guard flag, FORCE_EXC_GUARD=1 environment variable, or Makefile equivalent.
• Source logic: FirmwarePipeline.swift controls eligibility via applyExcGuard = iosBaseIs18 || forceExcGuard.
• Kernel modification: KernelPatcher.swift applies patchExcGuardBehavior() when the flag is enabled.
• Deployment requirement: Always re-patch and restore/reinstall the CFW after enabling the flag for changes to take effect.

Frequently Asked Questions

What is the EXC_GUARD patch and why disable it?

The EXC_GUARD patch disables Mach-port guard exceptions (GUARD_TYPE_MACH_PORT) in the iOS kernel. According to the source code, iOS 18 bases require this modification to prevent crash-loop behavior during boot, while iOS 26.x bases function correctly without it.

Does forcing the patch on iOS 26.x cause instability?

The patch is opt-in for iOS 26.x because the base system does not require it for stability. While vphone-cli allows forcing the patch via --force-exc-guard, you should only enable it when troubleshooting specific Mach-port guard issues or following specialized workflows that explicitly require disabled guards.

Why must I restore the device after patching?

The firmware patch command modifies the stored kernel image on disk. The running device continues using the previously cached kernel until you execute vphone-cli restore or install the CFW again, which flashes the newly patched image to the device and triggers a boot sequence with the modified EXC_GUARD behavior.

Can I use the Makefile and CLI flag together?

Yes. If you set FORCE_EXC_GUARD=1 while using the Makefile, it automatically appends --force-exc-guard to the underlying vphone-cli invocation. Setting the environment variable manually before a direct CLI command achieves the same result without the Makefile wrapper.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}