Skip to main content
Glama

Grogu (grogu-ios)

Control unjailbroken iOS / iPadOS devices natively over Tailscale — direct CoreDevice/DVT telemetry, millisecond Decision API, FastWDA UI trees, Siri voice takeover, and MCP integration for LLMs.

License: MIT Python 3.11+

Grogu lets a Linux server (or any Tailscale peer) control an unjailbroken iPhone or iPad without keeping a Mac tethered — keeping banking, broker, and Apple Pay apps 100% untampered while giving LLMs and deterministic scripts full native UI hierarchy access and deep system telemetry.


Architecture

flowchart LR
    Siri["iOS / iPadOS Siri & Vocal Shortcuts"] -- "POST /api/siri/command (Tailscale)" --> GW["Grogu Gateway (:18830)"]
    Agent["LLM / MCP Client"] -- "stdio / HTTP (:18831)" --> MCP["grogu-mcp"]
    MCP --> DE["Decision API & FastWDA Client"]
    GW --> DE
    GW --> Core["GroguCoreManager"]
    Core -- "JSON RPC (:18833)" --> Worker["grogu-worker (UserspaceRsdTunnel)"]
    DE -- "HTTP (:18832 -> :8100)" --> Worker
    Worker <== "Tailscale TCP (:49152 / :62078)" ==> Device["iOS / iPadOS Device"]

Four Core Pillars

  1. No-Mac, No-Root Tailscale RSD Tunnel (grogu-worker)

    • Uses pymobiledevice3's pure-Python UserspaceRsdTunnel directly over Tailscale TCP (RemotePairing port 49152 or CoreDeviceTunnelProxy over 62078) — bypassing mDNS/Bonjour multicast limitations.

    • Clamps REQUESTED_MTU = 1280 for reliable WAN/Tailscale framing and auto-mounts the Personalized Developer Disk Image (auto_mount) when com.apple.dt.testmanagerd.remote is absent after a reboot (on high-RTT Tailscale links, sudo pymobiledevice3 remote tunneld + mounter auto-mount can pre-mount DDI in ~10s).

    • Multiplexes WDA port forwarding (127.0.0.1:18832 -> device:8100), a shared DVT telemetry RPC socket (127.0.0.1:18833), and an XCUITestService supervisor on a single RSD tunnel.

  2. Dual-Speed UI Control (FastWDAClient + DecisionEngine) — Works Even Without WDA

    • Zero-WDA Native Fallback: Before or without WebDriverAgent running, ios_ui_dump (GET /api/ui/dump) automatically falls back to DVT AccessibilityAudit, launch / open_url fall back to DvtProvider ProcessControl (dvt_launch), and screenshots use DVT Screenshot — zero sideloading required for inspection, deep-link app launching, and voice reading.

    • Full Gesture Mode (FastWDA): Compacts the XCUITest accessibility hierarchy (type, label, name, value, rect, center) with waitForIdleTimeout=0 and waitForQuiescence=false.

    • Decision API (ios_decision_run / POST /api/decision/execute): Executes deterministic steps (launch, open_url, tap, tap_selector, wait_selector, swipe, type, button, sleep, reflex) with per-step millisecond telemetry.

    • Custom On-Device Patch (wda_patch/): Optional Objective-C FBGroguCommands extension adding /grogu/fast_tree and /grogu/reflex for sub-30ms on-device polling and tap synthesis.

  3. Deep System Telemetry (ios_lowlevel_telemetry / GET /api/telemetry/{kind})

    • summary: Device identity, Developer Mode status, battery, running apps.

    • processes: Live Sysmontap CPU & memory footprint (MB) per PID.

    • ioregistry: Battery capacity, voltage, amperage, adapter watts, temperature, Wi-Fi state.

    • schemes: Installed apps and every registered CFBundleURLTypes URL Scheme for instant deep-link jumps.

    • oslog: Live unified system logs (ActivityTraceTap).

    • network: Uses PcapdService over USB or automatically switches to DVT DeviceInfo.network_information() + NetworkStatistics over wireless Tailscale RSD.

    • accessibility, dvt_launch, dvt_kill, screenshot.

  4. Non-Blocking Siri & Vocal Shortcuts Takeover (ios_siri/)

    • POST /api/siri/command answers status & screen-read queries synchronously ("speak"), while action commands return an immediate TTS acknowledgment and wait 450ms before injecting UI actions so the Siri overlay dismisses first.

    • Supports both a 60-second Apple Shortcuts + iOS/iPadOS 18+ Vocal Shortcuts setup and native Swift AppIntents (GroguSiriIntents.swift).


Related MCP server: iphone-mirror-mcp

Quick Start

1. Install on your Linux Tailscale Host

git clone https://github.com/Overbaker/grogu.git
cd grogu
python3 -m venv .venv
.venv/bin/pip install -e ".[worker]"
cp .env.example .env
# Edit .env with your device's Tailscale IP (GROGU_DEVICE_IP) and host Tailscale IP (GROGU_BIND_HOST)

Start the gateway (on your Tailscale interface):

GROGU_DEVICE_IP=100.64.0.10 GROGU_BIND_HOST=100.64.0.1 grogu-gateway

2. One-Time USB Pairing Bootstrap (on Mac)

Plug your iPhone/iPad into a Mac on the same Tailscale network, unlock it, and run:

curl -fsSL http://<YOUR_GATEWAY_TAILSCALE_IP>:18830/bootstrap/mac.sh | bash

This installs your host's SSH public key, pairs lockdown + RemotePairing over USB, enables Wi-Fi connections, and uploads <udid>.plist + remote_<udid>.plist to ~/.pymobiledevice3/ on your Linux host.

