How VPhoneIPAInstaller Extracts, Re-Signs, and Installs IPAs to the Guest over vsock

VPhoneIPAInstaller validates IPA archives, extracts their payloads, re-signs Mach-O binaries with private virtualization entitlements, and transmits the package to the guest VM via vsock where the vphoned daemon completes installation using iOS MobileInstallation APIs.

VPhoneIPAInstaller serves as the bridge between the host macOS environment and the guest virtual iPhone in the Lakr233/vphone-cli project. This component manages the complete deployment pipeline—from file validation to final app registration—using a lightweight vsock-based control channel that avoids direct filesystem sharing between host and guest.

Package Validation and Extraction

The installation process begins with strict file validation and archive extraction. The system ensures only properly formatted iOS packages enter the pipeline before unpacking their contents for modification.

Validating IPA Extensions

In sources/vphone-cli/VPhoneInstallPackage.swift, the isSupportedFile(_:) method checks the Uniform Type Identifier (UTI) and file extension to confirm the input is either a standard .ipa or signed-variant .tipa package. This gatekeeper prevents unsupported archives from proceeding to the extraction phase, which would otherwise corrupt the temporary workspace.

Extracting the Payload

Once validated, the installer treats the IPA as a ZIP archive and extracts its contents into a temporary directory created via FileManager. The extraction logic iterates entry-by-entry through the archive, preserving the Payload directory structure required for iOS applications. The installer then recursively scans this directory to locate every Mach-O binary—including the main app executable, app extensions, frameworks, and dynamic libraries—that requires re-signing.

Re-Signing Mach-O Binaries with Private Entitlements

Because the virtual iPhone runs with PV=3 virtualization privileges, all binaries must carry specific private entitlements that standard development IPAs lack. The re-signing stage injects these capabilities before the guest VM will accept the package.

The VPhoneSigner Implementation

The VPhoneSigner class in sources/vphone-cli/VPhoneSigner.swift drives the signature generation process. For each discovered Mach-O binary, the signer invokes the system codesign tool with the --force flag to replace existing signatures and the --entitlements flag pointing to the bundled vphone.entitlements file. This process also injects a fake com.apple.mobile.installation identifier, ensuring the guest recognizes the payload as a trusted application bundle.

Entitlements Configuration

The private entitlements required for container creation and virtualization access are stored in sources/vphone.entitlements. Key entries include com.apple.private.security.container-creation and other PV=3-specific permissions that allow the app to run inside the Virtualization.framework guest. A dummy provisioning profile included in the repository satisfies iOS code-signing verification during development; production deployments may substitute this with enterprise certificates.

Transferring Packages via vsock

After re-signing completes on the host, the package transmits to the guest through a dedicated vsock channel. This socket type provides Unix-domain semantics across the VM boundary without exposing the host filesystem directly to the guest iOS environment.

Host-Side Control Channel (VPhoneControl)

The VPhoneControl class in sources/vphone-cli/VPhoneControl.swift manages the host-side vsock client. It constructs a JSON-encoded installation request containing the action type ("install"), package identifier, version, and the absolute path to the temporary directory holding the re-signed payload. This client connects to port 1337 on the guest and transmits the request using a length-prefixed JSON protocol—a 4-byte length header followed by the UTF-8 encoded payload.

Guest Daemon Protocol (vphoned)

On the guest side, the vphoned Objective-C daemon (located in scripts/vphoned) listens on vsock port 1337. Upon receiving the length prefix, it parses the JSON request and validates the action field. The daemon then prepares the target directory structure within /var/mobile/Containers/Bundle/Application/ for the incoming application bundle.

Guest-Side Installation Flow

With the payload positioned in the sandboxed container hierarchy, the guest daemon triggers the standard iOS installation mechanism.

The vphoned daemon invokes the private MobileInstallation framework API installApplicationAtURL:options:completion: to register the app with Launch Services and SpringBoard. Because the host already re-signed the binaries with proper entitlements and provisioning, the guest performs no additional signature verification, dramatically accelerating the installation process. Upon completion, the daemon returns a JSON status object—either {"status":"ok", "detail":"<install-log>"} or an error description—which transmits back through the vsock channel to the host CLI. The UI layer in VPhoneInstallPackage.swift formats this response using successMessage(for:detail:) to present either a concise confirmation or detailed installer logs to the user.

