How VPhoneAppDelegate Lifecycle Manages GUI and Host Control in vphone-cli

The VPhoneAppDelegate serves as the central coordinator that boots the virtual iPhone, conditionally instantiates the macOS graphical interface based on CLI flags, and maintains the host-control socket connection that synchronizes UI state with the guest daemon's capabilities.

In the Lakr233/vphone-cli repository, the VPhoneAppDelegate (defined in sources/vphone-cli/VPhoneAppDelegate.swift) implements the NSApplicationDelegate protocol to drive the entire application lifecycle. It bridges the gap between the virtualization engine (VPhoneVirtualMachine), the macOS GUI stack, and the host-side control channel (VPhoneControl) used to communicate with the guest vphoned daemon via virtio sockets.

Application Launch and Signal Handling

The lifecycle begins in applicationDidFinishLaunching, which configures the process environment and initiates the asynchronous VM startup. First, it sets the activation policy based on the cli.noGraphics flag to determine whether the app appears in the Dock (lines 26‑27).

To ensure clean shutdown when the user sends Ctrl+C, the delegate installs a DispatchSourceSignal handler for SIGINT. This converts the POSIX signal into a graceful NSApp.terminate call on the main queue (lines 28‑35).

func applicationDidFinishLaunching(_: Notification) {
    NSApp.setActivationPolicy(cli.noGraphics ? .prohibited : .regular)

    // Graceful Ctrl-C shutdown
    signal(SIGINT, SIG_IGN)
    let src = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
    src.setEventHandler { 
        print("\n[vphone] SIGINT — shutting down")
        NSApp.terminate(nil) 
    }
    src.activate()
    sigintSource = src

    // Launch VM on the main actor
    Task { @MainActor in
        try await self.startVirtualMachine()
    }
}

Virtual Machine Initialization

The private startVirtualMachine() method resolves command-line options, validates the ROM file, and instantiates the VPhoneVirtualMachine (lines 49‑78). After storing the VM instance in self.vm, it calls vm.start(forceDFU:) to begin the boot sequence (lines 79‑80).

Immediately after the VM starts, the delegate creates the host-side VPhoneControl object. This establishes the virtio socket connection to the guest. Depending on the cli.noGraphics setting, it then proceeds to build the GUI components or runs in headless mode.

Conditional GUI Assembly

When graphics are enabled (!cli.noGraphics), the delegate constructs the entire visual stack before the VM window appears. The assembly occurs in three stages:

1. Window Controller: Instantiates VPhoneWindowController and calls showWindow(for:screenWidth:screenHeight:screenScale:keyHelper:control:ecid:), which creates the capture view and registers a VPhoneKeyHelper to forward keyboard events into the VM (lines 101‑112).

2. Menu Controller: Creates VPhoneMenuController, injecting references to the keyHelper, control, and VM. It attaches closures that open auxiliary windows for Files, Keychain, and Apps management (lines 124‑139).

3. Host Services: Connects the VPhoneHostControl server to the window's capture view, enabling screen recording, screenshot capture, and camera forwarding (lines 155‑166).

if !cli.noGraphics {
    let keyHelper = VPhoneKeyHelper(vm: vm, control: control)
    let wc = VPhoneWindowController()
    wc.showWindow(for: vm.virtualMachine,
                  screenWidth: options.screenWidth,
                  screenHeight: options.screenHeight,
                  screenScale: options.screenScale,
                  keyHelper: keyHelper,
                  control: control,
                  ecid: vm.ecidHex)
    windowController = wc

    let mc = VPhoneMenuController(keyHelper: keyHelper, control: control)
    mc.vm = vm
    mc.captureView = wc.captureView
    // ... configure File/Keychain/Apps callbacks ...
    menuController = mc
}

Host Control Synchronization

The VPhoneControl instance exposes two critical callbacks that drive the VPhoneAppDelegate host control lifecycle: onConnect and onDisconnect. These fire when the guest daemon advertises or withdraws capabilities.

When the connection opens, the delegate updates menu item availability based on the capability set. If the guest advertises "location", the delegate automatically starts location forwarding. If "ipa_install" is present, it enables the install menu item and triggers any auto-install requested via CLI (lines 68‑90).

control.onConnect = { [weak mc, weak provider = locationProvider] caps in
    mc?.updateConnectAvailability(available: true)
    mc?.updateInstallAvailability(available: caps.contains("ipa_install"))
    
    if caps.contains("location") { 
        provider?.startForwarding() 
    }
    
    Task { @MainActor in 
        await self?.installPackageIfRequested(caps: caps) 
    }
}

control.onDisconnect = { [weak mc, weak provider = locationProvider] in
    mc?.updateConnectAvailability(available: false)
    provider?.stopReplay()
    provider?.stopForwarding()
}

On disconnect, the delegate disables UI actions and stops background services like location replay to prevent orphaned processes.

Graceful Shutdown

The lifecycle concludes through two pathways. When the user closes the last window, applicationShouldTerminateAfterLastWindowClosed returns !cli.noGraphics, meaning the app exits only when running in graphical mode (lines 62‑63).

When termination proceeds, applicationWillTerminate stops the VPhoneHostControl server to release the local socket and halt any active screen recording or camera forwarding sessions (lines 58‑59).

func applicationWillTerminate(_: Notification) {
    hostControl?.stop()
}

Summary

• Single Entry Point: The VPhoneAppDelegate guarantees the VM launches exactly once via applicationDidFinishLaunching, isolating boot logic from the NSApplication runtime.
• Graphics Agnostic: GUI components are instantiated only when cli.noGraphics is false, allowing the same codebase to run headless servers and full desktop clients.
• Capability-Driven UI: Menu items and host services activate dynamically based on the guest daemon's advertised capabilities ("ipa_install", "location"), preventing unavailable actions from cluttering the interface.
• Clean Teardown: Signal handlers and termination delegates ensure the host control socket, location providers, and recording services stop before the process exits, preventing resource leaks.

Frequently Asked Questions

How does VPhoneAppDelegate handle headless mode?

When the --no-graphics flag is passed, applicationDidFinishLaunching sets NSApp.setActivationPolicy(.prohibited) and skips the instantiation of VPhoneWindowController and VPhoneMenuController. The app runs solely as a virtualization host with the control channel active, exiting immediately when the VM shuts down.

What triggers the host control connection lifecycle?

The VPhoneControl object initiates an asynchronous connection to the guest virtio socket immediately after the VM starts. The onConnect callback fires when the guest daemon sends its capability manifest, and onDisconnect triggers if the socket closes or the guest reboots, disabling dependent UI features.

How is the GUI kept in sync with guest capabilities?

The delegate registers capability-specific handlers inside the control.onConnect closure. For example, it calls mc?.updateInstallAvailability(available: caps.contains("ipa_install")) to toggle the Install IPA menu item. This ensures the interface reflects only the services currently supported by the running guest OS.

What happens when the user presses Ctrl+C?

The SIGINT signal is captured by a DispatchSourceSignal installed in applicationDidFinishLaunching. Instead of terminating abruptly, the handler prints a diagnostic message and invokes NSApp.terminate(nil), which triggers the standard applicationWillTerminate cleanup sequence to stop the host control server.

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