REMOTE DEBUG IOS APP ON DEVICE
The app dials out to a hosted relay. No cable, no shared Wi-Fi, no Xcode on the machine you debug from — and your AI agent gets exactly the same access you do.
Wireless debugging in Xcode pairs a device to one Mac on the same network: a full debugger, but you have to be next to it. A proxy like Charles or Proxyman shows HTTP traffic and nothing else. Appium and WebDriverAgent drive the UI from a Mac host on that same network, and see the app from the outside. Safari Web Inspector reaches web views only. AppTelepath takes a different route: an SDK inside your debug build opens an outbound WebSocket to a hosted relay, so the app's runtime is reachable from any network.
An SDK in the build, and iOS only. The SDK ships in Debug, Staging, Ad Hoc and CI configurations; it detects the distribution channel and refuses to start in an App Store build. Android is on the roadmap and not delivered — nothing on this page works on Android yet. Everything else on this page is available today, in the free beta.
The device is the one that connects. That single decision is what removes the cable, the shared network and the Mac.
# iPhone · Debug / Staging build Telepath SDK │ │ outbound wss ▼ wss://apptelepath.com/ws ← hosted relay ▲ │ https │ apptelepath.com/app (you) · apptelepath.com/mcp (your agent)
The relay routes messages; device traffic is not stored unless you explicitly record a session. Workspaces are isolated by credential: a device credential can join as a device and do nothing else.
Searches for remote iOS debugging often land on Safari Web Inspector, which inspects the DOM inside a web view. This page is about the native runtime: view controllers, URLSession traffic, the sandbox, UserDefaults, SQLite, crashes and hangs.
Six steps, end to end. Steps 2 to 5 are the ones an AI agent can do for you — the console's guide hands it the whole task in one paste.
Sign in, then point a remote-MCP client at the hosted endpoint. Authorization happens once in the browser: you confirm the account, the client and the workspace.
codex mcp add apptelepath --url https://apptelepath.com/mcp \ --oauth-client-id https://apptelepath.com/oauth/clients/codex-cli.json codex mcp login apptelepath
Any remote-MCP-capable client uses the same URL: https://apptelepath.com/mcp. There is no npm package and no local stdio server. No MCP client? Skip this step — the HTTP API in step 6 does everything the MCP tools do.
One pod, restricted to the configurations you actually debug. Name the non-App-Store configurations of your project here — they are not always called Debug.
# Podfile
pod 'AppTelepath', '~> 3.0', :configurations => ['Debug', 'Staging']
pod install
React Native Fabric hosts use pod 'AppTelepath/ReactNative', '~> 3.0' so Pressable can be activated. The legacy pod name Telepath installs the same binary; pick one. Either way the import stays import Telepath.
Add the flag to every host target you listed above. Use it instead of DEBUG: TestFlight and Ad Hoc builds are Release-type configurations, and a #if DEBUG guard would silently keep the SDK out of exactly the builds you wanted to inspect.
// Build Settings · every host target you listed above
SWIFT_ACTIVE_COMPILATION_CONDITIONS = TELEPATH_ENABLED
Objective-C targets use GCC_PREPROCESSOR_DEFINITIONS = TELEPATH_ENABLED=1.
In application:didFinishLaunchingWithOptions:. No key in the source: the connection settings come from the build configuration.
// AppDelegate.swift #if TELEPATH_ENABLED import Telepath Telepath.start() // configure once; works in normal runs and in authorized test builds #endif
Only placeholders go into version control. The real values live in a gitignored local config or the secret store you already use — the agent writes them there for you after calling telepath_issue_device_token.
// Info.plist — committed placeholders only
TelepathAgentServerURL $(TELEPATH_AGENT_URL)
TelepathAgentWorkspaceKey $(TELEPATH_AGENT_KEY)
# CI or a temporary override
TELEPATH_AGENT_URL=wss://apptelepath.com/ws
TELEPATH_AGENT_KEY=<device-only credential>
For CI or a one-off run, inject them as environment variables instead. The credential is device-only: someone who extracts it from a build can impersonate a device, and cannot reach MCP, the HTTP API, the control plane or any other device. Never substitute an admin or ordinary workspace token, and never commit it. Working without an agent? Create a member workspace token in the console and use that as the key.
Launch the app on the device. It connects at launch and shows up in the workspace — in the console at apptelepath.com/app, and in your agent's device list.
# agent side
telepath_list_devices
telepath_screenshot
# any workspace member token curl -s -H "Authorization: Bearer $TELEPATH_TOKEN" \ https://apptelepath.com/api/devices curl -s -H "Authorization: Bearer $TELEPATH_TOKEN" \ https://apptelepath.com/api/screenshot -o shot.jpg
The HTTP calls take an ordinary member workspace token, not the device-only credential. Anything the MCP tools can do, POST /api/invoke can do too, so scripts and CI need no MCP client at all.
Prefer not to do this by hand? The console's integration guide copies the whole thing — pods, flag, launch entry, build settings, verification — as one task for your coding agent, which then reports back only once the device is actually online.
The same commands, on sample data: screenshot, hierarchy, tap, network, diagnose.
See a sessionEvery panel in the console and every agent tool is one command on the device. Same list for both.
A screenshot of the live app, and a hierarchy that defaults to a summary — interactive elements and visible text, each with a stable ref — instead of ten thousand nodes.
Act by ref instead of guessing coordinates. Each action reports what changed on screen, plus the error logs and failed requests from that moment — usually no confirming screenshot needed.
Captured requests with headers and bodies, paged for large payloads, exportable as HAR from the console. Replay a captured request through the app's own stack.
Recent lines with filters, or a live stream. The response says how many lines the on-device buffer dropped, so “no logs” and “logs lost” never look alike.
CPU, memory, FPS and thread count as a snapshot or a subscription — the same series the console charts.
Browse the sandbox, read files in chunks, read and edit defaults, run SQL against the app's databases. Write commands are gated by allowWrite.
Crash reports with stacks, main-thread hangs, thread bursts, off-main UI calls, and leaks only when a retain cycle is proven. Detectors report whether they were armed, so an empty list is never read as “no problem”.
One call answers “what just went wrong”: clustered error logs, failed requests, crashes and hangs from the last minute, ranked by severity, with a one-line headline.
Record logs, network, performance and crashes — plus periodic screenshots — into a timeline you can filter, replay and export. Reproduce once, hand it to anyone.
Location, routes and location failures; push payloads including silent and tapped ones; network degradation with latency, bandwidth, failure rate, hangs and URL targeting.
Register an app-specific command once and it joins the capability list every agent sees. There is also a raw invoke escape hatch for anything in the protocol.
When a stack can't be symbolicated on device, the response says so and returns the image UUIDs and load addresses needed to resolve it — rather than a nearby symbol that looks like an answer.
Each of these is good at something. The differences that matter are how far the connection reaches, and how deep it sees.
| Xcode wireless | Safari Web Inspector | Charles / Proxyman | Appium / WebDriverAgent | AppTelepath | |
|---|---|---|---|---|---|
| Across the internet | No — device and Mac on the same network | No — device paired to a nearby Mac | Only if you expose a proxy host the device can route to | No — the driver host sits on the same network | Yes — the app dials out to a hosted relay |
| USB cable | Needed to pair the device the first time | Needed for the initial trust and pairing | No — but the device must trust a proxy certificate | Needed to install and sign the driver app | Never |
| Xcode or a Mac to look | Required, on the same network | Required — macOS Safari | Not required; a proxy host is | A macOS host is required to run the driver | Only to build and install the app once. Debugging is a browser tab or an agent call |
| What it can see | Everything a debugger sees — breakpoints, memory, Instruments | Web view internals only: DOM, JS console, storage | HTTP(S) traffic only | The UI from the outside, plus device logs | The app's runtime: screen, UI tree, logs, network, sandbox, UserDefaults, SQLite, performance, crashes and hangs |
| Driving the app | No — you pause it, you don't tap it | JavaScript inside the web view | No — traffic can be rewritten, the UI can't be touched | Yes — this is what it exists for | Yes — tap, type and swipe by stable element reference |
| Callable by an AI agent | No | No | No | Through an Appium or mobile-mcp server you host | Yes — hosted MCP, plus HTTP and SSE for everything else |
| What it asks of you | Nothing added to the app | Nothing added to the app | A trusted proxy certificate on the device | A signed driver app running alongside yours | An SDK in non-App-Store builds — and iOS only for now |
No. The app opens an outbound WebSocket to wss://apptelepath.com/ws, and both the web console and the MCP endpoint reach it through that relay. A phone on cellular in another country behaves exactly like one on the desk beside you.
You need Xcode once, to build and install a version of the app that contains the SDK. Debugging after that happens in a browser or through your agent, so the machine you debug from needs neither Xcode nor macOS.
No. The SDK checks the distribution channel at runtime and refuses to start in an App Store build. TestFlight also refuses unless you opt in explicitly and accept that an embedded credential can be extracted from a build. Keep it in Debug, Staging, Ad Hoc and CI configurations.
Yes. A simulator connects the same way a real device does and reports itself as a simulator, so an agent can tell the two apart. Everything on this page other than real-hardware conditions behaves identically.
The hosted service and the iOS SDK are in free beta with no expiry date for now, running on Trial quotas: 2 devices online, 1 GB of traffic per month, 1 seat, 14 days of retention. Billing isn't switched on yet, so paid pricing isn't published.
iOS is the only platform delivered today. There is an iOS host adapter for React Native Fabric so taps reach Pressable, but not a full React Native JS probe. Android is planned, not shipped.
What the platform is, and a live session you can page through.
The hosted MCP endpoint, its tools and how clients authorize.
What changes when the agent can see the running app itself.
Free beta quotas today, and the plans that follow.
Free beta, no credit card. Connect the MCP endpoint, let the agent do the integration, and watch the device come online.
Start free