Mobilebox
Menu
Agent guideDocs pages and contents

On this page

Mobilebox

Mobilebox gives you cloud Android phones (Android 14, arm64) over API and MCP: $0.01 a minute, ready in 19.4 s in our November 2026 benchmark. Mobile Sandboxes, controllable by your agents: your existing agent supplies the reasoning. You read the screen as a numbered list of elements, act on it, and delete the phone when done, or park it to resume later. Parked phones are shut down and free; apps, data and logins stay, and apps start fresh after a resume. A ready cloud Android phone costs $0.01 per minute, billed per second with a one-minute minimum per session; boot time is free. No API key yet? Follow https://mobilebox.dev/setup.md: your user gives you their email and you get a key at once; their 6-digit code keeps the workspace. New workspaces get free credit; add credits from the dashboard. iPhone and iPad: platform: "ios" ($0.05 per phone-minute). Real Android devices: device: "real" ($0.01 per phone-minute, the cloud price). Apps that need more memory or storage: size: "large" (4 GB RAM and 16 GB storage, $0.02 per phone-minute); the phone’s memory_gb and disk_gb say what it has, and if none is free the answer says so and offers a normal phone. A home or carrier IP in a city: network: "residential" ($8 per GB) or "mobile" ($15 per GB) with city, e.g. Berlin; GPS, timezone and locale match it. Every response says which platform and device you got; follow next on any error.

The loop

  1. create_phone (MCP) / POST /v1/phones?wait=ready / node src/cli.ts create. MCP and the CLI return the first screen once ready. REST create returns phone metadata; inspect status, poll the same id if still booting, then call GET /v1/phones/{id}/observe.
  2. Read the screen. Each line looks like [4] Row "Device name" — Pixel (540,550): ref, type, text, secondary text, state, center. A toast: "Imported" (com.app, 2 s ago) line under app: is a toast from the last 10 s: many apps confirm a save or report an error only there.
  3. act with a few actions at once, e.g. [{"type":"open_app","package":"com.android.settings"},{"type":"tap","target":{"text":"About phone"}}]. You get per-action results and the new screen.
  4. Repeat 2 to 3. Batch the steps you’re sure of; observe when you aren’t.
  5. delete_phone when done, even when the task failed; park_phone instead only to resume that phone later.

Targets

targetmeaning
{"text":"Sign in"}best default: exact match, then contains; nth picks among matches
{"ref":3}from the last screen you saw; fails with stale_ref if the screen moved on
{"id":"com.app:id/login"} / {"desc":"Navigate up"}resource id / content description
{"x":540,"y":1200}raw pixels, for what the list can’t show (use a screenshot)

Labels are in the phone’s language. country on create also sets the locale ("DE" gives German Settings), so the English labels in these examples match only an English phone; take labels from the screen you read.

Actions

tap, long_press, swipe {from,to}, scroll {direction}, scroll_to {text} (scrolls a list until the text is on screen; use it before tapping something below the fold), type {text, clear?, submit?, target?}, key {back|home|enter|delete|recents|tab}, back, home, open_app {package}, close_app {package} (sends it to the background, then force-stops it, like swiping it away in recents; the next open_app starts it fresh), wait {ms}, wait_for {text, gone?, timeout_ms}, receive_sms {from, text} (a test SMS arrives, e.g. the one-time code your app waits for).

Show the user

Missing something (a gesture, a device, an API)? Call request_capability (MCP) with what you needed and, optionally, why; the Mobilebox team reads every request and answers it.

publish_proof (MCP) / POST /v1/phones/{id}/proofs, when a test for a pull request is done (before deleting the phone), returns Markdown for the PR comment: passed or failed, duration, cost and up to 3 screenshots (deleted after 30 days). Before/after: publish the screen on main’s build first, then pass its image URL and "current" (on the PR’s build) with labels: ["Before", "After"]; they show side by side. For a video of the run, record_screen {action: "start"} (MCP) / POST /v1/phones/{id}/recording/start before it: publish_proof stops it and adds an MP4 link to the comment (up to 180 s, one per phone; stop ends it sooner; a park or delete ends it). Before/after: start it after publishing the Before proof, or that proof takes it. Example prompt and the GitHub Action: screenshots in every pull request.

watch_phone (MCP) / POST /v1/phones/{id}/view gives a live viewer link: the screen with your actions drawn on it and a caption per step. Offer it when the user wants to watch or confirm what you do; show the link, or run the npx mobilebox watch "<url>" command it comes with to open it in its own window. When a step needs your user (password, 2FA, captcha), give them the link: they press Take control, do it, and press Release. Meanwhile your calls on that phone return 409 human_in_control; GET /v1/phones/{id}?wait=ready&timeout=50 returns once they release it. Then observe before you act. Never ask them for the password.

