AI mobile app testing on real Android phones in the cloud
Install your APK on a cloud Android phone and let an AI agent work through test goals in plain words, with screenshots, step traces and a live screen.
Last updated 2026-11-05
Black Friday deposit bonus
Every qualifying top-up earns free credit, on top of any other offer.
Ends November 30
Scripted UI tests break every time a button moves, and a person tapping through the same flows before every release doesn't scale. An AI agent can do the tapping instead: you describe a test in plain words ("sign up with this email, add an item to the cart, check the total"), and the agent reads the screen, taps, types and scrolls until it has done it or found that it can't. Lovely Router's cloud phones are real Android 14 phones in the cloud. Install your APK on one, send it test goals over /v1/phones, and read back a pass or fail, the agent's answer and every step it took. A phone costs $1.20 per hour while it is awake, billed per minute, and nothing while it sleeps.
Hand it to your AI agent
Copy this prompt into Claude Code, Cursor, Codex or any coding agent. It tells the agent where the docs are and how to use your API key.
Upload my Android build to a Lovely Router cloud phone and run a short suite of plain-language test goals against it, reporting pass or fail with the agent's steps. - Docs (read first): https://lovelyrouter.com/docs/phone.md and https://lovelyrouter.com/docs/api/phones.md - Create a phone, upload and install the APK, start one agent run per test goal and poll it; collect each run's steps and final answer. Delete the phone at the end (billed while awake). - Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys. - Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large. - Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt. My task: <the APK and the test flows to check>
How it works
Upload your build
Store the APK once with
PUT /v1/phones/apks/{name}, up to 100 MB in one request, or up to 500 MB in 50 MB parts. Split bundles (.apks,.xapk) work too. Uploading to the same name replaces the file, so your CI can push every new build under one name.Start a phone with the app
Create a phone with your APK in
apps. A new phone takes about a minute to start, a little longer while it installs. Itsstartup_appsfield says whether each install worked and which package it installed.Run each test as a goal
Send each test to
POST /v1/phones/{id}/runsas a goal in plain words, with every value it needs. The run endssucceededwhen the agent reached the goal andfailedwhen it decided the goal can't be reached, with its reason inanswer.trace=1returns each step.
Run a test goal against your APK
Upload the build, start a phone with it and wait until it is ready:
curl -X PUT https://lovelyrouter.com/v1/phones/apks/myapp-latest.apk \
-H "Authorization: Bearer $LOVELY_API_KEY" \
--data-binary @app/build/outputs/apk/release/app-release.apk
curl https://lovelyrouter.com/v1/phones \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"apps": ["myapp-latest.apk"], "name": "release-check", "wait": 50}'Then send the tests one after another to the same phone. This Python script runs a short suite and prints a result per test:
import os, requests
API = "https://lovelyrouter.com/v1/phones"
H = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"}
PHONE = "ph_..." # the id from POST /v1/phones
TESTS = {
"signup": "Open MyApp. Sign up with the email qa+signup@example.com and the password Test-1234. "
"Pass if the home screen greets the new user; report the greeting.",
"cart": "Open MyApp, search for 'blue mug', add the first result to the cart and open the cart. "
"Report the item name, quantity and total exactly as shown.",
"settings": "Open MyApp's settings, switch the language to German and go back to the home screen. "
"Pass only if the home screen is now in German.",
}
for name, goal in TESTS.items():
run = requests.post(f"{API}/{PHONE}/runs", headers=H, json={"goal": goal, "max_steps": 40}).json()
while run["status"] in ("queued", "running"):
run = requests.get(f"{API}/runs/{run['id']}", headers=H, params={"wait": 50}).json()
if run["status"] == "waiting":
print(name, "needs a person:", run["question"])
continue
trace = requests.get(f"{API}/runs/{run['id']}", headers=H, params={"trace": 1}).json()["trace"]
print(f"{name:<10} {run['status']:<10} {run['steps']:>3} steps {run['answer'] or run['error']}")
for s in trace:
if not s["ok"] or s.get("unchanged"):
print(" step", s["step"], s["action"], s.get("error") or "screen did not change", "-", s["note"])A phone runs one goal at a time, so the tests go in order; a second run on a busy phone gets 409. To test in parallel, start more phones: each account can have 3 at a time.
How the agent works through a test
In the default smart mode, each step is one tool call by a chat model. The model gets the elements on screen (from Android's view tree, each with its position and flags such as clickable and editable) and the screenshot, and calls exactly one tool: tap, long_press, swipe, scroll, type, key, open_url, launch or wait to act, ask_user to ask you something, or done to finish with an answer. Every step records a note with what it saw and why it acted, the action, the app in front, whether it worked, and unchanged: true when the action left the screen exactly as it was.
The default model is gemini-3.8-flash; pass any chat model from the model list as model. Its tokens are billed at the normal API price and the run reports them in llm_usd. A run takes up to 40 steps by default and up to 200 with max_steps; one that reaches the limit ends stopped.
Write goals like test cases. Give the agent every value it needs (accounts, search terms, expected text), and say what counts as a pass: "Pass if the total is shown in euros". The agent reports what it saw in answer, so ask it to copy the text you want to assert on, then check it in code.
Logins, codes and a person in the loop
A test account that needs a code sent by text message, or a flow only a person should approve, doesn't have to be skipped. The agent calls ask_user, the run turns waiting with a question, and you answer with POST /v1/phones/runs/{id}/reply. Or open the live screen, do the step by hand and reply done.
POST /v1/phones/{id}/screen returns a link to the phone's live screen. It opens in any browser without a plugin, can sit in an iframe in your own dashboard, and lets whoever has it watch and tap, so share it only with the person who should use the phone. The phone console does the same without code.
The agent never pays, sends money, deletes data or posts publicly unless the goal says so. Use test accounts and a sandboxed payment setup for checkout flows anyway.
Screenshots, resets and logs
Between agent runs, your own code can drive the phone directly (direct control):
GET /v1/phones/{id}/screenshotsaves the screen as WebP for a test report, 540 pixels on its short side.POST /v1/phones/{id}/actionswith{"action": "shell", "command": "pm clear com.example.myapp"}resets the app's data before the next test, andlogcat -d -t 300 *:Ereturns the latest errors inoutput.{"action": "launch", "package": "com.example.myapp"}opens the app at its start screen;{"action": "rotate", "orientation": "landscape"}checks the landscape layout.
curl https://lovelyrouter.com/v1/phones/ph_.../actions \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"action": "shell", "command": "logcat -d -t 300 *:E"}'Installing a new build on a phone that has the app already updates it: POST /v1/phones/{id}/apps with {"apk": "myapp-latest.apk"} returns when the install is done.
What it is good at, and what it isn't
AI tests suit the flows people use: onboarding, search, checkout, settings, a regression you can describe in a sentence. They keep working when a layout changes, because the agent reads the screen each step rather than looking for a fixed view id. They are slower than scripted tests (a few seconds a step in smart mode) and they judge by what is on screen, so a check that needs exact pixel comparisons or timings belongs in your own test code. Every phone is the same Android 14 phone in the cloud, with Google Play services and no Play Store, so it doesn't replace testing on a range of physical devices and Android versions.
What you pay
| Price | |
|---|---|
| Phone while awake | $1.20 per hour, billed per minute |
| Phone while asleep | Free |
| Agent runs | The chat model's tokens at the normal API price |
| Uploaded APKs | The first 1 GB free, then $0.30 per GB a month |
A phone falls asleep after 5 minutes without use and wakes in about 2 seconds with the screen as it was. A phone unused for 1 hour is deleted with its apps and data; delete it yourself with DELETE /v1/phones/{id} when a suite ends. Starting a phone needs 15 minutes of phone time on your balance. The same prepaid key pays for models, data tools and cloud agents, with no subscription.
Frequently asked questions
Can I test my own APK that isn't in any store?+
Yes. Upload it with PUT /v1/phones/apks/{name} and install it by name, or list an https:// link to the file in apps. Any APK works, and so do .apks and .xapk bundles.
How do I know whether a test passed?+
The run ends succeeded when the agent reached the goal and failed when it decided it couldn't, with the reason in answer or error. Ask the agent to report the text you care about and assert on it in your own code.
Can I see what the agent did on each step?+
Yes. GET /v1/phones/runs/{id}?trace=1 lists each step's action, its note on what it saw and why, whether it worked, and whether the screen changed. Take screenshots with the screenshot endpoint for your report.
What happens when the app asks for a verification code?+
The agent asks you: the run turns waiting with a question, and continues when you reply. You can also finish the step yourself on the live screen.
Can I run tests in parallel?+
Each phone runs one goal at a time, and each account can have 3 phones at once, so up to 3 tests run side by side.
Does it work with iOS apps?+
No. Cloud phones run Android 14 only.
Want an agent that plays games on the phone instead? See the AI game playing agent. Every endpoint and field is in the phone API reference, and the browser agent does the same for web apps.