Code Implementation Example

The following Swift snippet demonstrates the core workflow that VPhoneMenuApps.swift orchestrates when users select the Install IPA option. This example excludes UI plumbing to highlight the extraction, signing, and vsock transmission phases:

import Foundation

func installIPA(at url: URL) async throws {
    // 1. Validate file type
    guard VPhoneInstallPackage.isSupportedFile(url) else {
        throw NSError(domain: "IPAInstaller", code: 1,
                      userInfo: [NSLocalizedDescriptionKey: "Unsupported file"])
    }
    
    // 2. Create temporary workspace
    let workDir = FileManager.default.temporaryDirectory
        .appendingPathComponent(UUID().uuidString)
    try FileManager.default.createDirectory(at: workDir,
                                            withIntermediateDirectories: true)
    
    // 3. Extract IPA (ZIP archive)
    try Archive.unzipFile(at: url, to: workDir)
    
    // 4. Re-sign all Mach-O binaries
    let binaries = try workDir.recursivelyFindMachOs()
    let entitlementsPath = Bundle.main.path(forResource: "vphone", 
                                            ofType: "entitlements")!
    for binary in binaries {
        try VPhoneSigner.signMachO(at: binary,
                                   withEntitlements: entitlementsPath)
    }
    
    // 5. Transmit installation request over vsock
    let control = VPhoneControl.shared
    let request = ["action": "install", "path": workDir.path]
    let response = try await control.sendJSON(request)
    
    // 6. Format success message
    print(VPhoneInstallPackage.successMessage(
        for: url.lastPathComponent,
        detail: response["detail"] as? String ?? ""
    ))
}

The production implementation uses VPhoneControl.send(lengthPrefixedJSON:) for wire-protocol compliance and includes comprehensive error handling for vsock disconnections or signing failures.

Summary

• VPhoneIPAInstaller handles the complete host-to-guest IPA deployment pipeline in Lakr233/vphone-cli.
• Validation occurs via VPhoneInstallPackage.isSupportedFile(_:) to ensure only .ipa and .tipa archives proceed.
• Extraction unzips the archive to a temporary directory where Mach-O binaries are discovered recursively.
• Re-signing applies private PV=3 entitlements using VPhoneSigner and the system codesign tool before transmission.
• vsock transport uses port 1337 with length-prefixed JSON messages between VPhoneControl and the guest vphoned daemon.
• Guest installation leverages the private MobileInstallation API to register the app with SpringBoard without additional signature verification.

Frequently Asked Questions

What file types does VPhoneIPAInstaller support?

The installer accepts iOS application archives with .ipa or .tipa extensions. The isSupportedFile(_:) method in VPhoneInstallPackage.swift validates both the file extension and Uniform Type Identifier (UTI) to ensure compatibility with the extraction and signing pipeline.

Why does the installer re-sign binaries on the host instead of the guest?

Re-signing on the host avoids requiring code-signing certificates or provisioning profiles inside the guest VM. The VPhoneSigner component applies private entitlements like com.apple.private.security.container-creation using the host's codesign tool, allowing the guest vphoned daemon to install the application immediately upon receipt without performing cryptographic operations.

How does the vsock communication protocol work?

The host VPhoneControl client connects to the guest daemon on port 1337 using the vsock address family. It transmits length-prefixed JSON messages—first sending a 4-byte integer representing the payload length, followed by the UTF-8 JSON data. The vphoned daemon parses this request, executes the installation, and returns a similarly formatted JSON response containing status codes and installation logs.

What iOS APIs does the guest daemon use to install applications?

The guest-side vphoned daemon invokes the private MobileInstallation framework method installApplicationAtURL:options:completion: to register the transferred bundle with the iOS Launch Services database and SpringBoard. This API requires the app to already possess valid signatures and entitlements, which the host provides during the re-signing phase.

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