Apps

install_app {url} (MCP) / POST /v1/phones/{id}/apps with the file bytes or {"url": …}: an .apk, or a split bundle (.apks, .xapk) from which the phone’s splits are picked (arm64-v8a, its screen density, its language, plus base and feature splits), up to 2 GB. Then open_app. Updates keep the app’s data; a different signing key is refused (signature_mismatch). Phones are arm64-v8a, Android 14. list_apps, uninstall_app (deletes the app’s data). Fresh apps may open with a permission dialog first: answer it like a user would.

App needs Google services (push, "Google Play services required")? Create the phone with google: "microg", or set it with set_device (MCP) / PATCH /v1/phones/{id}/device (one restart, apps and data stay): Google services via microG, open source. Push (FCM), Firebase Auth and Maps work; Play Integrity/SafetyNet, the Play Store and Play billing/licensing don’t.

App closed by itself, hangs or shows an error? app_logs {package} (MCP) / GET /v1/phones/{id}/apps/{package}/logs returns that app’s own log lines (Android logcat, its processes only, Java and native crash reports included) and how its processes last ended (crash, crash_native, anr, low_memory, user_requested for a force stop). Default: warnings and errors, the last 200 lines; level (V, D, I, W, E), lines (up to 1000) and since (ISO 8601 time) narrow or widen it.

Files

push_file {path, url} or {path, content} (MCP) / POST /v1/phones/{id}/files?path=… with the bytes, or {"url", "path"} without ?path=, up to 2 GB per file and 4 GB per phone, one push at a time: a file name lands in /sdcard/Download, which Android’s file picker shows under Downloads, so an app’s "Import" or "Open file" can pick it; or give a path under /sdcard/. pull_file {path} / GET /v1/phones/{id}/files?path=… reads a file back (MCP: text, or base64 for other files, up to 100 KB; PNG and JPEG as images up to 1 MB), or lists a folder; use it to find and check what an app wrote (a log, an export, a save).

type needs a focused text field: tap the field first (or pass target). If the text does not arrive you get type_not_applied instead of a silent success.

When something fails

Each error carries next, the exact thing to do instead, and retryable (the same call can succeed later). Read next before retrying. A batch stops at the first failed action, and the rest don’t run; a batch also stops starting new actions after 120 s (batch_timeout).

Request sizes: 20 actions per batch, JSON bodies up to 256 KB, ?wait=ready&timeout= up to 55 s per call (poll again while it says creating/starting). Unknown fields and wrong types are a 400 that changes nothing. The CLI exits 1 when a call or an action fails.

Capacity: all API keys in a project share its phones and balance. When a create (or start) needs more room, the answer is a 429 phone_limit or a 503 box_full saying we’re scaling your workspace, with a call link to raise it: next names a phone you can park or delete to go on now, and a 503 carries retry_after seconds (also the Retry-After header). Pass the call link to your user. Boots queue, so under load a create can take a few polls longer.

Authentication and discovery

Use an API key as Authorization: Bearer YOUR_API_KEY for phone-control REST and MCP calls. /v1/account/keys is browser-session-only key management, not an agent endpoint. Browser session cookies are separate. Read /llms.txt for the documentation index, /openapi.json for the REST schema, /docs/reference for response contracts, and /docs/errors for recovery. MCP is stateless Streamable HTTP at /mcp. Call tools/list for the actual input schemas. Keep keys in client secrets, not in model-visible prompts. The existing SDK/CLI use MOBILESANDBOX_API_KEY and MOBILESANDBOX_URL for compatibility.

Verify, then stop

A successful tap proves an input, not an outcome. Read the returned screen and verify the saved result. REST actions can return HTTP 200 with results[i].ok=false; MCP act includes failures in its result text. Earlier actions remain applied after a failed batch. Observe and continue from current state; do not blindly repeat a submit or other side effect.

Make creates safe to retry: pass a fresh unique idempotency_key (a UUID; no space at either end) to create_phone (REST: Idempotency-Key header; CLI: --idempotency-key). If you lose the response, retry with the same key and options: you get the same phone, not a second one, for 24 h. Other options with that key are a 409 idempotency_conflict; a deleted phone is a 410 phone_deleted. Without a key, list phones before retrying. Preserve the phone id for cleanup. Park on completion or failure when data should remain; delete disposable test phones. If cleanup itself fails, report it and inspect the phone rather than assuming it stopped.

A cloud Android phone is not a guarantee of Google Play services (microG covers push and the basics, see Apps), device certification, SIM/camera behavior, third-party app compatibility, physical-device performance, or an iOS runtime. Verify the exact application and workflow you need.

Source: SKILL.md in the repo, rendered at build time.