Add iPhone17,3 iOS 27.0 beta 8 (24A5430a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 22 -> 23.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 7 (24A5424a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 21 -> 22.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Ej64m761KR33KaNYh3BuTo
The bundled 26.6.1 IPSW pointed at the 23G82 release candidate, which
differs from the shipped release. Point it at the 23G83 final restore
and update the tested-environment tables accordingly.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 6 (24A5418b) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 20 -> 21.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 26.6.1 (23G82) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 19 -> 20.
Co-Authored-By: Claude Fable 5 <[email protected]>
Reflect fast-by-default compression (--max = xz -9), directory
auto-naming, and the positional import argument in the README and its
ja/ko/zh translations.
Co-Authored-By: Claude Fable 5 <[email protected]>
The build cross-compiles the guest daemon (vphoned) for iOS, which
requires the iOS SDK bundled with Xcode. Add it to the host
prerequisites in the English, Japanese, Korean, and Chinese READMEs.
Co-Authored-By: Claude Fable 5 <[email protected]>
Export previously hardcoded xz -9 (the densest but slowest libarchive
compressor), forcing a multi-GB Disk.img through the most aggressive
setting on every export.
Add a `--compress {fast,balanced,max}` preset on `vphone vm export`,
default `balanced`:
fast zstd -3
balanced zstd -19 (new default)
max xz -9 (previous behavior)
All presets go through the same system /usr/bin/tar (libarchive) already
used for xz, so no new dependency and no raised platform floor. Import is
unchanged: it already auto-detects the compressor via `tar -tf`/`-xf`, so
zstd and xz archives both import.
Tests assert each preset's magic bytes (zstd vs xz), that fast/max
round-trip, and the default is zstd. README examples updated.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add the iPhone17,3 27.0 24A5408d + cloudOS 26.4 pairing to the firmware
catalog so it is selectable in `fw prepare` / `vm create`, and bump the two
hardcoded pairing counts in the picker tests (18 -> 19).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01N2bwKrGJWY7o2ArdxibVPe
PyPI has no arm64 macOS wheel for keystone-engine, so pip builds it
from the sdist, whose make-share.sh invokes cmake directly. Without
it the build fails silently and installs bindings with no native
library, which is what the libkeystone repair recovers from.
Restructure the README (Prerequisites/Install/Build up top, a dedicated
SIP/AMFI Relaxation section, Tested Environments moved down) and trim prose.
Regenerate the Korean, Japanese, and Chinese translations to match the new
structure verbatim — same 13 sections in the same order, all commands, URLs,
tables, and identifiers preserved byte-for-byte, only prose and code comments
translated, docs/-relative links and in-language anchors applied.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
`vm create` on an interactive terminal now prompts for whichever firmware
component wasn't passed on the command line, choosing from a known-good
iPhone/cloudOS catalog by friendly name (e.g. "iOS 26.4", "cloudOS 26.4")
rather than raw URLs. Supply one of --iphone-source/--cloudos-source and
only the other is asked for; supply neither and a full pairing is chosen.
Non-interactive runs (or both flags set) pass through unchanged, so
fw_prepare's defaults still fill any gap and scripted use is unaffected.
- VPhoneFirmwareCatalog: 18 iPhone17,3 pairings + 4 distinct cloudOS images.
- VPhoneFirmwarePicker: pure, injectable-I/O resolver (13 unit tests).
- VPhoneFirmwareSelection: TTY adapter (isatty + readLine → stderr prompts).
- Wired into `vm create` before the orchestrator runs; READMEs (+ ja/ko/zh)
document the prompt behavior.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
- README.md rewritten around the vphone-cli binary (no make): tested-env
matrix, two-path SIP/AMFI setup, firmware variants, commands, short flags,
and a Python-runtime section covering the auto-provisioned venv / portability
- docs/README_{ko,ja,zh}.md regenerated as full translations mirroring it
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
On 26.x bases the EXC_GUARD (Mach port guard) disable patch is not required
to boot, so it is no longer applied unconditionally on regular/jb/exp.
Production apps shipping crash-reporting/RASP SDKs (Bugly, Crashlytics,
KSCrash) call task_swap_exception_ports(), which the research kernel enforces
as a fatal GUARD_TYPE_MACH_PORT violation on launch; a --force-exc-guard flag
(FORCE_EXC_GUARD=1 in the Makefile) re-enables the patch for those cases.
iOS 18 bases and the dev variant keep the patch always-on, since both need it
to boot. The documented violation is corrected from SET_EXCEPTION_BEHAVIOR to
KOBJECT_REPLY_PORT_SEMANTICS, matching the actual reproduction crash logs.
Also add /vm-*/ to .gitignore for multi-VM directories.
Co-authored-by: Paulo Sarrin <[email protected]>
Co-authored-by: zqxwce <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
patch-dsc-maxslide self-gates to a no-op when the shared cache fits the
vphone600 26.x kernel's 6 GiB region, which 26.x/18.x bases always do, so
it only fires on 27. Add a --force flag that bypasses the fits-check and
zeroes maxSlide unconditionally (still idempotent), and a
FORCE_DSC_MAXSLIDE=1 env opt-in in cfw_install.sh that runs it on non-27
bases. Default off; 27 behavior unchanged.
Also fix the installer env-threading in cfw_install_host.sh: a
${VAR:+NAME=val} word produced by expansion is not parsed as a shell
assignment (zsh runs it as a command), so route the assignments through
env. This makes FORCE_DSC_MAXSLIDE reach the installer and repairs the
same latent bug for SPOOF_BUILD.
Verified on a 26.4 JB VM: FORCE_DSC_MAXSLIDE=1 yields on-disk maxSlide=0
and a live shared-cache slide of 0x0 (dyld maps the cache at its
preferred base 0x180000000 in rpcserver_ios), versus the nonzero slide a
stock 26.4 boot picks.
Docs + research/0_binary_patch_comparison.md updated (README and the ja/ko/zh
translations).
Co-Authored-By: Claude Fable 5 <[email protected]>
Add the 27.0 / `17,3_27.0_24A5380h` / `26.4-23E5207q` row to the
tested-environments table across README.md and the ja/ko/zh translations,
and update docs/demo.jpeg.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013pk5tsoBeuu3jhkmnRFtic
Sync the localized READMEs (ja/ko/zh) tested-environment tables to match
README.md: add the Mac16,11 27.0b2 / 17,3_18.6.2_22G100 / 26.1-23B85 row
and drop the redundant Mac16,8 26.5.1 / 17,3_26.1_23B85 entry.
Note in all four READMEs that GPU/Metal acceleration does not work on
iOS 18.x -- the 18.x Metal/IOGPU framework has no paravirtualized GPU
implementation, so Metal-rendered content (web, images, wallpaper) does
not render; touch, networking, and apps work.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q7gbWrtKLu8rFGmpXHmu9t
Patch the 26.0/26.0.1 IOMobileFramebuffer SwapEnd payload size during CFW install and document the validated 26.0, 26.0.1, and 26.1 host-install matrix.
The ramdisk-based install (build/send an SSH ramdisk, iproxy-forward, then
push CFW files over SSH and flip the boot snapshot with snaputil in-VM) has
been fully replaced by the host-mount path: cfw_install_host.sh mounts the
VM's Disk.img on the host, places every file locally, and flips the boot
snapshot offline via tools/apfs_snap_rename.py. This removes all remaining
ramdisk generation, delivery, and usage — no legacy fallback.
Deleted:
- scripts/ramdisk_build.py, scripts/ramdisk_send.sh
Renamed:
- scripts/cfw_host_mode.sh -> scripts/cfw_transport.sh (was a conditional
"host-mode override"; now the sole, unconditionally-sourced transport)
setup_machine.sh: drop the USE_RAMDISK_CFW=1 branch and every iproxy/ramdisk
helper (usbmux UDID resolution, port picking, start/stop iproxy, wait-for-
ramdisk-ssh), all RAMDISK_*/IPROXY_* vars, the cleanup() iproxy handling, and
the orphaned cfw_install_target var. Only the host-mount cfw_install_host call
remains.
cfw_install{,_dev,_jb,_exp}.sh: delete the SSH transport (SSH_* vars, SSH_OPTS,
sshpass prereq/_sshpass/_ssh_retry, ssh_cmd/scp_to/scp_from/remote_file_exists/
remote_mount, wait_for_device_ssh_ready) and the dead ramdisk-mechanism body
blocks (snaputil snapshot flip, dropbearkey host-key pre-generation, halt-over-
SSH, CFW_SKIP_HALT). The transport is now sourced unconditionally from
cfw_transport.sh. dropbear -R generates host keys at first boot; the offline
apfs_snap_rename.py does the boot-source flip. Dropped the vestigial
CFW_HOST_MODE gate.
Also: pymobiledevice3_bridge.py (ramdisk-send command already gone), Makefile
(ramdisk targets/help/IRECOVERY_ECID removed), README + ja/ko/zh (install flow
rewritten to host-mount), AGENTS.md/CLAUDE.md architecture tree, and stale
comments in vphone_jb_setup.sh, VPhoneCLI.swift, apfs_snap_rename.py,
cfw_patch_post_restore_dt.py.
Verified booting via make setup_machine.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01XZVS9oqVNmHJzpb8mFtKJx
Introduces a new `exp` firmware variant on top of JB and ports the
`hv_vmm_present` sysctl rename to it.
Variant infrastructure
----------------------
- Adds `case exp` to `FirmwarePipeline.Variant`,
`VPhoneCLI.PatchFirmwareCLI.VariantOption`, and
`VPhoneVirtualMachine.Variant`. Every `switch variant` block in
`FirmwarePipeline.buildComponentList` includes the new case.
- Adds `make fw_patch_exp` + `make cfw_install_exp` Makefile targets
and an `EXP=1` flag for `make setup_machine`, mutually exclusive with
`JB=1` / `DEV=1` / `LESS=1`. `SPOOF_BUILD` env var is threaded
through for later use by the build-version step.
- Adds `--exp` to `scripts/setup_machine.sh` alongside `--jb` /
`--dev` / `--less`. The post-install JB-Finalize block also fires
for EXP (since EXP inherits the JB rootfs deployment).
- Adds `scripts/cfw_install_exp.sh` as the EXP install script
starting point: identical phase set to `cfw_install_jb.sh` (JB-1..JB-5)
with banner/header/footer updated for EXP. Subsequent commits in this
branch add the EXP-only experimental phases on top.
- Updates the variants table in `AGENTS.md` / `README.md` and the
three translated READMEs to include the new `Experimental (EXP)`
row, plus a paragraph describing what EXP adds on top of JB.
Kernel patch
------------
- New `KernelEXPPatcher` orchestrator in
`sources/FirmwarePatcher/Kernel/`, chained after `KernelPatcher` +
`KernelJBPatcher` for the `.exp` variant only. Inherits
`KernelJBPatcherBase` to reuse the JB symbol-table / ADRP-BL index /
branch-encoder infrastructure.
- New `KernelEXPPatchHvVmmRename` patch in
`sources/FirmwarePatcher/Kernel/EXPPatches/`. Part A flips byte 0 of
the NUL-delimited `\\0hv_vmm_present\\0` cstring (the sysctl OID's
`oid_name` value) — `'h'` -> `'X'` — so the kernel resolves
`sysctlbyname("kern.hv_vmm_present")` as ENOENT and
`sysctlbyname("kern.Xv_vmm_present")` to the OID's real int value.
Part B mangles byte 5 of every kernel-internal occurrence of
`kern.hv_vmm_present` so callers keep hitting the renamed OID; two
byte-aligned forms are covered (NUL-delimited cstring + sandbox-profile
name-token with trailing `\\x0f`).
- Patch IDs are `kernelcache_exp.hv_vmm_oid_rename` and
`kernelcache_exp.hv_vmm_internal_caller_mangle`. Idempotent.
- `KernelJBPatcher` is unchanged at the call-site level (no
`patchHvVmmRename` call); its docstring is updated to point at
`KernelEXPPatcher` for the EXP-only patch.
JB and other variants are NOT affected: `cfw_install_jb.sh` and
`cfw_install_dev.sh` are untouched in this commit.
Make the default clean target remove only build/tooling artifacts, add
confirmation prompts, and require explicit CLEAN_VM/CLEAN_IPSW flags before
removing VM or IPSW state. Document the behavior in README translations.
It could be more clear that git submodules must be installed.
In my case, I missed this, leading to hours of troubleshooting.
This commit seeks to make it more clear what steps are needed to install dependencies.
* Fix iproxy port number for SSH connection
* Fix iproxy port number in README_zh.md
* Fix iproxy port number in Japanese README
* Fix iproxy port number in README_ko.md
* fix: prefer project venv Python for patchers
* add: VM backup, restore, and switch support
Named backups via rsync --sparse for efficient sparse disk handling.
- vm_backup.sh: save current VM as a named backup to vm.backups/
- vm_restore.sh: restore a named backup into vm/
- vm_switch.sh: save current + restore target in one step
- Makefile targets: vm_backup, vm_restore, vm_switch, vm_list
- Documentation added to all READMEs (EN, ZH, KO, JA)
Closes#204
Made-with: Cursor
Run SwiftFormat on firmware patcher
Remove legacy Python firmware patchers
Fix compare pipeline pyimg4 PATH handling
Restore Python patchers and prefer fresh restore
Update BinaryBuffer.swift
Avoid double scanning in patcher apply
Prefer Python TXM site before fallback
Retarget TXM trustcache finder for 26.1
Remove legacy Python firmware patchers
Fail fast on nested virtualization hosts
Return nonzero on fatal boot startup
Add amfidont helper for signed boot binary
Stage AMFI boot args for next host reboot
Add host preflight for boot entitlements
Fail fast when boot entitlements are unavailable
Switch firmware patch targets to Swift CLI
Record real Swift firmware parity results
Verify Swift firmware pipeline end-to-end parity
Fix Swift firmware pipeline JB dry-run
Implement VM configuration manifest system compatible with security-pcc's
VMBundle.Config format, storing VM settings in config.plist.
**Manifest System:**
- Add VPhoneVirtualMachineManifest.swift with security-pcc compatible structure
- Add scripts/vm_manifest.py for manifest generation during vm_new
- Update VPhoneCLI to support --config option with CLI overrides
- Update vm_create.sh to generate config.plist with CPU/memory/screen settings
**Environment Variables:**
- CPU/MEMORY/DISK_SIZE now only used during vm_new (written to manifest)
- boot/boot_dfu automatically read from config.plist
- Remove unused CFW_INPUT variable (overridden by scripts internally)
- Document remaining variables with their usage scope
**Documentation:**
- Update README.md with VM configuration section
- Update docs/README_{zh,ja,ko}.md with translated VM configuration docs
- Update Makefile help output with vm_new options and config.plist usage
- Fix fw_patch_jb description: "dev + JB extensions"
- Fix restore_get_shsh description: "Dump SHSH response from Apple"
**Code Quality:**
- Add VPhoneVirtualMachineRefactored.swift demonstrating code-clarity principles
- Extract 200+ line init into focused configuration methods
- Improve naming: hardwareModel, graphicsConfiguration, soundDevice
- Add BatteryConnectivity enum for magic numbers
- Create research/manifest_and_refactoring_summary.md with full analysis
**Compatibility with security-pcc:**
- Platform type: Fixed vresearch101 (iPhone-only)
- Network: NAT only (no bridging/host-only needed)
- Added: ScreenConfig and SEP storage (iPhone-specific)
- Removed: VirtMesh plugin support (PCC-specific)
docs: add machineIdentifier storage analysis
Research and validate the integration of machineIdentifier into config.plist.
**Findings:**
- security-pcc stores machineIdentifier in config.plist (same approach)
- VZMacAuxiliaryStorage creation is independent of machineIdentifier
- VZMacMachineIdentifier only requires Data representation, not file source
- No binding or validation between components
**Conclusion:**
- ✅ No compatibility issues
- ✅ Matches security-pcc official implementation
- ✅ Proper handling of first-boot creation and data recovery
- ✅ Safe to use
Delete VPhoneVirtualMachineRefactored.swift
refactor: integrate machineIdentifier into config.plist
Move machineIdentifier storage from standalone machineIdentifier.bin file
into the central config.plist manifest for simpler VM configuration.
**Changes:**
- VPhoneVirtualMachineManifest: Remove machineIDFile field
- VPhoneVirtualMachine: Load/create machineIdentifier from manifest
- VPhoneCLI: Remove --machine-id parameter, require --config
- Makefile: Remove --machine-id from boot/boot_dfu targets
- vm_manifest.py: Remove machineIDFile from manifest structure
**Behavior:**
- First boot: Creates machineIdentifier and saves to config.plist
- Subsequent boots: Loads machineIdentifier from config.plist
- Invalid/empty machineIdentifier: Auto-regenerates and updates manifest
- All VM configuration now centralized in single config.plist file
**File cleanup:**
- Move VPhoneVirtualMachineRefactored.swift to research/ as reference
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
