ProductIntegrationsPricingFAQFeedbackX
All posts

Keep Your Phone Awake While Your AI Agent Tests, Without Changing Your Settings

Ike Studios LLC

Ask an AI coding agent to test your React Native app on your iPhone and the hard part isn't the test. It's everything before the first tap: WebDriverAgent has to be signed and running on the phone, Developer Mode has to be on, Metro has to be reachable from the device, the Expo dev client has to load your bundle instead of its launcher screen, and the phone has to stay awake for the whole session. Miss any one and the agent's taps silently do nothing, the screen goes black mid-flow, or the session drops with the phone sitting on the lock screen.

Ceraph is built to make physical-device testing something your agent can run on its own. It's an MCP server that lets your coding agent drive and test a React Native or Expo app on iOS devices and simulators, plus Android devices and emulators. One call brings a real iPhone or Android phone to a ready-to-test state, and Ceraph keeps it awake and reachable while the agent works.

Why agent testing on a real device keeps breaking

Device automation on a real phone has a familiar set of failure modes, and they're well documented across the Appium and XCUITest community:

  • The phone auto-locks. When the screen sleeps, the automation session loses the app. Testers report an iPhone locking hours into an Appium run even with Auto-Lock set to Never. With a passcode set, a restarted session lands on the lock screen and stays down until someone unlocks the phone by hand.
  • WebDriverAgent disappears or won't launch. WDA vanishing from the device and xcodebuild failed with code 65 are among the most common real-device threads.
  • The device isn't actually connected. A locked phone, a pending "Trust This Computer?" prompt, or a charge-only cable can make an attached iPhone invisible to the tools that look for it.
  • The app never loads its JavaScript. The build succeeds, the app opens, and it sits on a redbox or the dev-client launcher because the phone can't reach Metro.

A human tester notices these in seconds. An agent running unattended doesn't, unless the tool tells it.

The manual setup

If you're wiring this up yourself, the usual checklist is:

  • iOS: sign and install WebDriverAgent through Xcode, enable Developer Mode (Settings → Privacy & Security → Developer Mode), trust the Mac, and set Settings → Display & Brightness → Auto-Lock → Never. Keep the phone unlocked; automation can't get past Face ID or a passcode.
  • Android: enable Developer options and USB debugging, accept the host authorization prompt, keep the screen on with adb shell svc power stayon usb (or Developer options → Stay awake), and route Metro over USB with adb reverse tcp:8081 tcp:8081.
  • Both: start Metro, build and install the development build, open it, get past the Expo dev-client launcher to your bundle, and remember to restore the phone's display settings afterward.

That works for a person at a desk. For an agent, every step is a place to get stuck with no one watching.

One call: ceraph_start

Your agent calls ceraph_start (or you run ceraph start --device), and Ceraph brings the phone to a ready-to-test state:

  • Metro started or reused for this project.
  • Build and install of the development build, only when the installed app is missing or stale.
  • The automation driver: WebDriverAgent on iOS, after a one-time install through Xcode; UiAutomator2 on Android. Ceraph manages subsequent starts, including the USB connection to WebDriverAgent.
  • Wake and unlock verification, so the agent doesn't start driving a sleeping phone.
  • Expo dev-client routing past the launcher to your project's bundle.

ceraph_start runs only what's missing and stops at the first step that fails, with remediation for that step. On a physical iPhone it also checks that the app actually loaded and ran its JavaScript, because a green build isn't proof. The Metro side of that, including which redboxes Ceraph recovers from on its own, is covered in our guide to Metro redboxes.

Keeping the phone awake while the agent drives

Keep-awake is on by default for physical devices. While Ceraph is driving, the iPhone or Android phone stays awake for the whole run, so a long session doesn't end on the lock screen halfway through a flow. As of October 2026, Ceraph is the only mobile MCP that keeps an iPhone connected to your computer awake on its own. When the session ends, Ceraph restores the phone's normal behavior. On Android, that includes putting back the display settings you had before.

On a real iPhone, terminating the app under test keeps WebDriverAgent available, so the agent can relaunch and keep going without starting over.

Keep-awake keeps an unlocked phone awake, and Ceraph wakes and unlocks a phone that has no passcode on its own. A phone protected by a passcode or Face ID needs you to unlock it once; no automation can get past those. If such a phone is already locked, device_ensure_awake returns structured remediation, and Ceraph tells a locked phone apart from an automation session that iOS suspended, so the agent reports the right fix: unlock once and re-run ceraph_start. You can turn keep-awake off with the keepAwake preference or CERAPH_KEEP_AWAKE_HEARTBEAT=off; the ordinary wake and unlock check still runs.

When the phone isn't ready, Ceraph says why

Bring-up failures come back as named problems with the fix, not as silent no-ops:

  • Developer Mode is off: Ceraph says so and gives the Settings path.
  • An iPhone is plugged in but can't be reached (locked, not yet trusted, or on a charge-only cable): Ceraph stops and says which checks to make. It won't quietly fall back to a simulator while you think you're testing on the phone.
  • An iPhone can't reach Metro over the network: with a USB data cable connected, Ceraph re-routes the development build over USB and checks again; otherwise it returns remediation. Android phones reach Metro through adb reverse.

Before you start, ceraph doctor checks project and runtime readiness without building anything. rn_wait_for_device waits for a phone to be plugged in and authorized, and rn_target_status reports which runtime is active and whether automation is ready.

Picking the right device

Ceraph selects devices conservatively, so the agent tests where you expect:

  • One USB phone connected: ceraph start --device selects it, iPhone or Android.
  • Several devices: pass the exact Apple UDID/CoreDevice identifier or Android adb serial.
  • Wi-Fi: a phone reachable only over Wi-Fi is never selected automatically. Approve that specific phone with ceraph start --device <id> --wifi, and revoke the approval with --no-wifi. Approval lasts until the session ends.
  • More than one agent: one running app has one active Ceraph driver. A second agent gets a busy result instead of fighting over the same phone.

Walkthrough: onboarding on your iPhone

You plug in your iPhone, unlock it, and ask your agent: test the new onboarding flow on my phone.

  1. Bring-up. The agent calls ceraph_start. Ceraph reuses Metro, rebuilds because a native dependency changed, starts WebDriverAgent, confirms the phone is awake, and routes the dev client to your bundle.
  2. Drive. The agent reads each screen with ceraph_snapshot and works through the flow with screen_tap and screen_type_into_field: the welcome screens, the permissions step, profile setup.
  3. Stay up. The agent takes twenty minutes, fixes a layout bug it finds on step three, and re-runs the flow. The phone stays awake the whole time, and you're not at your desk.
  4. Read the errors. If anything throws, rn_get_errors puts it in the conversation, and the agent reports the actual failure.

When it's done, Ceraph restores the phone's normal sleep behavior.

Where this fits

If you're weighing Ceraph against other mobile MCPs, our comparison walks through startup and the rest of the workflow.

Plug in your phone and get started.