3. Enable Developer Mode & Prepare Sideloader-Compatible WDA (Optional for Touch Injection)

Note: DVT telemetry, wireless NetworkStatistics, AccessibilityAudit UI trees, app launches, screenshots, and Siri voice queries already work without WDA. Install WebDriverAgent when you also want synthesized touch taps/swipes/typing.

  1. On the iPhone/iPad: Settings → Privacy & Security → Developer Mode → ON (reboot & confirm).

  2. Sideloaders using apple-codesign (Impactor, AltStore, SideStore, plumesign) skip signing PlugIns/*.xctest bundles (causing mapped file has no cdhash). Repackage the upstream release into Frameworks/WebDriverAgentRunner.framework first:

grogu-prepare-wda-ipa --download -o ~/.config/grogu/WebDriverAgentRunner-sideload.ipa

The gateway also serves this file over Tailscale at GET /bootstrap/wda-sideload.ipa. 3. Sign & install ~/.config/grogu/WebDriverAgentRunner-sideload.ipa via Impactor, plumesign --apple-id --register-and-install, or Xcode, and trust your developer certificate under Settings → General → VPN & Device Management. 4. Unplug the USB cable and start the persistent tunnel & WDA supervisor (supports both PlugIns/*.xctest and Frameworks/*.framework):

GROGU_DEVICE_IP=100.64.0.10 grogu-worker daemon

4. Register as an MCP Server

Add to your MCP client configuration (e.g. mcp_config.json):

{
  "mcpServers": {
    "grogu-ios": {
      "command": "/path/to/grogu/.venv/bin/grogu-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "GROGU_DEVICE_IP": "100.64.0.10",
        "GROGU_BIND_HOST": "100.64.0.1"
      }
    }
  }
}

License

MIT © 2026 Overbaker

Available Tools

12 tools
ios_decision_runB

Execute a deterministic Decision API JSON step list (launch, open_url, tap, tap_selector, wait_selector, swipe, type, button, sleep, reflex).

Inputs: steps_json (required). Returns: object

ios_input_textB

Type text into the currently focused field.

Inputs: text (required). Returns: object

ios_keyB

Press hardware button: HOME, VOLUME_UP, or VOLUME_DOWN.

Inputs: key_name (required). Returns: object

ios_launch_appB

Launch an app by alias, Bundle ID, or URL Scheme DeepLink.

Inputs: app_target (required). Returns: object

ios_lowlevel_telemetryC

Read low-level iOS/iPadOS telemetry over Tailscale DVT/Lockdownd. Supported kind: summary, processes, ioregistry, schemes, oslog, network, accessibility, dvt_launch, dvt_kill.

Inputs: kind (required), filter_text. Returns: object

ios_screenshotB

Capture screen PNG (via WDA if running, else DVT Screenshot).

Inputs: filename. Returns: object

ios_siri_tasksC

Read recent Siri voice commands & execution traces received by the gateway.

Inputs: limit. Returns: object

ios_statusA

Query device status: Tailscale ports (62078/49152/8100), pairing keys, WDA readiness, and foreground app.

Inputs: no named parameters. Returns: object

ios_swipeC

Swipe from (x1, y1) to (x2, y2) with duration in milliseconds.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +1 more. Returns: object

ios_tapC

Tap at screen point coordinates (x, y).

Inputs: x (required), y (required). Returns: object

ios_tap_elementC

Find a visible UI element by label/name/value and tap its center immediately.

Inputs: text (required), exact. Returns: object

ios_ui_dumpC

Dump current UI accessibility hierarchy cleanly in milliseconds.

Inputs: compact. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 12 tools

    Disambiguation4/5

    Each tool maps to a distinct action on the iOS device, with a clear prefix and scope. The only real overlap is ios_tap vs ios_tap_element (coordinate vs element lookup) and ios_status vs ios_lowlevel_telemetry (both report device diagnostics), but descriptions make the boundaries reasonably clear. ios_decision_run intentionally aggregates primitives, which is fine as an orchestrator.

    Naming Consistency4/5

    All 12 tools share the ios_ prefix and snake_case, which is highly predictable. However, the ordering is mixed—verb-first (ios_tap, ios_launch_app, ios_input_text) versus noun-first (ios_status, ios_ui_dump, ios_lowlevel_telemetry, ios_siri_tasks)—so it's not a strict verb_noun pattern throughout.

    Tool Count5/5

    Twelve tools is well within the sweet spot for an iOS automation server. Every tool earns its place: primitives (tap, swipe, text, key), observation (ui_dump, screenshot, status), and higher-level orchestration (decision_run, launch_app, telemetry).

    Completeness4/5

    Coverage is strong: observation, low-level input, app launch, batch orchestration, and telemetry are all present. Minor gaps remain—no standalone app terminate/close (only dvt_kill buried in telemetry), no long-press or element-relative swipe, and no query for installed apps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to discover and interact with iOS apps through a local MCP gateway, converting remote Streamable HTTP MCP endpoints into stdio tools. Provides dynamic device discovery, tool schema introspection, and deterministic tool calling for app analysis.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate a real iPhone from a Mac by reading the screen over USB and sending taps, swipes, typing, and app launches over Bluetooth, with every action returning a fresh screenshot so the agent can verify its work. Runs as a local MCP server, so agents can test iOS apps on physical devices and automate everyday phone tasks.
      38 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that lets AI agents see and operate real iPhones, iPads, and Android devices from a Mac — screenshots, on-device OCR, taps, swipes, typing, app launching, and replayable skills over USB, Wi-Fi, or adb, with nothing installed on the phone. It gates anything that sends, posts, buys, or deletes behind human approval dialogs and private credential entry, backed by a kill switch, policy file, audit log, and a live-view web console.
      1
      GPL 3.0