{"id":30145402,"url":"https://github.com/appium/appium-ios-remotexpc","last_synced_at":"2026-05-30T22:00:49.703Z","repository":{"id":301312481,"uuid":"967881101","full_name":"appium/appium-ios-remotexpc","owner":"appium","description":"A Node.js library that enables communication with iOS devices using remote XPC services. It supports device lockdown, property-list (plist) handling, system-log access, IPv6 tunneling to iOS devices, and more. Originally built for Appium automation.","archived":false,"fork":false,"pushed_at":"2026-05-30T19:45:02.000Z","size":7183,"stargazers_count":27,"open_issues_count":9,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-05-30T20:11:41.724Z","etag":null,"topics":["automation","ios","xpc"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"open_collective":"appium"}},"created_at":"2025-04-17T06:34:56.000Z","updated_at":"2026-05-26T20:28:27.000Z","dependencies_parsed_at":"2025-08-26T16:42:30.500Z","dependency_job_id":"24c9da92-6b2c-48f5-84f1-5c7975dd3240","html_url":"https://github.com/appium/appium-ios-remotexpc","commit_stats":null,"previous_names":["srinivasantarget/appium-ios-remotexpc","appium/appium-ios-remotexpc"],"tags_count":125,"template":false,"template_full_name":null,"purl":"pkg:github/appium/appium-ios-remotexpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-remotexpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-remotexpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-remotexpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-remotexpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appium","download_url":"https://codeload.github.com/appium/appium-ios-remotexpc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appium%2Fappium-ios-remotexpc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33711018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","ios","xpc"],"created_at":"2025-08-11T08:37:16.366Z","updated_at":"2026-05-30T22:00:49.686Z","avatar_url":"https://github.com/appium.png","language":"TypeScript","funding_links":["https://opencollective.com/appium"],"categories":[],"sub_categories":[],"readme":"# appium-ios-remotexpc\n\nA Node.js library for interacting with iOS devices\nthrough Appium using remote XPC services.\nThis library enables communication with iOS devices\nthrough various services like system logs and network tunneling.\n\n## Overview\n\nThis library provides functionality for:\n\n- Remote XPC (Cross Process Communication) with iOS devices\n- Lockdown communication\n- Device multiplexing via **usbmuxd** (lists USB **and** WiFi-attached devices; see below)\n- Property list (plist) handling\n- IPv6 tunneling services to iOS devices using TUN/TAP interfaces\n- System log access\n\n## Installation\n\n```bash\nnpm install appium-ios-remotexpc\n```\n\n## Requirements\n\n- Node.js 16 or later\n- iOS device for testing\n- Proper device pairing and trust setup\n- Root/sudo privileges for tunnel creation (TUN/TAP interface requires elevated permissions)\n\n## Features\n\n- **Plist Handling**: Encode, decode, parse, and create property lists for iOS device communication.\n- **Device communication over usbmux / usbmuxd**: The system **usbmuxd** daemon exposes a single device list that includes machines plugged in over **USB** and, when pairing and wireless sync are set up, the same iPhone/iPad **over WiFi**. WiFi entries are marked **`ConnectionType: Network`** (USB entries use `ConnectionType: USB`). This library connects through usbmuxd the same way for both; the tunnel path is unchanged (lockdown → CoreDeviceProxy → TUN/TAP → Remote XPC).\n- **Remote XPC**: Establish Remote XPC connections with iOS devices.\n- **Service Architecture**: Connect to various iOS services:\n    - System Log Service: Access device logs\n    - Tunnel Service: Network tunneling to/from iOS devices\n    - Diagnostic Service: Device diagnostics\n    - AFC Service: File system operations on iOS devices\n- **Pair Record Management**: Read and write device pairing records.\n- **Packet Streaming**: Stream packets between host and device for service communication.\n\n## Configuration\n\n### Environment Variables\n\n#### APPIUM_IOS_REMOTEXPC_LOG_LEVEL\n\nControls the logging verbosity of the library.\n\n- **Default**: `info`\n- **Possible values**: Standard log levels supported by @appium/support logger\n  - `silly` - Most verbose, logs everything\n  - `verbose` - Very detailed logs\n  - `debug` - Detailed debugging information\n  - `info` - General informational messages (default)\n  - `warn` - Warning messages\n  - `error` - Error messages only\n- **Usage**:\n\n```bash\n# Set log level to debug for verbose output\nAPPIUM_IOS_REMOTEXPC_LOG_LEVEL=debug npm test\n\n# Set log level to error for minimal output\nAPPIUM_IOS_REMOTEXPC_LOG_LEVEL=error node your-script.js\n```\n\nThis is particularly useful for debugging issues or reducing log noise in production environments.\n\n## Architecture Flow\n\nThe following diagram illustrates the high-level flow of how the tunnel is created:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/images/ios-arch.png\" alt=\"iOS Architecture\" width=\"70%\"\u003e\n\u003c/div\u003e\n\n### Role of TUN/TAP\n\nThe `appium-ios-tuntap (previously tuntap-bridge)` module plays a crucial role in establishing network connectivity:\n\n1. **TLS Socket Input**: Receives the secure TLS socket connection from CoreDeviceProxy\n2. **Virtual Network Interface**: Creates a TUN/TAP virtual network interface on the host system\n3. **IPv6 Tunnel**: Establishes an IPv6 tunnel between the host and iOS device\n4. **Packet Routing**: Routes network packets between the virtual interface and the iOS device\n5. **Service Access**: Enables access to iOS shim services through the tunnel\n\n**Technical Details:**\n- **Platform Support**: Works on both macOS and Linux\n- **IPv6 Support**: Creates IPv6 tunnels for modern iOS communication\n- **Packet Handling**: Manages packet routing between virtual interface and device\n- **Automatic Cleanup**: Properly closes tunnels and cleans up interfaces\n\n**Security Considerations:**\n- Requires root/sudo access for TUN/TAP interface creation\n- Uses TLS for secure communication with iOS devices\n\n## Usage\n\n### Creating a Tunnel (Low-level approach)\n\n```typescript\nimport {\n  createLockdownServiceByUDID,\n  rsdSessionLockKey,\n  startCoreDeviceProxy,\n  TunnelManager,\n} from 'appium-ios-remotexpc';\n\n// Create lockdown service\nconst { lockdownService, device } = await createLockdownServiceByUDID(udid);\n\n// Start CoreDeviceProxy\nconst { socket } = await startCoreDeviceProxy(\n  lockdownService,\n  device.DeviceID,\n  device.Properties.SerialNumber,\n  { rejectUnauthorized: false }\n);\n\n// Create tunnel using tuntap\nconst tunnel = await TunnelManager.getTunnel(socket);\nconsole.log(`Tunnel created at ${tunnel.Address} with RSD port ${tunnel.RsdPort}`);\n\n// Discover RSD services (serialized per tunnel; closed before return)\nawait TunnelManager.runSerializedRsdSession(\n  rsdSessionLockKey(tunnel.Address, tunnel.RsdPort),\n  async () =\u003e {\n    const remoteXPC = await TunnelManager.connectRemoteXPCUnlocked(\n      tunnel.Address,\n      tunnel.RsdPort,\n    );\n    try {\n      console.log(remoteXPC.getServices());\n    } finally {\n      await remoteXPC.close();\n    }\n  },\n);\n```\n\n### iPhone / iPad over WiFi (usbmuxd “network” devices)\n\n**usbmuxd** (the multiplexer daemon, e.g. on macOS) does **not** only list USB devices: once a device is paired with the host and wireless sync / lockdown-over-WiFi is enabled, **the same daemon’s device list includes that device as attached over WiFi**. In plist responses from `ListDevices`, those rows carry **`ConnectionType: Network`** (and a distinct `DeviceID` from any USB listing for the same physical device).\n\nThere is no separate “WiFi API” in this library: call `createUsbmux()` → `listDevices()` (or any other client that queries **usbmuxd**) and use the returned **`DeviceID`** and UDID with `createLockdownServiceByUDID` and the tunnel steps in the previous section—identical to USB.\n\n**Typical host-side setup:**\n\n1. Pair the device with this Mac and tap **Trust** on the device if prompted.\n2. Allow the device to connect over WiFi (e.g. in Finder under the device, enable **Show this [device] when on WiFi**, or use Xcode **Devices and Simulators** with the equivalent option so lockdown can reach the device without USB).\n3. Confirm **usbmuxd** reports the device with **`ConnectionType: Network`**—for example by logging the result of `listDevices()` from this library, or by checking another usbmuxd client’s device list while the device is on the same network and not on USB.\n\nFor an end-to-end tunnel smoke test with the tunnel registry HTTP API, use `npm run tunnel-creation` or `npm run test:tunnel-creation` (see `scripts/test-tunnel-creation.ts`), usually with **sudo** for TUN/TAP.\n\n### Apple TV / tvOS over WiFi\n\nApple TV and tvOS devices over WiFi are supported. The following symbols are part of the public API and are intended for external use (e.g. by the Appium XCUITest driver):\n\n```typescript\nimport {\n  AppleTVPairingService,\n  UserInputService,\n  AppleTVTunnelService,\n} from 'appium-ios-remotexpc';\n\nconst userInput = new UserInputService();\nconst pairing = new AppleTVPairingService(userInput);\nconst result = await pairing.discoverAndPair('Living Room');\n```\n\nFor step-by-step pairing instructions, see the [Apple TV Pairing Instructions](docs/apple-tv-pairing-guide.md).\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/appium-ios-remotexpc.git\ncd appium-ios-remotexpc\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n### Continuous Integration\n\nThis project uses GitHub Actions for continuous integration and Dependabot for dependency management:\n\n- **Lint and Build**: Automatically runs linting and builds the project on Node.js LTS.\n- **Format Check**: Ensures code formatting adheres to project standards\n- **Test Validation**: Validates that test files compile correctly (actual tests require physical devices)\n- **Dependabot**: Automatically creates PRs for dependency updates weekly\n\nAll pull requests must pass these checks before merging. The workflows are defined in the `.github/workflows` directory.\n\n### Scripts\n\n- `npm run build` - Clean and build the project\n- `npm run lint` - Run ESLint\n- `npm run format` - Run prettier\n- `npm run lint:fix` - Run ESLint with auto-fix\n- `npm test` - Run tests (requires sudo privileges for tunneling)\n\nCLI helpers under `scripts/` are ESM (`.mjs`) and load the library via the package entrypoint. Run `npm run build` before using them so `appium-ios-remotexpc` resolves to `build/`.\n\n- `npm run tunnel-creation` / `npm run test:tunnel-creation` — Create USB tunnels and start the tunnel registry HTTP API (requires `sudo`)\n- `npm run test:tunnel-creation:lsof` — Same as above with `--keep-open` (for inspecting open sockets)\n- `npm run pair-appletv` — Pair an Apple TV over WiFi for Remote XPC (requires `sudo`)\n- `npm run start-appletv-tunnel` — Start an Apple TV WiFi tunnel and tunnel registry (requires `sudo`)\n\nPass `--help` after `--` to any of these npm scripts to see CLI flags (for example: `npm run pair-appletv -- --help`).\n\n## Project Structure\n\n- `/scripts` - Optional CLI helpers (ESM `.mjs`) for tunnels and Apple TV pairing; use via `npm run` entries under [Scripts](#scripts)\n- `/src` - Source code\n  - `/lib` - Core libraries\n    - `/lockdown` - Device lockdown protocol\n    - `/pair-record` - Pairing record handling\n    - `/plist` - Property list processing\n    - `/remote-xpc` - XPC connection handling\n    - `/tunnel` - Tunneling implementation with tuntap integration\n    - `/usbmux` - usbmuxd client (USB and WiFi-listed devices)\n  - `/services` - Service implementations\n    - `/ios`\n      - `/diagnostic-service` - Device diagnostics\n      - `/syslog-service` - System log access\n      - `/tunnel-service` - Network tunneling\n\n## Testing\n\n```bash\n# Run all tests\nnpm test\n```\n\nNote: Integration tests require:\n- Physical iOS devices connected (USB and/or **WiFi** if the device is paired and visible to usbmux as `Network`)\n- Sudo privileges for tunnel creation\n- Device trust established\n\n## License\n\nApache-2.0\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Notes\n\nThis project is under active development. APIs may change without notice.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fappium-ios-remotexpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappium%2Fappium-ios-remotexpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappium%2Fappium-ios-remotexpc/lists"}