How to Report a Bug in vphone-cli: A Complete Guide for macOS Virtualization

To report a bug in vphone-cli, collect your macOS version, hardware model, Swift version, and the exact commit hash from VPhoneBuildInfo.swift, then provide numbered reproduction steps, console output or crash logs from VPhoneAppDelegate.swift, and the guest daemon response from VPhoneControl.swift before opening a GitHub issue.

vphone-cli is a macOS-only command-line tool that boots a virtual iPhone using Apple's Virtualization.framework. Because the project spans host-side Swift UI, VM configuration, and guest-side daemon communication via vsock, effective bug reports must include specific diagnostic details from multiple subsystems to help maintainers reproduce and fix issues quickly.

Essential Information for a High-Quality Bug Report

Environment and Version Details

Since vphone-cli requires macOS 15+ with SIP and AMFI disabled, your report must specify your exact platform configuration. Include your macOS version (e.g., 15.1), Mac hardware model, Swift version from swift --version, and the exact vphone-cli build identifier. You can retrieve the commit hash programmatically using the build-time constant in VPhoneBuildInfo.swift:

import VPhoneBuildInfo

print("vphone-cli version: \(VPhoneBuildInfo.commitHash)")

Alternatively, run git rev-parse HEAD in the repository root to identify the source tree that produced your binary.

Step-by-Step Reproduction

Provide a concise, numbered list that reproduces the problem from a fresh checkout. For example:

1. Clone the repository and run make setup_venv && make build
2. Execute ./vphone-cli boot with any custom flags
3. Describe the specific action that triggers the failure

This allows maintainers to verify the bug using the same entry points defined in VPhoneCLI.swift.

Observed vs Expected Behavior

Clearly state what happened versus what should have happened. Attach console output, crash logs, or UI screenshots. If the application crashed, include the stack trace. If the VM failed to boot, note the exact error message from VPhoneError.swift.

Configuration and Logs

Document any non-default settings from VPhoneVirtualMachine.Options or hardware model overrides in VPhoneHardwareModel.swift. Include relevant logs from three critical sources:

• Host-side logs: Written by the NSApplication delegate in VPhoneAppDelegate.swift
• VM logs: Events from VZVirtualMachine handled in VPhoneVirtualMachine.swift
• Guest-side logs: Output from vphoned inside the VM, accessible via the vsock client in VPhoneControl.swift

Use this snippet to extract host-side logs:

import VPhoneAppDelegate

class Logger {
    static func dumpLog() -> String {
        let logPath = "\(NSHomeDirectory())/Library/Logs/vphone-cli.log"
        return (try? String(contentsOfFile: logPath)) ?? "No log found"
    }
}

print(Logger.dumpLog())

Key Source Files Referenced in Bug Reports

When describing your issue, reference these specific files from the repository to help maintainers locate the problem:

• sources/vphone-cli/VPhoneAppDelegate.swift: Sets up the NSApplication, handles termination, and writes host logs
• sources/vphone-cli/VPhoneVirtualMachine.swift: Configures and controls the VZVirtualMachine instance
• sources/vphone-cli/VPhoneControl.swift: Host-side vsock client that communicates with the guest daemon
• sources/vphone-cli/VPhoneCLI.swift: Parses command-line arguments and launches workflows
• sources/vphone-cli/VPhoneHardwareModel.swift: Defines the virtual hardware model (PV = 3) via the Dynamic library
• sources/vphone-cli/VPhoneError.swift: Central error enum used throughout the codebase

How to Submit Your Bug Report

Once you have gathered the environment details, reproduction steps, and logs:

1. Navigate to the Issues tab of the Lakr233/vphone-cli repository
2. Click New issue and select the Bug report template
3. Fill in the sections with your collected data, attaching log files or screenshots as needed
4. Submit the issue

Maintainers will triage the report, attempt reproduction using the steps provided, and may request additional information such as a minimal test case or core dump.

Summary

• vphone-cli requires macOS 15+ with SIP/AMFI disabled, so always include your exact macOS version and hardware model
• Capture the commit hash from VPhoneBuildInfo.swift using git rev-parse HEAD to identify your build
• Structure your report with numbered reproduction steps starting from make build
• Include logs from VPhoneAppDelegate.swift (host), VPhoneVirtualMachine.swift (VM), and VPhoneControl.swift (guest communication)
• Reference specific source files like VPhoneCLI.swift or VPhoneHardwareModel.swift when describing configuration issues
• Submit via GitHub Issues using the bug report template

Frequently Asked Questions

What macOS versions are supported by vphone-cli?

vphone-cli requires macOS 15 or later because it relies on specific APIs within Apple's Virtualization.framework that are only available in recent versions. Additionally, System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI) must be disabled for the virtual machine to boot properly.

How do I capture logs from the guest daemon?

The guest daemon vphoned runs inside the virtualized iPhone environment. You can query its status and retrieve logs using the vsock client implemented in VPhoneControl.swift:

import VPhoneControl

VPhoneControl.shared.send(command: "ping") { response in
    print("Guest daemon replied: \(response)")
}

Which log files are most important for VM boot failures?

For boot-related issues, prioritize logs from VPhoneVirtualMachine.swift which handles VZVirtualMachine events, and VPhoneAppDelegate.swift which captures host-side initialization errors. The interaction between these two components typically reveals whether the failure occurs during VM configuration or guest handoff.

How do I list available VM options when reporting configuration bugs?

You can print the default VM configuration to verify if custom settings in VPhoneVirtualMachine.Options are causing the issue:

import VPhoneVirtualMachine

let options = VPhoneVirtualMachine.Options.default
print("Default VM options: \(options)")

This output helps maintainers determine if non-standard hardware models defined in VPhoneHardwareModel.swift or modified command-line flags from VPhoneCLI.swift are contributing to the bug.

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