Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
// MARK: - Socket
/// The local control channel between `vphone-launchpad-cli` and a running
/// Launchpad. The app listens on a Unix socket in its Application Support
/// folder, mode 0600, and serves only peers with its own user ID. Nothing
/// listens on the network: a remote agent reaches it over ssh.
///
/// One connection carries one request. The client writes the request as one
/// JSON line; the app answers with any number of `output` events, streamed
/// while the command runs, and ends with one `done` event. The client closing
/// its end cancels the command where the command supports it.
nonisolated enum VPhoneLaunchpadControl {
static var directory: URL {
FileManager.default.homeDirectoryForCurrentUser
.appendingPathComponent("Library/Application Support/vphone-launchpad", isDirectory: true)
}
static var socketPath: String {
directory.appendingPathComponent("control.sock").path
}
/// Requests are small; a guest request carries at most vphoned's own
/// 1 MiB body limit.
static let maximumRequestLength = 2 << 20
/// Fills `address` with `path`, or returns false when it does not fit.
static func address(_ path: String, into address: inout sockaddr_un) -> Bool {
let bytes = path.utf8CString
guard bytes.count <= MemoryLayout.size(ofValue: address.sun_path) else {
return false
}
address.sun_family = sa_family_t(AF_UNIX)
withUnsafeMutableBytes(of: &address.sun_path) { buffer in
for (index, byte) in bytes.enumerated() {
buffer[index] = UInt8(bitPattern: byte)
}
}
return true
}
/// Writes all of `data`, retrying short writes. False once the peer is gone.
@discardableResult
static func write(_ data: Data, to fd: Int32) -> Bool {
data.withUnsafeBytes { buffer in
var offset = 0
while offset < buffer.count {
let written = Darwin.write(fd, buffer.baseAddress! + offset, buffer.count - offset)
if written < 0, errno == EINTR {
continue
}
guard written > 0 else {
return false
}
offset += written
}
return true
}
}
}
// MARK: - Messages
nonisolated struct VPhoneLaunchpadControlRequest: Codable, Sendable {
/// A command name from `VPhoneLaunchpadControlCommand.all`.
var command: String
var arguments: [String] = []
/// Valued options by name; a flag that is set has the value "true".
var options: [String: String] = [:]
/// Repeatable options (`--block a --block b`) by name, in the order
/// given. Optional, so a request without them still decodes.
var repeated: [String: [String]]?
func option(_ name: String) -> String? {
options[name]
}
/// Where `vm create --kmutil-ssh` carries the builder's password, which
/// vphone-launchpad-cli reads from its environment: no argument holds it.
static let kmutilSSHPasswordOption = "kmutil-ssh-password"
func flag(_ name: String) -> Bool {
options[name] == "true"
}
/// Every value of a repeatable option; empty when it was not given.
func values(_ name: String) -> [String] {
repeated?[name] ?? []
}
}
/// One line from the app. `output` lines stream while a command runs; the
/// last line has `done` set, `ok`, and either a JSON `result` or an `error`.
nonisolated struct VPhoneLaunchpadControlEvent: Codable, Sendable {
var output: String?
var done: Bool?
var ok: Bool?
/// The command's result as a JSON document.
var result: String?
var error: String?
var detail: String?
static func line(_ text: String) -> Self {
Self(output: text)
}
static func success(_ result: String) -> Self {
Self(done: true, ok: true, result: result)
}
static func failure(_ message: String, detail: String? = nil) -> Self {
Self(done: true, ok: false, error: message, detail: detail)
}
func encodedLine() -> Data {
var data = (try? JSONEncoder().encode(self)) ?? Data(#"{"done":true,"ok":false,"error":"unencodable event"}"#.utf8)
data.append(0x0A)
return data
}
}
// MARK: - Commands
/// The commands both sides know. The CLI parses its arguments and prints
/// help from this table; the app dispatches on `name`.
nonisolated struct VPhoneLaunchpadControlCommand: Sendable {
let name: String
/// Positional arguments, in order. A trailing `...` takes the rest.
let arguments: [String]
/// Options that take a value.
let options: [String]
/// Options without a value.
let flags: [String]
/// Options that take a value and may be given more than once.
var repeated: [String] = []
let summary: String
var usage: String {
let positional = arguments.map { "<\($0)>" }
let named = options.map { "[--\($0) <value>]" } + repeated.map { "[--\($0) <value>]..." } + flags.map { "[--\($0)]" }
// exec reads its options only before the arguments it passes on.
let parts = name == "exec" ? named + positional : positional + named
return ([name.replacingOccurrences(of: ".", with: " ")] + parts).joined(separator: " ")
}
var takesRest: Bool {
arguments.last?.hasSuffix("...") == true
}
static let all: [Self] = [
Self(name: "status", arguments: [], options: [], flags: [],
summary: "Host checks, helper, default bundle and machine counts."),
Self(name: "bundle.list", arguments: [], options: [], flags: [],
summary: "Installed VPhone.bundle versions, their checks, and the machines bound to each."),
Self(name: "bundle.install-local", arguments: ["path"], options: [], flags: ["keep-default"],
summary: "Install a VPhone.bundle folder or .zip built on this Mac as <version>-local.<hash> and check it. It becomes the default unless --keep-default; machines keep their own bundle."),
Self(name: "bundle.install-release", arguments: ["version"], options: [], flags: ["keep-default"],
summary: "Download and install a GitHub release (a version, or \"latest\"). It becomes the default unless --keep-default."),
Self(name: "bundle.set-default", arguments: ["version"], options: [], flags: [],
summary: "Make an installed version the default for new machines and library-wide commands, and check it. Machines keep their own bundle."),
Self(name: "bundle.use", arguments: ["version"], options: [], flags: [],
summary: "The old name of bundle set-default."),
Self(name: "bundle.verify", arguments: ["version"], options: [], flags: [],
summary: "Add the execution policy exception, allow vphone-vm if AMFI refuses it, and run host preflight."),
Self(name: "bundle.accept", arguments: ["version"], options: [], flags: ["off"],
summary: "Use a version even though its checks failed (--off takes that back)."),
Self(name: "bundle.remove", arguments: ["version"], options: [], flags: [],
summary: "Remove an installed version no machine is bound to."),
Self(name: "vm.list", arguments: [], options: [], flags: [],
summary: "Machines in every library, with their run state and Core Bundle."),
Self(name: "vm.start", arguments: ["name"], options: ["root", "timeout"], flags: ["headless", "wait"],
summary: "Launch a machine. --wait blocks until vphoned answers on vphone.sock."),
Self(name: "vm.stop", arguments: ["name"], options: ["root"], flags: [],
summary: "Stop a machine: the guest shuts down first, and the virtual machine is ended only if it cannot or does not in time."),
Self(name: "vm.wait", arguments: ["name"], options: ["root", "timeout"], flags: [],
summary: "Wait until vphoned answers on the machine's vphone.sock."),
Self(name: "vm.log", arguments: ["name"], options: ["root", "lines", "kind"], flags: [],
summary: "The last lines of the console log (--kind create, dfu or patch for those logs)."),
Self(name: "vm.create", arguments: ["name"], options: [
"root", "bundle", "iphone-source", "cloudos-source", "device", "cpu", "memory", "disk-size", "network", "preset", "from", "ipsw", "kmutil-ssh",
"slim", "trim", "keep-languages", "service-profile", "remove-apps", "keep-apps",
], flags: ["keep-artifacts", "no-wait", "no-template", "accounts-off"], repeated: ["block", "allow"],
summary: "Create a machine through every step, as New Machine does, bound to --bundle (default: the default bundle): cloned from a template, built first when missing, or restored on its own with --no-template. --preset takes a preset name or the path of a preset plist. --block and --allow turn one patch of --preset off or on, as New Machine's patch list and vphone-cli fw set-patches do: boot-chain ones go into the template, guest ones are applied to the clone. --slim, --trim, --keep-languages, --service-profile, --remove-apps, --keep-apps and --accounts-off shape the template, as in vphone-cli vm create. --ipsw <path> is the ipsw a 2.12.0 bundle stages a kernelcache mix with, as New Machine's ipsw field; a 2.12.1 bundle extracts natively and needs none. --kmutil-ssh <user@host> links an iOS 18 guest's kernel-first mix on that Mac over ssh, as New Machine's macOS builder field, with the password (for ssh and sudo there) from this tool's VPHONE_KMUTIL_SSH_PASSWORD. --from <step> retries a failed creation from that step, with the options it started with."),
Self(name: "vm.set-bundle", arguments: ["name", "version"], options: ["root"], flags: ["update-environment"],
summary: "Bind a machine to another installed version; its host programs change at the next start. --update-environment also redeploys that version's guest environment into the stopped machine. The boot chain stays as created."),
Self(name: "vm.leases", arguments: [], options: [], flags: ["release"],
summary: "DHCP leases on the shared NAT network and the machine that owns each. --release frees the ones iOS guests left with a MAC no machine in any library has, through the root helper."),
Self(name: "cfw.install", arguments: ["name"], options: ["root"], flags: ["keep-artifacts"],
summary: "Install CFW into a stopped machine with its own bundle, through the root helper."),
Self(name: "cfw.update-environment", arguments: ["name"], options: ["root"], flags: [],
summary: "Redeploy the machine's own bundle's guest resources (vphoned and hook dylibs) into it while stopped, and nothing else."),
Self(name: "cfw.update-kernel", arguments: ["name"], options: ["root"], flags: [],
summary: "Swap the stopped machine's Preboot kernelcache for the one its patches resolve to, keeping the data (no restore)."),
Self(name: "guest.send", arguments: ["name", "json"], options: ["root"], flags: [],
summary: "Send one raw vphone.sock request, such as {\"t\":\"tap\",\"x\":645,\"y\":1398}."),
Self(name: "guest.rpc", arguments: ["name", "method", "params..."], options: ["root"], flags: ["screen"],
summary: "Call a vphoned method; params is one JSON object."),
Self(name: "guest.push", arguments: ["name", "local", "path"], options: ["root", "mode"], flags: [],
summary: "Copy a file from this Mac into the guest, streamed, any size. A path ending in / keeps the file's name; --mode is octal, the Mac file's permissions by default."),
Self(name: "guest.pull", arguments: ["name", "path", "local"], options: ["root"], flags: [],
summary: "Copy a file from the guest to this Mac, streamed, any size. local may be a folder; the file replaces it only once complete."),
Self(name: "guest.unlock", arguments: ["name"], options: ["root", "passcode", "timeout"], flags: [],
summary: "Turn the screen on and unlock the guest (vphoned screen.unlock). --passcode enters the passcode of a guest that has one; --timeout is in seconds, 10 by default."),
Self(name: "exec", arguments: ["arguments..."], options: ["bundle"], flags: [],
summary: "Run vphone-cli with these arguments and stream its output: the default bundle's, or that of --bundle <version> given before the arguments."),
]
static func named(_ name: String) -> Self? {
all.first { $0.name == name }
}
}
// MARK: - Parsing
/// Why `vphone-launchpad-cli` cannot send a command line: printed as
/// `error: <message>`, then the detail.
nonisolated struct VPhoneLaunchpadControlUsageError: Error, Equatable {
var message: String
var detail: String?
}
extension VPhoneLaunchpadControlRequest {
/// The request for the words after `vphone-launchpad-cli`. `foreground`
/// is set when `--foreground` is among a command's options.
static func parse(_ words: [String], foreground: inout Bool) throws(VPhoneLaunchpadControlUsageError) -> Self {
typealias Failure = VPhoneLaunchpadControlUsageError
guard let first = words.first else {
throw Failure(message: "no command. Run vphone-launchpad-cli help.")
}
// Two words name a grouped command ("vm start"), one word the others.
var rest = words
var command: VPhoneLaunchpadControlCommand?
if rest.count >= 2, let grouped = VPhoneLaunchpadControlCommand.named("\(rest[0]).\(rest[1])") {
command = grouped
rest.removeFirst(2)
} else if let single = VPhoneLaunchpadControlCommand.named(first) {
command = single
rest.removeFirst()
}
guard let command else {
let group = VPhoneLaunchpadControlCommand.all.filter { $0.name.hasPrefix("\(first).") }
if !group.isEmpty {
throw Failure(message: "\(first) needs a command.", detail: group.map { " \($0.usage)" }.joined(separator: "\n"))
}
throw Failure(message: "unknown command \(words.prefix(2).joined(separator: " ")). Run vphone-launchpad-cli help.")
}
var request = Self(command: command.name)
// exec hands everything after it to vphone-cli untouched, except a
// leading --bundle that picks whose vphone-cli runs.
if command.name == "exec" {
if let first = rest.first, first == "--bundle" || first.hasPrefix("--bundle=") {
rest.removeFirst()
if first == "--bundle" {
guard !rest.isEmpty else {
throw Failure(message: "--bundle needs a value.")
}
request.options["bundle"] = rest.removeFirst()
} else {
request.options["bundle"] = String(first.dropFirst("--bundle=".count))
}
}
request.arguments = rest
return request
}
var positional: [String] = []
var repeated: [String: [String]] = [:]
var index = 0
while index < rest.count {
let word = rest[index]
index += 1
if word == "--" {
positional += rest[index...]
break
}
guard word.hasPrefix("--"), word.count > 2 else {
positional.append(word)
continue
}
var name = String(word.dropFirst(2))
var value: String?
if let equals = name.firstIndex(of: "=") {
value = String(name[name.index(after: equals)...])
name = String(name[..<equals])
}
if name == "foreground", value == nil {
foreground = true
} else if command.flags.contains(name), value == nil {
request.options[name] = "true"
} else if command.options.contains(name) || command.repeated.contains(name) {
if value == nil, index < rest.count {
value = rest[index]
index += 1
}
guard let value else {
throw Failure(message: "--\(name) needs a value.")
}
if command.repeated.contains(name) {
repeated[name, default: []].append(value)
} else {
request.options[name] = value
}
} else {
throw Failure(message: "unknown option --\(name).", detail: "usage: vphone-launchpad-cli \(command.usage)")
}
}
// A trailing `...` argument may be empty.
let named = command.takesRest ? command.arguments.count - 1 : command.arguments.count
guard positional.count >= named, command.takesRest || positional.count == named else {
throw Failure(message: "wrong number of arguments.", detail: "usage: vphone-launchpad-cli \(command.usage)")
}
// The app runs elsewhere; a relative path means nothing to it.
if let index = ["bundle.install-local": 0, "guest.push": 1, "guest.pull": 2][command.name] {
positional[index] = URL(fileURLWithPath: positional[index]).standardizedFileURL.path
}
if let root = request.options["root"] {
request.options["root"] = URL(fileURLWithPath: root).standardizedFileURL.path
}
// A preset file, as `VPhoneLaunchpadPatchSelection.isPresetFile` tells it from a name.
if let preset = request.options["preset"], preset.contains("/") || preset.hasSuffix(".plist") {
request.options["preset"] = URL(fileURLWithPath: (preset as NSString).expandingTildeInPath).standardizedFileURL.path
}
request.arguments = positional
if !repeated.isEmpty {
request.repeated = repeated
}
return request
}
}