iCTRL

AI-friendly iOS automation service, built on XCUITest.

[!WARNING] For automated testing and research only. iCTRL hands full control of a phone (taps, text input, screen contents, every installed app) to whoever holds a paired key. Any automation like this can be hijacked or misused: a leaked key, a client you shouldn't have approved, or an agent acting on instructions it picked up along the way. Weigh the risks before you use it:

• Run it only on devices you own and accounts you are entitled to automate.
• Approve only the pairing requests you started.
• Leave remote access off unless you need it, and stop the server when you are done.
• Don't leave an agent unsupervised around payments, messages or anything that can't be undone.

You are responsible for how you use it, including compliance with the terms of the apps you automate.

iCTRL turns an iPhone into a controllable automation endpoint. It runs a long-lived XCUITest runner that exposes a JSON-RPC 2.0 API over HTTP (default port 8200), so an AI agent — or any HTTP client — can drive the device: tap, swipe, type, read the UI tree, take screenshots, launch apps, open URLs, and more.

Unlike a raw XCUITest script, iCTRL is designed to be discovered and driven by a model: GET /skill serves a complete operating manual and GET /schema documents every method with its parameters, so an agent can learn the API at runtime and call it correctly without prior knowledge.

Works with any agent. The JSON-RPC API and the skill are built in and progressively discoverable: an agent starts from the manual and drills into the schema only as it needs to. Any agent that can make HTTP requests can use it, such as OpenClaw, Hermes, Minis, Claude Code or Codex. All it needs is the phone's IP address and port; these agents usually explore the endpoint and install the skill themselves to learn how to drive the phone. Minis is additionally optimized for iCTRL, so it carries out interactions on the phone faster.

Hand it to your agent in one sentence. Once the runner is up (with remote access enabled, if the agent isn't on the phone), tell your agent:

"My iPhone is running iCTRL at 192.168.1.20:8200 — figure out how to drive it."

It finds the manual at GET /skill and the method list at GET /schema, downloads a client from the device, and asks to pair. Approve the pairing notification on the phone, and from there it works out the rest.

flowchart LR
  subgraph setup["Set up once"]
    direction TB
    S1["① Sign and install<br/>SideStore · sign-ipa.sh · Xcode"]
    S2["② Mount the DDI<br/>iCTRL app · StikDebug · Xcode"]
    S3["③ Launch the runner<br/>allow Notifications and Local Network"]
    S1 --> S2 --> S3
  end

  subgraph phone["iPhone"]
    direction TB
    R["iCTRL runner :8200<br/>127.0.0.1 only by default"]
    N["🔔 Runner notifications<br/>✅ Allow pairing · 🌐 Remote Access · 📡 Nearby · 🛑 Stop"]
    N -. "🌐 Remote Access opens it to the LAN" .-> R
  end

  A["🤖 Agent<br/>OpenClaw · Hermes · Minis · Claude Code · Codex<br/>given only IP:port"]

  S3 --> R
  A -- "1 · GET /skill, /schema: learn the API" --> R
  A -- "2 · POST /pair: X25519 key exchange" --> R
  R -- "pairing request" --> N
  A == "3 · encrypted JSON-RPC: tap, swipe, type, read UI, screenshot" ==> R

An agent on the phone itself, such as Minis, reaches the runner on 127.0.0.1. An agent on another machine needs 🌐 Remote Access turned on and the same Wi-Fi network.

• Bundle ID: com.openminis.ictrl
• Transport: JSON-RPC 2.0 over HTTP, port 8200
• Auth: encrypted envelope (X25519 pairing → HMAC-SHA256 sealed requests)
• Shipped as two IPAs: iCTRLUITests-Runner.ipa (the automation engine — required, and the one that must be running) + iCTRL.ipa (the companion app — optional, see The iCTRL app)
• Needs: a way to sign the IPA (free Apple ID via SideStore, or a paid account) and the Developer Disk Image mounted — see Installation

The iCTRL app (optional)

The runner does all the automation and runs on its own. iCTRL.ipa is a companion app for doing the surrounding chores on the phone itself:

• Mount the Developer Disk Image without a Mac, and re-mount it after a reboot in one tap (Option 3). Pairing files can be picked in the app or shared to iCTRL from Files, Mail, AirDrop or a chat.
• Start and stop the runner, and see whether it is running and which version.
• Visibility: see and switch who can reach the runner — 🟢 this device only, 🟡 LAN, or 🟡 LAN + nearby (AWDL).
• Authorized clients: every computer, agent and browser holding a key, where each last connected from (this device / USB, LAN, nearby, VPN), and revoking any of them.
• Runner logs, live, with pause, refresh and filter.

The app pairs with the runner once like any client (one Allow in the runner's notification). You can skip it if you mount the DDI with Xcode or StikDebug and manage the runner from its notification or a computer — with a free Apple ID's three-app limit, installing StikDebug or the iCTRL app is enough.

Features

Built for AI agents

• Self-describing. The device serves its own operating manual (GET /skill, under 15K characters, most important rules first) and a full method schema (GET /schema). An agent given only the address learns the rest by itself.
• Responses that steer. Every result carries a hint, and every error says what to do next. A ref re-resolves the live element at tap time; visibility and alternatives flag look-alikes; scrolls report whether they moved and where you are in the list.
• Knows the apps on the phone. resolve_app turns an app name into a bundle id offline and remembers which apps actually opened on this device, even where iOS refuses to list installed apps.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