How danielpaulus/go-ios works
1. Repository shape
This is a Go workspace built around a core iOS automation library plus multiple entrypoints: the main ios CLI at the repo root, a separate experimental restapi service, and smaller helper binaries such as cmd/configure and cmd/cdc-ncm. The architecture is centered on talking to real iOS devices, not on a browser/server UI.
2. Core boundary: the ios/ package tree
The ios/ directory is the main subsystem. It contains the device communication stack, protocol codecs, and one package per Apple service or feature area. Most commands and APIs are thin orchestration layers over these packages.
3. Device connectivity layer
The lowest-level flow starts with device discovery and connection setup: discover, listdevices, listen, connect, startsession, stopsession, and pair/readpair. This layer handles host-to-device trust state, pair records, and the initial transport that everything else depends on.
4. Transport and tunnel infrastructure
Communication reaches devices through Apple transports like usbmux/lockdown, plus newer tunnel support for iOS 17+. The ios/tunnel package is explicitly cross-platform with Darwin, Linux, and Windows implementations, including user-space and TUN/Wintun paths. This is a major architectural boundary because many higher-level commands depend on whether the device is reachable through USB, a tunnel, or Remote Service Discovery.
5. Protocol/serialization layer
A large part of the codebase is devoted to decoding Apple-specific wire formats: plistcodec, xpc, dtx_codec, nskeyedarchiver, and opack. These packages convert binary protocol payloads into Go structures and back. In a diagram, this is the transformation layer between raw device bytes and typed service calls.
6. Device service clients
The subpackages under ios/ map to distinct iPhone/iPad services: afc, house_arrest, fileservice, installationproxy, imagemounter, debugserver, debugproxy, instruments, testmanagerd, syslog, diagnostics, crashreport, springboard, mobileactivation, misagent, notificationproxy, and others. Each one is a client for a specific Apple daemon or service endpoint and sits above the transport/codecs.
7. High-level workflows
User-facing features are built by combining those service clients: app install/start/kill, file transfer, developer disk image mounting, screenshotting, log streaming, device state changes, accessibility controls, test execution, location simulation, profile management, and supervision/preparation. These are orchestration flows rather than single-protocol calls, so they form the “application logic” tier above the service clients.
8. XCTest / WebDriverAgent execution path
Test execution is a distinct subsystem centered on ios/testmanagerd and related DTX/NSKeyedArchiver handling. It supports running XCUITests and WebDriverAgent across platforms, which implies a flow from CLI/API → test manager setup → DTX channel messaging → device-side test listener/runtime coordination.
9. Debugging and reverse-engineering tools
ios/debugproxy, ios/debugserver, and ios/dproxy expose a reverse-engineering path that dumps or forwards Apple protocol traffic. This is useful both as an end-user feature and as an internal visibility tool for understanding device/service interactions. It is a separate concern from the “production” automation commands.
10. Cross-platform networking support
The ncm/ module and cmd/cdc-ncm binary are a separate Go module for USB/network management on Linux. Together with ios/pcap and parts of ios/tunnel, they support lower-level network attachment and traffic inspection needed for device discovery, IP finding, and tunnel operation.
11. API surface
The root CLI is the primary interface, with output designed to be machine-readable JSON. The restapi/ module wraps a subset of the same capabilities behind an HTTP server with routes, middleware, streaming endpoints, and WDA-related endpoints. Architecturally, this is an alternate frontend over the same device-control backend.
12. Platform-specific behavior
The codebase is strongly OS-aware. Some functionality is gated by Linux/Windows/macOS-specific implementations, especially around tunnels and USB networking. This matters for architecture because the same high-level command may take different transport paths depending on host OS and device/iOS version.
13. External dependencies and services
The repo interacts with real Apple device services, Apple activation and developer-image endpoints, and in some cases a local proxy or HTTP proxy for downloads/activation. For iOS 17+, tunnel setup becomes a prerequisite for many operations. Those external dependencies are part of the runtime architecture, not just build tooling.
14. Validation and fixtures
The many integration tests and binary fixtures in ios/dtx_codec, ios/nskeyedarchiver, ios/instruments, ios/testmanagerd, and service-specific packages show that protocol compatibility is a first-class concern. The repo is built around real wire-level contracts, so tests are heavily fixture-driven and device-integration-oriented.
15. Packaging and delivery
GitHub Actions, the npm publishing wrapper, and the Dockerfile for usbmuxd-related builds support distribution across platforms. They do not change the runtime architecture, but they explain how the CLI and helper binaries are packaged and delivered to end users.
Main entry points: main.go ios CLI · appservice.go device workflows · discover.go discover · lockdown.go lockdown
Components 24
Interfaces
CLI and HTTP entrypoints
Connectivity
Discovery, pairing, sessions, and device reachability
- discover · Finds attached devices and starts the reachability flow.
ios/discover.go - listdevices · Enumerates connected devices for CLI and automation use.
ios/listdevices.go - pairing · Reads and stores pair records used to establish trusted host relationships.
ios/pair.go - session · Starts and stops lockdown or service sessions against a device.
ios/startsession.go - lockdown · Core control layer for device state, preferences, and service startup.
ios/lockdown.go
Transport
USB, lockdown, tunnel, and network attachment
Protocols
Wire formats and serialization layers
- plist codec · Encodes and decodes Apple property list payloads.
ios/plistcodec.go - XPC/DTX · Binary message codecs for XPC and DTX-based services.
ios/xpc/xpc.go - NSKeyedArchiver · Archives and unarchives Apple object graphs used by test and instruments flows.
ios/nskeyedarchiver/archiver.go
Services
Apple service clients and device-side capabilities
- AFC · Device file system access client for app containers and transfers.
ios/afc/afc.go - install proxy · Installs, queries, and manages applications on the device.
ios/installationproxy/installationproxy.go - image mounter · Downloads and mounts developer disk images and personalized images.
ios/imagemounter/imagemounter.go - debug stack · Reverse-engineering path for debugserver, debugproxy, and protocol dumping.
ios/debugproxy/debugproxy.go - instruments · Device-state, metrics, screenshot, and process-control clients.
ios/instruments/instruments_metrics.go - testmanagerd · XCTest and WebDriverAgent orchestration over DTX and archived payloads.
ios/testmanagerd/xcuitestrunner.go
Workflows
Higher-level automation flows built on service clients
- device workflows · High-level app install, file transfer, screenshot, logging, accessibility, and supervision workflows.
ios/appservice/appservice.go - testing flow · Runs XCUITests and WDA through testmanagerd, DTX, and archiver support.
ios/testmanagerd/xcuitestrunner.go
Tooling
Auxiliary binaries and cross-platform helpers
- configure · Small setup command for local configuration tasks.
cmd/configure/configure.go - cdc-ncm · USB/network helper binary for Linux device networking.
cmd/cdc-ncm/main.go - networking · USB networking and traffic inspection support shared by tunnel and device discovery paths.
ncm/ncm.go
Connections 31
- ios CLI → discover: device lookup · The CLI starts by finding reachable devices.
- ios CLI → listdevices: inventory · Lists attached devices for user-facing commands.
- ios CLI → pairing: trust setup · Pairs or reads pair records before privileged operations.
- ios CLI → session: open/close · Starts and stops device sessions.
- ios CLI → device workflows: automation · Invokes the higher-level device workflows.
- ios CLI → testing flow: tests · Runs XCTest and WDA orchestration.
- REST API → device workflows: backend · HTTP routes wrap the same automation backend.
- REST API → testing flow: wda tests · Exposes test execution and WDA-related endpoints.
- discover → usbmux: usb path · Discovery uses USB transport when devices are attached locally.
- discover → RSD: remote path · Discovery can fall back to Remote Service Discovery.
- discover → tunnel: iOS 17+ · Modern devices may require tunnel reachability.
- pairing → lockdown: pair records · Pairing feeds the trusted lockdown state.
- session → lockdown: service session · Sessions are established through lockdown.
- lockdown → plist codec: payloads · Lockdown exchanges plist-encoded messages.
- lockdown → usbmux: transport · Lockdown talks over USB transport when available.
- tunnel → usbmux: fallback · Tunnel setup still depends on underlying device attachment and discovery.
- XPC/DTX → NSKeyedArchiver: archives · DTX-based services exchange archived Objective-C payloads.
- AFC → plist codec: file ops · File service requests are encoded as Apple wire payloads.
- install proxy → plist codec: install msgs · App install and query traffic uses plist-based messages.
- image mounter → plist codec: image reqs · Developer image mounting uses plist requests and responses.
- debug stack → XPC/DTX: traffic · Debug tooling forwards or dumps protocol traffic.
- instruments → XPC/DTX: telemetry · Instruments clients communicate through DTX channels.
- testmanagerd → XPC/DTX: test channel · XCTest execution is driven through DTX messaging.
- testmanagerd → NSKeyedArchiver: xctest data · Test configuration and listener payloads use keyed archives.
- device workflows → AFC: files · Workflows use AFC for file transfer and container access.
- device workflows → install proxy: apps · App install and launch flows depend on installation proxy.
- device workflows → image mounter: dev image · Developer disk image mounting is part of device preparation.
- device workflows → instruments: state · Screenshots, logs, accessibility, location, and process control route through instruments-style services.
- testing flow → testmanagerd: runner · The test workflow is centered on testmanagerd orchestration.
- networking → tunnel: linux/win · USB networking support underpins tunnel and attachment paths.
- networking → discover: ip find · Network attachment helps discover and reach devices.