# danielpaulus/go-ios architecture

> Architecture diagram of the GitHub repository danielpaulus/go-ios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielpaulus/go-ios
- Repository: https://github.com/danielpaulus/go-ios

## Overview

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`](https://github.com/danielpaulus/go-ios/blob/main/main.go) (ios CLI), [`ios/appservice/appservice.go`](https://github.com/danielpaulus/go-ios/blob/main/ios/appservice/appservice.go) (device workflows), [`ios/discover.go`](https://github.com/danielpaulus/go-ios/blob/main/ios/discover.go) (discover), [`ios/lockdown.go`](https://github.com/danielpaulus/go-ios/blob/main/ios/lockdown.go) (lockdown)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_interfaces["Interfaces"]
  node_main_cli["ios CLI<br/>root command<br/>[main.go]"]
  node_restapi["REST API<br/>http service<br/>[main.go]"]
end

subgraph group_grp_connectivity["Connectivity"]
  node_discover(("discover<br/>[discover.go]"))
  node_listdevices(("listdevices<br/>device inventory<br/>[listdevices.go]"))
  node_pairing(("pairing<br/>trust state<br/>[pair.go]"))
  node_session(("session<br/>[startsession.go]"))
  node_lockdown(("lockdown<br/>device control<br/>[lockdown.go]"))
end

subgraph group_grp_transport["Transport"]
  node_usbmux(("usbmux<br/>usb transport"))
  node_rsd(("RSD<br/>remote discovery<br/>[rsd.go]"))
  node_tunnel(("tunnel<br/>[tunnel.go]"))
end

subgraph group_grp_protocols["Protocols"]
  node_plistcodec{{"plist codec<br/>serialization<br/>[plistcodec.go]"}}
  node_xpc_dtx{{"XPC/DTX<br/>protocol codecs<br/>[xpc.go]"}}
  node_nskeyedarchiver{{"NSKeyedArchiver<br/>archive codec<br/>[archiver.go]"}}
end

subgraph group_grp_services["Services"]
  node_afc["AFC<br/>file service<br/>[afc.go]"]
  node_installationproxy["install proxy<br/>app install"]
  node_imagemounter["image mounter<br/>developer image<br/>[imagemounter.go]"]
  node_debugstack["debug stack<br/>debug proxy<br/>[debugproxy.go]"]
  node_instruments["instruments<br/>device telemetry"]
  node_testmanagerd["testmanagerd<br/>test runner<br/>[xcuitestrunner.go]"]
end

subgraph group_grp_workflows["Workflows"]
  node_device_apps["device workflows<br/>automation flows<br/>[appservice.go]"]
  node_testing_flow["testing flow<br/>xctest orchestration<br/>[xcuitestrunner.go]"]
end

subgraph group_grp_tooling["Tooling"]
  node_configure_cmd["configure<br/>helper binary<br/>[configure.go]"]
  node_cdc_ncm["cdc-ncm<br/>linux helper<br/>[main.go]"]
  node_networking[("networking<br/>usb/network support<br/>[ncm.go]")]
end

node_main_cli -->|"device lookup"| node_discover
node_main_cli -->|"inventory"| node_listdevices
node_main_cli -->|"trust setup"| node_pairing
node_main_cli -->|"open/close"| node_session
node_main_cli -->|"automation"| node_device_apps
node_main_cli -->|"tests"| node_testing_flow
node_restapi -->|"backend"| node_device_apps
node_restapi -->|"wda tests"| node_testing_flow
node_discover -->|"usb path"| node_usbmux
node_discover -->|"remote path"| node_rsd
node_discover -->|"iOS 17+"| node_tunnel
node_pairing -->|"pair records"| node_lockdown
node_session -->|"service session"| node_lockdown
node_lockdown -->|"payloads"| node_plistcodec
node_lockdown -->|"transport"| node_usbmux
node_tunnel -->|"fallback"| node_usbmux
node_xpc_dtx -->|"archives"| node_nskeyedarchiver
node_afc -->|"file ops"| node_plistcodec
node_installationproxy -->|"install msgs"| node_plistcodec
node_imagemounter -->|"image reqs"| node_plistcodec
node_debugstack -->|"traffic"| node_xpc_dtx
node_instruments -->|"telemetry"| node_xpc_dtx
node_testmanagerd -->|"test channel"| node_xpc_dtx
node_testmanagerd -->|"xctest data"| node_nskeyedarchiver
node_device_apps -->|"files"| node_afc
node_device_apps -->|"apps"| node_installationproxy
node_device_apps -->|"dev image"| node_imagemounter
node_device_apps -->|"state"| node_instruments
node_testing_flow -->|"runner"| node_testmanagerd
node_networking -->|"linux/win"| node_tunnel
node_networking -->|"ip find"| node_discover

click node_main_cli "https://github.com/danielpaulus/go-ios/blob/main/main.go"
click node_restapi "https://github.com/danielpaulus/go-ios/blob/main/restapi/main.go"
click node_configure_cmd "https://github.com/danielpaulus/go-ios/blob/main/cmd/configure/configure.go"
click node_cdc_ncm "https://github.com/danielpaulus/go-ios/blob/main/cmd/cdc-ncm/main.go"
click node_discover "https://github.com/danielpaulus/go-ios/blob/main/ios/discover.go"
click node_listdevices "https://github.com/danielpaulus/go-ios/blob/main/ios/listdevices.go"
click node_pairing "https://github.com/danielpaulus/go-ios/blob/main/ios/pair.go"
click node_session "https://github.com/danielpaulus/go-ios/blob/main/ios/startsession.go"
click node_lockdown "https://github.com/danielpaulus/go-ios/blob/main/ios/lockdown.go"
click node_usbmux "https://github.com/danielpaulus/go-ios/blob/main/ios/usbmuxconnection.go"
click node_rsd "https://github.com/danielpaulus/go-ios/blob/main/ios/rsd.go"
click node_tunnel "https://github.com/danielpaulus/go-ios/blob/main/ios/tunnel/tunnel.go"
click node_plistcodec "https://github.com/danielpaulus/go-ios/blob/main/ios/plistcodec.go"
click node_xpc_dtx "https://github.com/danielpaulus/go-ios/blob/main/ios/xpc/xpc.go"
click node_nskeyedarchiver "https://github.com/danielpaulus/go-ios/blob/main/ios/nskeyedarchiver/archiver.go"
click node_afc "https://github.com/danielpaulus/go-ios/blob/main/ios/afc/afc.go"
click node_installationproxy "https://github.com/danielpaulus/go-ios/blob/main/ios/installationproxy/installationproxy.go"
click node_imagemounter "https://github.com/danielpaulus/go-ios/blob/main/ios/imagemounter/imagemounter.go"
click node_debugstack "https://github.com/danielpaulus/go-ios/blob/main/ios/debugproxy/debugproxy.go"
click node_instruments "https://github.com/danielpaulus/go-ios/blob/main/ios/instruments/instruments_metrics.go"
click node_testmanagerd "https://github.com/danielpaulus/go-ios/blob/main/ios/testmanagerd/xcuitestrunner.go"
click node_device_apps "https://github.com/danielpaulus/go-ios/blob/main/ios/appservice/appservice.go"
click node_testing_flow "https://github.com/danielpaulus/go-ios/blob/main/ios/testmanagerd/xcuitestrunner.go"
click node_networking "https://github.com/danielpaulus/go-ios/blob/main/ncm/ncm.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_cli,node_restapi,node_configure_cmd,node_cdc_ncm,node_networking toneBlue
class node_discover,node_listdevices,node_pairing,node_session,node_lockdown toneAmber
class node_usbmux,node_rsd,node_tunnel toneMint
class node_plistcodec,node_xpc_dtx,node_nskeyedarchiver toneRose
class node_afc,node_installationproxy,node_imagemounter,node_debugstack,node_instruments,node_testmanagerd toneIndigo
class node_device_apps,node_testing_flow toneTeal
```

