# How iOS 27 Specific Kernel Patches Are Gated in vphone-cli

> Discover how vphone-cli gates iOS 27 kernel patches using automatic version detection, CLI flags, and conditional execution. Optimize your iOS patching process.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: internals
- Published: 2026-08-31

---

**vphone-cli gates iOS 27-specific kernel patches through a three-layer system involving automatic base version detection, CLI flag propagation, and conditional execution blocks in the kernel patcher.**

The vphone-cli repository provides a virtualization toolchain for running iOS on Apple Silicon Macs, supporting multiple iOS base versions including 18.x, 26.x, and 27.x. Because certain jailbreak-oriented kernel patches only remain compatible when the guest userland runs iOS 27 atop the 26.4 vphone600 host kernel, the codebase implements a strict **gate** mechanism to prevent these patches from breaking older iOS 26.x VMs. Understanding how iOS 27 specific kernel patches are gated in vphone-cli ensures safe firmware modification across different iOS generations.

## Base Version Detection in FirmwarePipeline

The gating process begins with automatic version identification during the firmware pipeline initialization. In [`sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift), the `FirmwarePipeline` class reads the product version directly from the restore directory using `Self.readBaseProductVersion` to determine the target iOS version.

The pipeline sets a Boolean flag `iosBaseIs27` by checking if the base version string starts with "27":

```swift
iosBaseIs27 = baseVersion?.hasPrefix("27.")

```

This detection occurs at lines 34-40 in [`FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/FirmwarePipeline.swift). When the pipeline executes `patchAll()`, it propagates this Boolean through to each `KernelJBPatcher` instance via a factory closure, ensuring the iOS 27-specific patches only activate when the base image actually requires them.

## CLI Flag Propagation via --target-os

For standalone patch operations outside the full pipeline, vphone-cli exposes a command-line interface that allows explicit version targeting. In [`sources/vphone-cli/VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneCLI.swift), the parser handles the `--target-os` argument to manually set the iOS version context.

The CLI logic maps the `--target-os` value to the internal `applyIOS27` property using a prefix check:

```swift
targetOS.map { $0.hasPrefix("27.") } ?? true

```

This implementation appears at lines 63-68 in [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift). If the user omits the `--target-os` flag, the default value evaluates to `true`, applying the full patch set including iOS 27 modifications—a behavior optimized for development and testing scenarios. Explicitly passing `--target-os 26.5` forces the parser to return `false`, effectively disabling the iOS 27-specific gates.

## KernelJBPatcher Gate Implementation

The actual enforcement of iOS 27 specific kernel patches occurs in [`sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift), where the `KernelJBPatcher` class implements the final execution barrier.

### The applyIOS27 Property

The patcher exposes a public `applyIOS27` property that defaults to `false` (lines 24-25), creating a secure-by-default posture that prevents accidental application of incompatible patches. This property acts as the master switch for all version-specific modifications.

### Conditional Patch Methods

All iOS 27-exclusive patches reside within conditional blocks checking `if applyIOS27 { … }`. These protected patches include critical system modifications such as:

- **`patchIoucFailedSandbox()`** – Modifies sandbox policy enforcement
- **`patchDiskImages2ClientAbi()`** – Adjusts disk image client ABI handling  
- **`patchExecSecurityPolicyKill()`** – Alters executable security policy termination

The specific implementation at lines 43-55 and 89-108 demonstrates how each method first validates the gate before executing binary patches. For example, `patchExecSecurityPolicyKill()` only modifies the kernel's security policy structures when `applyIOS27` evaluates to true, preventing execution kills on incompatible iOS 26.x bases where such patches would corrupt the VM's stability.

## Programmatic Pipeline Usage

When integrating vphone-cli as a library rather than a command-line tool, developers interact with the gate mechanism through the `FirmwarePipeline` constructor:

```swift
let pipeline = FirmwarePipeline(
    vmDirectory: vmDir,
    restoreDirectory: restoreDir,
    variant: .jb,
    forceExcGuard: false,
    enableFrida: false
)
pipeline.patchAll()   // applyIOS27 is set automatically from base version

```

During `patchAll()` execution (lines 36-38 in [`FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/FirmwarePipeline.swift)), the pipeline captures the `applyIOS27` value and injects it into each `KernelJBPatcher` instance through the factory closure: `p.applyIOS27 = applyIOS27`.

To execute standalone kernel patching with explicit version control:

```bash

# Apply iOS 27 patches (default behavior)

vphone-cli patch-component kernel-jb \
    --input /path/to/kernelcache \
    --output /path/to/patched_kernelcache

# Skip iOS 27 patches for iOS 26 compatibility

vphone-cli patch-component kernel-jb \
    --input /path/to/kernelcache \
    --output /path/to/patched_kernelcache \
    --target-os 26.5

```

## Summary

- **Version Detection**: [`FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/FirmwarePipeline.swift) automatically detects iOS 27 bases via `readBaseProductVersion` and the `hasPrefix("27.")` check.
- **CLI Override**: The `--target-os` flag in [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift) allows manual control over the `applyIOS27` Boolean when running `patch-component` commands.
- **Safe Defaults**: [`KernelJBPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/KernelJBPatcher.swift) initializes `applyIOS27` to `false`, preventing accidental application of incompatible patches.
- **Conditional Execution**: All iOS 27-specific modifications, including sandbox patches and security policy alterations, execute only within `if applyIOS27` gated blocks.
- **Automatic Propagation**: The full pipeline automatically synchronizes the gate value across all patcher instances during `patchAll()` execution.

## Frequently Asked Questions

### What happens if I apply iOS 27 patches to an iOS 26 base?

Applying iOS 27 specific patches such as `patchIoucFailedSandbox()` or `patchExecSecurityPolicyKill()` to an iOS 26.x base will break the VM. These patches modify kernel structures like IOMFB SwapEnd size checks and sandbox gates that differ between iOS versions, causing kernel panics or security policy violations when the binary layout does not match the expected iOS 27 format.

### How does vphone-cli detect the iOS version automatically?

The tool detects the version through `FirmwarePipeline.readBaseProductVersion`, which extracts the product version string from the restore directory metadata. It then sets `iosBaseIs27` using a prefix match against "27.", propagating this Boolean through the pipeline to each `KernelJBPatcher` instance during initialization.

### Can I force iOS 27 patches to run on a different version?

Yes, though not recommended for production VMs. When using the CLI, omitting `--target-os` defaults `applyIOS27` to `true`, applying all patches regardless of base version. For programmatic control, manually instantiate `KernelJBPatcher` and set `applyIOS27 = true` before calling patch methods, but expect compatibility issues when running on non-27 bases.

### Which specific kernel patches are gated by applyIOS27?

The gated patches include `patchIoucFailedSandbox()` for modifying sandbox failure handling, `patchDiskImages2ClientAbi()` for disk image client adjustments, and `patchExecSecurityPolicyKill()` for altering executable security termination policies. All reside in [`KernelJBPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/KernelJBPatcher.swift) and execute only when the `applyIOS27` property evaluates to true.