Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.
/iphonetest operator guide — live tunnel drive
Authoritative reference for a Claude session driving a real iPhone on AWS Device Farm
through /iphonetest --mode tunnel. Pre-empts every billing-leak, every silent-hang,
and every Appium-extension surprise that has been observed live.
- Upstream slash-command:
your-org/my-project→.claude/commands/iphonetest.md(file) - Driver script:
my-project/scripts/devicefarm/iphonetest.py→ hands off totunnel.pyfor--mode tunnel. This guide documents the JSON-RPC surface oftunnel.pyas it exists today, verified againsttunnel.py @ 22cf0cac(my-project PR #6174, merged 2026-05-29). When the surface drifts, update this file and re-pin the SHA. - Device Farm API surface:
CreateRemoteAccessSession. - Appium driver:
appium-xcuitest-driver— execute-methods reference. Latest upstream release at time of writing is v11.7.4 (2026-05-28); the driver bundled in AWS Device Farm's managed Appium server lags upstream (see the "What works vs. what's broken" matrix below).
1. What /iphonetest does
/iphonetest is the single entrypoint for driving a real iPhone on AWS Device
Farm from a Claude session. It auto-resolves the latest My-Project staging (or
production) IPA, uploads it to Device Farm, then — depending on --mode —
either runs an autonomous Appium + Claude agentic loop (walkthrough /
explore) or holds open one remote-access session + one Appium WebDriver
connection that an operating agent drives turn-by-turn (tunnel). All modes
auto-stop the session on exit so a crashed run cannot leak billing minutes.
Source-of-truth: my-project/.claude/commands/iphonetest.md.
2. Modes
--mode |
Shape | When to use |
|---|---|---|
tunnel (default since PR #6172) |
Interactive REPL or JSON-RPC over stdio; one session held open across many commands | An operating Claude driving the device turn-by-turn |
walkthrough |
Autonomous loop with the built-in My-Project-QA goal (visit every tab, screenshot each) | Smoke a fresh build |
explore |
Autonomous loop with operator-supplied --goal |
Single user-observable outcome, hands-off |
PR #6172 (merged 2026-05-29 17:48 UTC) flipped the default from
walkthroughtotunnel. Prior to that, you had to type--mode tunnelexplicitly. Today, bare/iphonetestlands you in interactive tunnel mode.
tunnel is the canonical mode for an operating Claude. Walkthrough/Explore
are for fire-and-forget runs where no human or agent is steering. The rest of
this guide is about tunnel.
2a. Interaction mode on the AWS side
tunnel.py always opens a Device Farm remote-access session with
interactionMode="NO_VIDEO". The AWS API exposes three values —
INTERACTIVE | NO_VIDEO | VIDEO_ONLY — but only NO_VIDEO returns a
usable remoteDriverEndpoint (HTTPS managed Appium server) suitable for an
Appium WebDriver client. INTERACTIVE mode exposes only interactiveEndpoint,
which is a WSS video stream meant for a human's browser and is incompatible
with the urllib3-based Appium Python client
(URLSchemeUnknown('wss')). The interactionMode parameter is marked
deprecated in the AWS API reference — NO_VIDEO continues to work and is the
only mode tunnel.py will ever request.
Source quote from
CreateRemoteAccessSession:
This parameter has been deprecated. The interaction mode of the remote access session. … Valid Values:
INTERACTIVE | NO_VIDEO | VIDEO_ONLY.
And the verbatim selection logic from tunnel.py:Tunnel.start:
# Device Farm exposes two endpoints when interactionMode=NO_VIDEO:
# endpoints.remoteDriverEndpoint -> HTTPS managed Appium server
# endpoints.interactiveEndpoint -> WSS video stream (browser-only)
# The top-level `endpoint` field is the WSS stream and is
# incompatible with the urllib3-based Appium Python client
# (URLSchemeUnknown('wss')).
endpoints = info.get("endpoints") or {}
self.endpoint = (
endpoints.get("remoteDriverEndpoint")
or info.get("endpoint")
or info.get("hostAddress")
or ""
)
3. Pre-flight checklist
Run these in order before invoking the command. Abort if any fails.
# 1. AWS Device Farm project visible (us-west-2 only)
aws devicefarm list-projects --region us-west-2 \
--query 'projects[].name' --output text
# → expect: My-Project-iOS-E2E
# 2. Doppler secrets present
doppler secrets --project my-project --config dev_local --only-names \
| grep -E "EAS_ACCESS_TOKEN|EXPO_TOKEN|DEVICEFARM_PROJECT_ARN|BEDROCK_AWS"
# 3. Python deps
pip show boto3 Appium-Python-Client anthropic | grep -E "^Name|^Version"
# missing? → pip install -r scripts/devicefarm/requirements.txt
# 4. No orphan sessions currently billing
python3 scripts/devicefarm/list-sessions.py
# any RUNNING / SCHEDULING listed? → stop them BEFORE you start another:
python3 scripts/devicefarm/stop-session.py --all-active
4. JSON-RPC command catalogue
tunnel.py --json reads one JSON object per stdin line and writes one JSON
response per stdout line. The full handlers dict from tunnel.py:jsonrpc
(quoted verbatim from my-project@22cf0cac5d9b88d066b4badd94b59d480be5285e):
handlers: dict[str, Any] = {
"start": lambda m: t.start(
app_arn=m.get("app_arn"), device_arn=m.get("device_arn")
),
"screenshot": lambda m: t.screenshot(m.get("path")),
"tap": lambda m: t.tap(float(m["x"]), float(m["y"])),
"tap_text": lambda m: t.tap_text(m["text"]),
"swipe": _swipe,
"type": lambda m: t.type_text(m["text"], submit=bool(m.get("submit", False))),
"press": lambda m: t.press(m["button"]),
"launch_app": lambda m: t.launch_app(m.get("bundle_id")),
"wait": lambda m: time.sleep(float(m["seconds"])),
"status": lambda m: t.status(),
"stop": _stop,
}
quit / exit are handled separately and trigger the cleanup callback before
acknowledging.
Every command below returns {"ok": true, ...} on success or
{"ok": false, "error": "..."} on failure. Field reads are by name (not
position) so wire order can never swap tap's x/y or turn --submit into
typed text.
start
Reserve a device. Auto-runs at script startup unless --no-autostart is
passed. Call explicitly only after a manual stop. With /iphonetest --mode tunnel, the IPA ARN is already injected by the orchestrator — you usually do
not call start yourself.
{
"cmd": "start",
"app_arn": "arn:aws:devicefarm:us-west-2:...:upload/...",
"device_arn": "arn:aws:devicefarm:us-west-2::device/..."
}
Response:
{
"ok": true,
"session_arn": "arn:aws:devicefarm:...",
"device": "Apple iPhone 17 Pro",
"endpoint": "https://...",
"width": 402,
"height": 874,
"artifacts": "artifacts/devicefarm-tunnel/20260529-180000-abcd1234"
}
session_arn and the screen dimensions are what you reference for the rest of
the run.
screenshot
Capture a PNG. Default path is artifacts/devicefarm-tunnel/<sess>/NNNN.png
(auto-incremented index). Use an explicit path when you want a stable
filename you'll Read next turn.
{ "cmd": "screenshot", "path": "artifacts/iphonetest/run/step-01.png" }
Response: {"ok":true,"path":"...","width":402,"height":874}.
tap
Tap at point coordinates. Coordinates are in points (matches width /
height from start / screenshot), not pixels.
{ "cmd": "tap", "x": 201, "y": 612 }
tap_text
Find an element by accessibility label / name / value and tap its center.
Tries exact predicate match first, then CONTAINS.
{ "cmd": "tap_text", "text": "Continue with Apple" }
Response includes the matched predicate and rect:
{
"ok": true,
"matched": "label == \"Continue with Apple\" OR name == \"Continue with Apple\" OR value == \"Continue with Apple\"",
"rect": { "x": 40, "y": 596, "width": 322, "height": 56 }
}
Quoted verbatim from tunnel.py:Tunnel.tap_text:
predicates = [
f'label == "{escaped}" OR name == "{escaped}" OR value == "{escaped}"',
f'label CONTAINS "{escaped}" OR name CONTAINS "{escaped}" OR value CONTAINS "{escaped}"',
]
Fails with No element matched text '...' if neither predicate hits. See
gotcha §6.2 for the iOS-system-UI workaround.
swipe
Two forms — direction (convenience) and coordinate (precise).
Direction form (60% screen-distance swipe from center):
{ "cmd": "swipe", "direction": "up", "duration_ms": 400 }
direction ∈ {up,down,left,right}.
Coordinate form (raw drag):
{
"cmd": "swipe",
"x1": 201,
"y1": 700,
"x2": 201,
"y2": 200,
"duration_ms": 600
}
Both compile down to mobile: dragFromToForDuration on the driver.
type
Send keys to whichever field is focused. submit: true appends a newline
(send-keys "\n" on the focused element) after the text lands.
{ "cmd": "type", "text": "hello Anna", "submit": false }
Since my-project@22cf0cac5d9b88d066b4badd94b59d480be5285e, type_text cascades
through the same four strategies explore.py:execute_action uses, in this
order (verbatim from tunnel.py:Tunnel.type_text):
- Focused element (
AppiumBy.IOS_PREDICATE, "hasKeyboardFocus == 1") →set_value(text) - Same focused element →
send_keys(text) - First-visible TextField or SecureTextField (predicate
(type == 'XCUIElementTypeTextField' OR type == 'XCUIElementTypeSecureTextField') AND visible == 1, sorted top-left first) → tap, thenset_value, falling back tosend_keysonset_valuefailure mobile: keys(last resort — usually fails on Device Farm; kept for local Appium / simulator hosts)
The first three strategies are why type now works on app-rendered My-Project
UI without first having to focus the field manually — see the matrix in §5
and gotcha §6.1 for what's still broken (iOS Springboard / Spotlight system
search fields).
press
Hardware-button press. Valid values:
home | lock | volumeup | volumedown.
{ "cmd": "press", "button": "home" }
launch_app
Launch (or bring to foreground) an app by bundle id. Device Farm does NOT
auto-launch the freshly-installed IPA after start — the device lands on
Springboard. This command is the canonical recovery; call it once right
after start. Added in my-project PR #6174
(merged 2026-05-29, SHA 22cf0cac5d9b88d066b4badd94b59d480be5285e).
Explicit bundle id form:
{ "cmd": "launch_app", "bundle_id": "com.staging.my-project" }
Auto-resolve form (bundle_id omitted — tunnel.py reads the IPA's
package_name field out of the upload metadata Device Farm holds against
the app_arn cached at start time, via
df.get_upload(arn=app_arn)["upload"]["metadata"]["package_name"]):
{ "cmd": "launch_app" }
Response on success:
{ "ok": true, "bundle_id": "com.staging.my-project", "method": "activateApp" }
method is activateApp when mobile: activateApp succeeds, or launchApp
when tunnel.py falls back to the older mobile: launchApp (kept for older
Appium driver builds). Quoted verbatim from tunnel.py:Tunnel.launch_app:
try:
self.driver.execute_script("mobile: activateApp", {"bundleId": bundle})
return {"ok": True, "bundle_id": bundle, "method": "activateApp"}
except Exception as exc_activate:
try:
self.driver.execute_script("mobile: launchApp", {"bundleId": bundle})
return {"ok": True, "bundle_id": bundle, "method": "launchApp"}
except Exception as exc_launch:
return {
"ok": False,
"error": f"activateApp: {exc_activate!r} | launchApp: {exc_launch!r}",
}
Error paths:
- Called before
start(no Appium driver yet):{"ok": false, "error": "session not started"}. - No
bundle_idand no cachedapp_arn:{"ok": false, "error": "no bundle_id provided and no app_arn cached on the session"}. - IPA upload metadata is missing or has no
package_name:{"ok": false, "error": "upload metadata has no \package_name`; pass bundle_id explicitly"}` (or a sibling error covering "no metadata" / "metadata is not valid JSON"). - Both
mobile: activateAppandmobile: launchAppthrow:{"ok": false, "error": "activateApp: <repr> | launchApp: <repr>"}.
wait
Sleep without sending anything to the device. Use this to let an animation or network call settle before the next screenshot.
{ "cmd": "wait", "seconds": 2 }
status
Report session liveness, device name, elapsed seconds, and screen size.
{ "cmd": "status" }
Response when running: {"ok":true,"running":true,"session_arn":"...","device":"Apple iPhone 17 Pro","elapsed_sec":143,"width":402,"height":874,"artifacts":"artifacts/devicefarm-tunnel/..."}.
stop
Stop the Device Farm session without exiting the tunnel process. You can
call start again after this. If stop_remote_access_session raises, the
ARN is not cleared and the response is {"ok": false, "error": "..."} —
the session may still be billing. Retry with
python3 scripts/devicefarm/stop-session.py --arn <arn>.
{ "cmd": "stop" }
quit / exit
Stop the session AND exit the process. Runs cleanup BEFORE acknowledging so the client sees the actual outcome — a successful response means the device is no longer billing.
{ "cmd": "quit" }
Response on clean stop: {"ok":true,"quit":true}. On stop failure:
{"ok":false,"quit":true,"error":"stop_remote_access_session failed; session may still be billing — run scripts/devicefarm/stop-session.py --all-active"}
(process exits with code 2).
5. What works vs. what's broken on Device Farm
Behavior observed live on iPhone 17 Pro / iOS 26.3.1 driving My-Project staging
(2026-05-29, against my-project@22cf0cac5d9b88d066b4badd94b59d480be5285e). The
Appium driver bundled in Device Farm's managed Appium server lags upstream
appium-xcuitest-driver v11.7.4
(reference),
which is why some mobile: extensions the docs list are not actually
exposed at the WDA endpoint.
cmd |
App-rendered My-Project UI | iOS system UI (Springboard / Spotlight) |
|---|---|---|
tap (coords) |
✓ | ✓ |
tap_text |
✓ (every interactive My-Project element ships an accessibility label per figma-design-system.md) |
✗ — Springboard / Spotlight system controls (Cancel, search field, App-Library labels) often have no label exposed to WDA's predicate matcher |
type |
✓ — the 4-strategy fallback (focused element → set_value/send_keys, then first-visible TextField/SecureTextField, then mobile: keys) lands on any field with hasKeyboardFocus == 1 OR any visible TextField, with no operator-side pre-focusing required |
✗ — iOS Springboard / Spotlight / App-Library search fields are not exposed in the active app's accessibility tree, so the predicate-based fallbacks find nothing and mobile: keys returns Unhandled endpoint: /wda/element/0/keyboardInput on DF |
swipe (both forms) |
✓ | ✓ |
press |
✓ | ✓ |
launch_app |
✓ — mobile: activateApp succeeds against the staging bundle id; mobile: launchApp fallback covers older driver builds |
n/a (operates on installed-app bundle ids, not system UI) |
screenshot / tap (coords) |
✓ | ✓ — always usable as the last-resort fallback |
6. Workarounds catalog
Each of these has been hit live; treat the workaround as the primary path when you recognise the symptom.
6.1 type returns Unhandled endpoint: /wda/element/0/keyboardInput (system UI only)
Symptom: {"cmd":"type","text":"my-project"} against the iOS Spotlight /
App-Library system search field comes back as
{"ok":false,"error":"Unhandled endpoint: /wda/element/0/keyboardInput"}.
Cause: Device Farm's bundled appium-xcuitest-driver does not expose
mobile: keys (the strategy-4 last resort tunnel.py:Tunnel.type_text
dispatches when nothing earlier matches). Even though upstream v11.7.4
documents mobile: keys, the managed Appium server on DF is older /
stripped. Springboard / Spotlight / App-Library search fields aren't exposed
in the active app's accessibility tree, so strategies 1–3 (focused element +
first-visible TextField) find nothing and the cascade tumbles into
strategy 4 — which fails.
App-rendered My-Project UI: type just works now. Since my-project@22cf0cac,
tunnel.py:Tunnel.type_text cascades through the same four strategies
explore.py:execute_action uses (focused-element set_value →
focused-element send_keys → first-visible TextField/SecureTextField with
tap + set_value/send_keys → mobile: keys). You do not need to
pre-focus the field with tap_text first — strategy 3 finds the topmost
visible TextField on its own. See §4 type for the verbatim cascade.
Workaround for iOS system text fields (Spotlight, App Library, Settings
search): type is still unusable here. Instead, tap each on-screen
keyboard letter individually by coordinate (read them off the screenshot),
or skip the system search entirely and reach the app via launch_app
(§6.3) — which is now the canonical recovery.
6.2 tap_text returns No element matched text 'Cancel'
Symptom: {"cmd":"tap_text","text":"Cancel"} (or any system-button label
in Springboard / Spotlight / Control Center) fails with
No element matched text 'Cancel'.
Cause: iOS Springboard and Spotlight UI elements often have no
accessibility label, name, or value exposed via WDA's
IOS_PREDICATE_STRING matcher. The two predicate fallbacks inside
tap_text both miss.
Workaround: screenshot, eyeball the coordinates, and use coordinate
tap:
./tx.sh '{"cmd":"screenshot","path":"01.png"}'
# Read 01.png, locate "Cancel" at e.g. (360, 60)
./tx.sh '{"cmd":"tap","x":360,"y":60}'
6.3 App is installed but not launched after start
Symptom: Right after tunnel.py reports {"ok":true,"event":"ready",...},
the screenshot shows the iOS home screen — not the My-Project app.
Cause: tunnel.py installs the IPA on session start (appArn is passed
to create_remote_access_session), but the Device Farm runtime does not
auto-launch it. The bundle is on the device — it's just sitting in App
Library → Recently Added.
Canonical fix (since my-project@22cf0cac): issue launch_app once. Either
form works:
# Explicit bundle id (recommended — no extra metadata round-trip)
./tx.sh '{"cmd":"launch_app","bundle_id":"com.staging.my-project"}'
# Auto-resolve from IPA upload metadata (tunnel.py reads `package_name`
# off the `app_arn` cached at `start` time)
./tx.sh '{"cmd":"launch_app"}'
Expect {"ok":true,"bundle_id":"com.staging.my-project","method":"activateApp"}.
On older Appium driver builds the response will be
...,"method":"launchApp" — same outcome, fallback path. See §4 launch_app
for the full error catalogue.
Fallback (if launch_app itself fails): swipe left to App Library, tap
"Recently Added" by coords, find the My-Project icon (one-liner pattern:
swipe left → swipe left → screenshot → tap "Recently Added" → screenshot → tap My-Project icon). Useful when activateApp and launchApp both throw
and you need a screenshot-driven recovery while you file the bug.
6.4 Picker auto-selection (iPhone 17 Pro / iOS 26.3.1)
Behavior: the device picker reads the IPA's metadata.supported_os +
metadata.form_factor via df.get_upload and rejects incompatible devices
before create_remote_access_session is called — so an
ArgumentException: invalid device or upload from AWS can never cost you
billing minutes. Highest-OS HIGHLY_AVAILABLE iPhone wins. For the current
My-Project staging IPA, that is iPhone 17 Pro on iOS 26.3.1.
Shipped in
PR #6171
(merged 2026-05-29 17:34 UTC). No operator action required — just don't pass
--device-arn unless you need a specific model.
6.5 Session is metered — kill-9 recovery
Cost: ~$0.17 per device-minute on metered iPhones. A 50-step walkthrough
runs $1–3. The autonomous loop auto-stops in finally and on SIGTERM;
tunnel.py:main._try_stop is what guarantees that, and a non-zero exit code
(2) is raised if stop_remote_access_session failed so CI can alert on
billing leaks.
A kill -9 bypasses all of that. If the tunnel process was force-killed
or the parent shell died, run the recovery one-liner immediately:
doppler run --project my-project --config dev_local -- \
python3 scripts/devicefarm/stop-session.py --all-active
This stops every RUNNING / SCHEDULING session in the project. Confirm with
python3 scripts/devicefarm/list-sessions.py.
6.6 NO_VIDEO is the only Appium-driveable interaction mode
INTERACTIVE returns a WSS endpoint that is for humans (browser-rendered
video stream) and is incompatible with the urllib3-based Appium Python
client. VIDEO_ONLY is not useful for automation either. tunnel.py
hardcodes interactionMode="NO_VIDEO" — do not try to override it. The
quoted-verbatim code is in §2a.
6.7 FIFO writers must stay open
Symptom: the first JSON command works; every subsequent command produces no output and the screenshot/tap hangs silently.
Cause: printf '{...}\n' > fifo opens, writes, and closes the FIFO.
The reader (tunnel.py) sees an EOF and the for raw in sys.stdin: loop in
jsonrpc() exits. The next write reopens the FIFO but tunnel.py has
already returned and nobody is reading.
Workaround: hold one writer open for the lifetime of the run, then append each command into the same FIFO:
# 1. Make the FIFO and a holder that never closes it
mkfifo tmp/tunnel/in
( exec 9>tmp/tunnel/in; sleep 86400 ) &
HOLDER_PID=$!
echo "$HOLDER_PID" > tmp/tunnel/holder_pid
# 2. Run tunnel.py reading from the FIFO, mirror output to a log
cat tmp/tunnel/in | python3 scripts/devicefarm/tunnel.py --json \
--app-arn "$APP_ARN" \
> tmp/tunnel/out.log 2>&1 &
echo $! > tmp/tunnel/pid
# 3. Send commands by appending to the FIFO from a second writer
printf '{"cmd":"screenshot","path":"01.png"}\n' > tmp/tunnel/in
The tx.sh helper in §7 wraps this pattern.
6.8 doppler run wrapper breaks stdin to subprocesses
Symptom: doppler run --project my-project --config dev_local -- bash -c '... python3 tunnel.py --json ...' either never receives the first JSON command or drops stdin midway.
Cause: doppler run's exec wrapper does not reliably forward stdin into a
nested bash -c "... python3 ..." invocation, especially when stdin is a
pipe / FIFO.
Workaround: materialize the secrets once, source them, and call
tunnel.py directly — no doppler wrapper in the hot path:
doppler secrets download \
--project my-project --config dev_local \
--no-file --format env > .env.iphonetest
set -a; source .env.iphonetest; set +a
# Now stdin works normally
python3 scripts/devicefarm/tunnel.py --json --app-arn "$APP_ARN"
Delete .env.iphonetest when you're done.
7. Suggested driving loop for a Claude operator
The pattern below is the one that actually works for a Claude session.
Everything lives under one tmpdir, the FIFO has a permanent holder, and
every command goes through a tiny tx.sh that reads the next line
written to out.log and surfaces it as the JSON response.
7.1 Bootstrap
TMP=$(mktemp -d -t tunnel.XXXXXX)
mkfifo "$TMP/in"
: > "$TMP/out.log"
# Hold the FIFO open so writers never EOF the reader
( exec 9>"$TMP/in"; sleep 86400 ) &
echo $! > "$TMP/holder_pid"
# tx.sh — send one JSON cmd, return the next response line
cat > "$TMP/tx.sh" <<'EOF'
#!/usr/bin/env bash
# Send one JSON cmd, return the next JSON response line from out.log.
# Usage: tx.sh '{"cmd":"screenshot","path":"x.png"}' [timeout_seconds]
set -euo pipefail
TMP="$(dirname "$0")"
CMD="${1:?usage: tx.sh JSON [timeout]}"
TIMEOUT="${2:-180}"
BEFORE=$(wc -l < "$TMP/out.log")
printf '%s\n' "$CMD" > "$TMP/in"
DEADLINE=$(( $(date +%s) + TIMEOUT ))
while [ "$(date +%s)" -lt "$DEADLINE" ]; do
CUR=$(wc -l < "$TMP/out.log")
if [ "$CUR" -gt "$BEFORE" ]; then
sed -n "$((BEFORE+1))p" "$TMP/out.log"
exit 0
fi
sleep 1
done
echo "{\"ok\":false,\"error\":\"tx.sh timeout after ${TIMEOUT}s\"}" >&2
exit 124
EOF
chmod +x "$TMP/tx.sh"
# Materialize secrets once — see gotcha §6.8
doppler secrets download \
--project my-project --config dev_local \
--no-file --format env > "$TMP/env"
set -a; source "$TMP/env"; set +a
# Launch the tunnel with /iphonetest (default mode = tunnel since PR #6172)
cat "$TMP/in" | \
python3 ~/Projects/my-project-workspace/my-project/scripts/devicefarm/iphonetest.py \
--mode tunnel --json \
> "$TMP/out.log" 2>&1 &
echo $! > "$TMP/pid"
When tunnel.py is ready it writes one JSON line like
{"ok":true,"event":"ready","session_arn":"...","device":"Apple iPhone 17 Pro","width":402,"height":874,"artifacts":"..."}.
Read out.log until you see "event":"ready" before sending the first
command.
7.2 Drive
TX="$TMP/tx.sh"
# 1. `start` already ran when /iphonetest launched the tunnel — device
# is reserved but sitting on Springboard.
# 2. Launch the app (canonical recovery, since my-project@22cf0cac).
# Bundle id is optional — tunnel.py resolves it from IPA metadata
# when omitted.
"$TX" '{"cmd":"launch_app","bundle_id":"com.staging.my-project"}'
# → expect {"ok":true,"bundle_id":"com.staging.my-project","method":"activateApp"}.
# 3. Take a baseline screenshot of the app's first screen
"$TX" '{"cmd":"wait","seconds":1}'
"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/01.png"}'
# 4. Sign in
"$TX" '{"cmd":"tap_text","text":"Continue with Apple"}'
"$TX" '{"cmd":"wait","seconds":3}'
"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/02.png"}'
# 5. Onwards — one screenshot per turn, one decision per turn
# 6. Always end with `quit`
"$TX" '{"cmd":"quit"}'
# → expect {"ok":true,"quit":true}. If "ok":false, run §6.5 recovery.
7.3 Teardown
kill "$(cat "$TMP/holder_pid")" 2>/dev/null || true
kill "$(cat "$TMP/pid")" 2>/dev/null || true
rm -f "$TMP/env"
After teardown, confirm no orphan sessions:
python3 ~/Projects/my-project-workspace/my-project/scripts/devicefarm/list-sessions.py
8. Cost model
| Item | Cost | Notes |
|---|---|---|
| Metered iPhone time | ~$0.17 / device-minute | Charged from RUNNING until stop_remote_access_session returns |
| Typical tunnel session | $1–3 per realistic walkthrough | ~6–18 minutes including app launch + sign-in + few flows |
--print-only |
$0 | Resolves + uploads the IPA, never reserves a device |
| Idle session during operator thinking | Yes, metered | Plan your next move before sending — but don't paralysis-by-analysis past a couple of minutes |
| Auto-stop guarantee | finally + SIGTERM + quit handler |
tunnel.py:main._try_stop returns False on stop failure, which raises the process exit code to 2 so CI / supervisors can alert. kill -9 bypasses this — recover with §6.5 |
| Bedrock tokens | Only in walkthrough / explore modes |
tunnel mode has no LLM-per-turn cost; the operating Claude is the brain |
The fundamental rule: a session that never reaches stop_remote_access_session keeps billing. Always end with quit, never kill -9, and run §6.5 if anything goes sideways.
9. Followups to file
When you hit one of these in the field, file in the my-project repo and link back to this guide. Do not patch them in the same PR that ships this doc — keep the doc PR pure.
mobile: keysfallback for system text fields. Either add a per-key tap-coords helper for the iOS on-screen keyboard, or document that My-Project tests should never depend on driving Spotlight / App-Library search.launch_app(shipped in my-project@22cf0cac) removed the most common reason an operator needed to drive system search at all, but Settings flows still hit it.- Document the bundled Appium driver version on Device Farm. A
mobile: getEnvprobe at session-start would lettunnel.pylog the WDA build version intostatusso future operators don't re-discover the upstream-vs-bundled drift from scratch. Shipped in my-project PR #6174 (merged 2026-05-29, SHAlaunch_app/activate_appJSON command intunnel.py.22cf0cac5d9b88d066b4badd94b59d480be5285e). See §4launch_appand §6.3.
Open these as my-project GitHub issues, link from
my-project/.claude/commands/iphonetest.md, and reference back here.
Last verified live: 2026-05-29 on iPhone 17 Pro / iOS 26.3.1 against
My-Project staging IPA, pinned to my-project@22cf0cac5d9b88d066b4badd94b59d480be5285e
(scripts/devicefarm/tunnel.py, my-project PR #6174). When anything in §4 / §5 /
§6 changes, update this file, re-pin the SHA, and update the upstream
slash-command in the same PR-pair.