## Components

### Interfaces

CLI and HTTP entrypoints

- [ios CLI](https://github.com/danielpaulus/go-ios/blob/main/main.go): root command · Primary command-line frontend for device automation and JSON output. · `main.go`
- [REST API](https://github.com/danielpaulus/go-ios/blob/main/restapi/main.go): http service · Alternate HTTP frontend that exposes a subset of the device-control backend. · `restapi/main.go`

### Connectivity

Discovery, pairing, sessions, and device reachability

- [discover](https://github.com/danielpaulus/go-ios/blob/main/ios/discover.go): device discovery · Finds attached devices and starts the reachability flow. · `ios/discover.go`
- [listdevices](https://github.com/danielpaulus/go-ios/blob/main/ios/listdevices.go): device inventory · Enumerates connected devices for CLI and automation use. · `ios/listdevices.go`
- [pairing](https://github.com/danielpaulus/go-ios/blob/main/ios/pair.go): trust state · Reads and stores pair records used to establish trusted host relationships. · `ios/pair.go`
- [session](https://github.com/danielpaulus/go-ios/blob/main/ios/startsession.go): device session · Starts and stops lockdown or service sessions against a device. · `ios/startsession.go`
- [lockdown](https://github.com/danielpaulus/go-ios/blob/main/ios/lockdown.go): device control · Core control layer for device state, preferences, and service startup. · `ios/lockdown.go`

### Transport

USB, lockdown, tunnel, and network attachment

- [usbmux](https://github.com/danielpaulus/go-ios/blob/main/ios/usbmuxconnection.go): usb transport · USB transport and response handling for device communication. · `ios/usbmuxconnection.go`
- [RSD](https://github.com/danielpaulus/go-ios/blob/main/ios/rsd.go): remote discovery · Remote Service Discovery support for non-USB device reachability. · `ios/rsd.go`
- [tunnel](https://github.com/danielpaulus/go-ios/blob/main/ios/tunnel/tunnel.go): iOS 17+ tunnel · Cross-platform tunnel stack with Darwin, Linux, and Windows implementations. · `ios/tunnel/tunnel.go`

### Protocols

Wire formats and serialization layers

- [plist codec](https://github.com/danielpaulus/go-ios/blob/main/ios/plistcodec.go): serialization · Encodes and decodes Apple property list payloads. · `ios/plistcodec.go`
- [XPC/DTX](https://github.com/danielpaulus/go-ios/blob/main/ios/xpc/xpc.go): protocol codecs · Binary message codecs for XPC and DTX-based services. · `ios/xpc/xpc.go`
- [NSKeyedArchiver](https://github.com/danielpaulus/go-ios/blob/main/ios/nskeyedarchiver/archiver.go): archive codec · 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](https://github.com/danielpaulus/go-ios/blob/main/ios/afc/afc.go): file service · Device file system access client for app containers and transfers. · `ios/afc/afc.go`
- [install proxy](https://github.com/danielpaulus/go-ios/blob/main/ios/installationproxy/installationproxy.go): app install · Installs, queries, and manages applications on the device. · `ios/installationproxy/installationproxy.go`
- [image mounter](https://github.com/danielpaulus/go-ios/blob/main/ios/imagemounter/imagemounter.go): developer image · Downloads and mounts developer disk images and personalized images. · `ios/imagemounter/imagemounter.go`
- [debug stack](https://github.com/danielpaulus/go-ios/blob/main/ios/debugproxy/debugproxy.go): debug proxy · Reverse-engineering path for debugserver, debugproxy, and protocol dumping. · `ios/debugproxy/debugproxy.go`
- [instruments](https://github.com/danielpaulus/go-ios/blob/main/ios/instruments/instruments_metrics.go): device telemetry · Device-state, metrics, screenshot, and process-control clients. · `ios/instruments/instruments_metrics.go`
- [testmanagerd](https://github.com/danielpaulus/go-ios/blob/main/ios/testmanagerd/xcuitestrunner.go): test runner · XCTest and WebDriverAgent orchestration over DTX and archived payloads. · `ios/testmanagerd/xcuitestrunner.go`

### Workflows

Higher-level automation flows built on service clients

- [device workflows](https://github.com/danielpaulus/go-ios/blob/main/ios/appservice/appservice.go): automation flows · High-level app install, file transfer, screenshot, logging, accessibility, and supervision workflows. · `ios/appservice/appservice.go`
- [testing flow](https://github.com/danielpaulus/go-ios/blob/main/ios/testmanagerd/xcuitestrunner.go): xctest orchestration · Runs XCUITests and WDA through testmanagerd, DTX, and archiver support. · `ios/testmanagerd/xcuitestrunner.go`

### Tooling

Auxiliary binaries and cross-platform helpers

- [configure](https://github.com/danielpaulus/go-ios/blob/main/cmd/configure/configure.go): helper binary · Small setup command for local configuration tasks. · `cmd/configure/configure.go`
- [cdc-ncm](https://github.com/danielpaulus/go-ios/blob/main/cmd/cdc-ncm/main.go): linux helper · USB/network helper binary for Linux device networking. · `cmd/cdc-ncm/main.go`
- [networking](https://github.com/danielpaulus/go-ios/blob/main/ncm/ncm.go): usb/network support · USB networking and traffic inspection support shared by tunnel and device discovery paths. · `ncm/ncm.go`

## Connections

- 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.
