API reference
Mobilebox is an API + MCP runtime for cloud Android phones for AI agents (Android 14, arm64): $0.01 a phone-minute, ready for a first screenshot in 19.4 s in our November 2026 benchmark. Bring your own agent: the service does not run a language model or accept a natural-language task endpoint.
Authentication
No key yet: setup.md walks an agent through it. POST /v1/signup/email {email, key_name?, via?} mails the user a 6-digit code. For a new address it also answers with api_key (shown once, stored only as a hash), key, project, claimed: false, balance_usd (a small trial), expires_at, message_for_user (tell your user this line), mcp_url and next_steps: the key works at once, for one phone at a time, and without the code the workspace closes at expires_at (7 days; its phones are deleted). An address that already has a workspace, or one waiting for its code, gets only {sent: true, next}, never a second key. POST /v1/signup/verify {email, code, key_name?, via?} confirms: with Authorization: Bearer <that key> it answers 200 claimed: true and the key keeps working; without it, 201 with a new api_key and key {id, name, hint, created_at} (keys issued before the code end), plus project, new_account, balance_usd, mcp_url and next_steps, and message while the workspace has no credit yet. Neither needs a browser. A confirmed new address gets the starter credit; a known email account gets a new key for its own project; an address that signs in with GitHub or Google answers 409 account_exists (sign in there and create the key in the dashboard). A code works once, for 10 minutes; 5 wrong tries or a newer code retire it (400 auth_failed). Too many codes: 429 with retry_after. Store the key in the user’s secret store or environment; never print it.
Send Authorization: Bearer YOUR_API_KEY on phone-control /v1/* and /mcp requests. Exception: /v1/account/keys is browser-session-only account management, not an agent API; create/list/revoke keys in the dashboard. Issued agent keys cannot become browser sessions. Browser login and API-key authentication are separate. Get your key from the account dashboard; do not send a browser session cookie as an API bearer key. Existing SDK/CLI variables remain MOBILESANDBOX_API_KEY and MOBILESANDBOX_URL for compatibility. Public product name: Mobilebox.
export MSB=https://mobilebox.dev
# Load MOBILESANDBOX_API_KEY from your secret manager or shell environment.
curl --fail-with-body "$MSB/v1/account" \
-H "Authorization: Bearer $MOBILESANDBOX_API_KEY"JSON bodies require Content-Type: application/json. Unknown fields, malformed JSON, and wrong types fail with 400 before the requested operation. JSON bodies are limited to 256 KB. Installation accepts apps up to 2 GB, as a binary upload or a URL the server downloads (each within 15 minutes).
Credit
A phone’s session is held from the workspace balance when it starts (see Pricing). Without enough, the start is a 402 insufficient_credits whose message and next carry a top-up link for your user, https://mobilebox.dev/billing/top-up?amount=10: it opens Add credits in their dashboard with the amount picked. Agents can’t add credit themselves; their user does it there.
POST /v1/billing/checkout {amount_usd} ($5 to $1,000, whole cents) answers 201 {id, status: "open", amount_usd, url, expires_at}: open url, Stripe’s payment page (card, Apple Pay, Google Pay), within the hour. Or it answers 202 {status: "processing", amount_usd, message}: the top-up is finished by email, as message says. The balance moves only once Stripe confirms the payment, usually within seconds; GET /v1/billing/checkout/{id} then says paid with the new balance_usd. Asking again for the same amount while that page is open returns the same session. GET /v1/account/credits lists payments (paid, partially_refunded, refunded, with receipt_url) and requests, newest first. A refund takes its amount off the balance again, never below $0.
Phone lifecycle
| Method and path | Request | Result |
|---|---|---|
| POST /v1/phones | Optional name, country, city, network, platform, device, size, idle_timeout, max_duration, timezone, locale, location, proxy, google, task; optional Idempotency-Key header | 201 phone, possibly still creating |
| GET /v1/phones | None | data array of this project’s phones |
| GET /v1/phones/{id} | None | Phone metadata and status |
| POST /v1/phones/{id}/start | Optional idle_timeout, max_duration | Starts or waits on existing phone |
| POST /v1/phones/{id}/park | No body | Shuts down, keeps apps/data/logins |
| DELETE /v1/phones/{id} | No body | 204; deletes phone and data |
| GET /v1/phones/{id}/sessions | None | Session timestamps, billed seconds, costs, end reasons |
| GET /v1/account | None | Project id, spent_usd, balance_usd, configured price (per_minute_usd, large_per_minute_usd, minimum_seconds), devices; email when available in a browser session |
| POST /v1/account/welcome | One of: wants (list of ios_real, android_real, android_cloud, live_view, other; optional wants_other), source (chatgpt, claude, perplexity, google, github, x, reddit, hackernews, friend, other; optional source_other), or skip: true | The optional questions the console asks once after sign-up; answers welcome: source or done |
| PUT /v1/account/devices | devices: list of android_cloud, android_real, iphone, ipad | The saved answer to "Which devices do you need?" (see below) |
Create, get, and start accept wait=ready or wait=parked and timeout=0 to 55 whole seconds. Default timeout: 50. A wait timing out can still return a creating/starting phone successfully. Inspect status and poll GET on the same id until ready, failed, or your own deadline; do not create duplicates.
{
"id": "ph_example",
"object": "phone",
"name": "smoke-test",
"platform": "android",
"device": "cloud",
"status": "ready",
"created_at": "2026-01-01T00:00:00.000Z",
"settings": { "timezone": "Europe/Berlin", "locale": "de-DE" },
"session": {
"id": "ses_example",
"started_at": "2026-01-01T00:00:00.000Z",
"ready_at": "2026-01-01T00:00:25.000Z",
"last_active_at": "2026-01-01T00:00:25.000Z",
"idle_timeout": 300,
"max_duration": 900,
"reserved_usd": "0.150000"
},
"failure": null
}This is an illustrative shape, not a recorded session. Settings reflect the configured fields. Phone status can be creating, starting, ready, parking, parked, failed, or deleted. Inspect failure.code and failure.message when failure is present; failed phones can be started again.
task is one line on what your agent is trying to do ("test the sign-up flow of my Android app"). It’s optional, helps us build what agents need, and is never shown publicly; MCP’s create_phone takes it too.
Defaults: idle_timeout 300 seconds, max_duration 900 seconds. Their ranges are 60 to 3,600 seconds and 60 to 10,800 seconds respectively. A session reserves its maximum charge against available balance; inspect the account and session endpoints for the configured rate and actual billed usage. All keys in the same project share its phones and balance. When a create needs more room, the answer says we’re scaling your workspace and links a call to raise it (see errors).
Devices
| Device | Price | Ask with |
|---|---|---|
| Cloud Android 14 phone (arm64) | $0.01 per phone-minute | default |
| Large cloud Android phone: 4 GB RAM and 16 GB storage | $0.02 per phone-minute | size: "large" |
| iPhone and iPad | $0.05 per phone-minute | platform: "ios" |
| Real Android device | $0.01 per phone-minute | device: "real" |
| Dedicated devices | from $79 per month | the call below |
Every response says which platform and device you got, and each is billed at its price above. A notice field carries anything else worth knowing about the phone you got; errors such as setup_required are in errors.
Every phone JSON says its size (normal or large), the RAM and storage it has (memory_gb, disk_gb) and its rate (per_minute_usd); a large create’s notice says the same in a sentence. A phone keeps its size across park and start, and is billed per second at its own rate with the same one-minute minimum; GET /v1/account lists both rates (price.per_minute_usd, price.large_per_minute_usd). When no large phone is free, the create (or a large phone’s start) answers 503 large_unavailable, creates and charges nothing, and says how to go on with a normal phone now (see errors).
MCP create_phone takes the same platform, device and size. The dashboard asks "Which devices do you need?"; PUT /v1/account/devices saves that answer. Volume over 100 devices: contact sales on the same call.
Retry a create safely
Send an Idempotency-Key header (1 to 64 printable ASCII characters with no space at either end; a UUID is safest) with POST /v1/phones to make the create safe to retry after a lost response. The MCP create_phone tool takes the same value as idempotency_key; the SDK as create({ idempotencyKey }); the CLI as create --idempotency-key.
| Retry within the window | Result |
|---|---|
| Same key, same options | 201 with the same phone in its current state, including parked or failed. No new phone, session, reservation, boot, or limit/credit check. |
| Same key, other options | 409 idempotency_conflict; the error does not repeat your input |
| Same key, phone was deleted | 410 phone_deleted; use a new key for a new phone |
| Rejected create (400, 402, 429, 503) | Nothing is claimed; fix the cause and retry with the same key |
Keys are scoped to the project, not the API key. A key holds for 24 hours from the phone’s creation, and longer while that phone is still creating; after that the same key creates a new phone. Options are compared as the phone would run them: omitted idle_timeout, max_duration and name equal their defaults, country equals the timezone, locale and location it sets, and a null proxy equals none. The wait and timeout query parameters are not options. Later changes to the phone do not make a retry a conflict. Without the header, every POST creates a phone as before. The key covers create only; start, park and delete have no key.
HTTP removes spaces at the ends of a header value before the API sees it, so a raw REST key " abc " arrives as "abc". The SDK, CLI and MCP refuse such keys with 400 invalid_request rather than change them. The key, its phone and the reservation are saved together before the phone boots, so they survive an API crash or restart. A host power loss can lose the most recent create, along with its key and phone.
Read the screen
GET /v1/phones/{id}/observe returns app, elements, and text, plus toast {text, app, age_ms} while an app’s last toast is under 10 s old (the text gets a toast: "Saved" (com.app, 2 s ago) line under app:); notifications never show. Add ?format=text for a compact numbered list. GET /v1/phones/{id}/screenshot returns image/png. The phone must be ready.
[4] Button "Save" (540,1080)
[5] TextField "Draft" [focused] (540,865)Illustrative lines: ref, element type, text, state, center. Observe again after a screen change; old refs may fail with stale_ref. A screenshot is useful for images, maps, or canvases absent from the accessibility tree.
Watch live
POST /v1/phones/{id}/view returns { url, expires_at, command } for a running phone. The url opens a viewer that shows the phone’s screen live with each action drawn on it: a cursor moving to the target, a ripple per tap, the path of each swipe, the text being typed (dots for password fields), and a caption per step ("Tapped "Search""), also announced to screen readers. Watching does not count as activity on the phone. command is npx mobilebox watch "<url>", which opens the viewer in its own app window (Chrome or Edge, else the default browser); npx mobilebox watch <phone_id> asks for a link with MOBILESANDBOX_API_KEY first. The dashboard’s Phones page has a Watch button on every running phone.
The link is short-lived and grants only this phone’s view in this workspace; the access token is in the URL fragment, so it reaches no server log. Ask for a new link after expires_at. The view ends when the phone parks or is deleted.
Your user takes control
When a step needs your user (a password, a 2FA code, a captcha, a one-time login), give them the link: signed in to mobilebox.dev in that workspace, they press Take control, tap and type on the phone, and press Release to agent. While they hold it, every call on the phone (act, observe, screenshot, apps, files, device, recording, proofs) answers 409 human_in_control with retry_after 10; GET /v1/phones/{id}?wait=ready&timeout=50 returns once they release it. Then observe before you act, and never ask them for the password. The phone’s JSON shows control: {by: "human", since} while they hold it, else control: null. Start, park and delete still work. It ends on Release, after 3 minutes without input, 30 s after they close the view, or when the phone parks or is deleted. The browser routes (POST|DELETE /v1/phones/{id}/control, POST /v1/phones/{id}/input) take a signed-in person’s session only: an API key gets 403 owner_only. Other viewers are cut off while they hold it. Every takeover is recorded (who, when, how many inputs, never the text).
Publish a proof
POST /v1/phones/{id}/proofs with {title, status: passed|failed, screenshots?, labels?} returns 201 { id, markdown, images, video?, labels?, duration_s, cost_usd, created_at, expires_at }. markdown is the PR comment: one line (✅ Login flow tested on a Mobilebox cloud phone · Android 14 · 38 s · $0.01), up to three screenshots, a link to the screen recording if one was made, and "Tested on Mobilebox". Post it yourself; Mobilebox shows proofs nowhere else.
Duration and cost are the phone’s session (the running one so far, else the last one), never sent by you. screenshots: up to 10, each "current", a base64 PNG of up to 2 MB, or an image URL from an earlier proof of this workspace (its screenshot is copied, so a screen can be pinned before a reinstall); left out, one of the current screen. labels: one short name per screenshot, for up to 3, e.g. ["Before", "After"]; the comment then shows the screenshots side by side in one table row under them. Before/after: publish a proof of the screen on main’s build, install the PR’s build, open the same screen and publish with screenshots [the first image URL, "current"] and labels ["Before", "After"]; post only the second. images lists their URLs: image files at unguessable addresses, not indexed, deleted 30 days after publishing. DELETE /v1/proofs/{id} deletes them sooner. Nothing is stored until you publish. Idempotency-Key works as on create.
Screen recording
POST /v1/phones/{id}/recording/start records the phone’s screen from now on, as an MP4 (H.264, a square of half the screen’s longer side, so portrait and landscape apps both fit, a frame only when the screen changes; an 8 s run through Settings was 0.8 MB). One recording per phone at a time (a second start is 409 recording_in_progress), up to 180 s: Android stops it by itself then. POST /v1/phones/{id}/recording/stop ends it sooner; stopping again changes nothing. Both return { object: "recording", status: recording|stopped, started_at, max_duration_s: 180, duration_s, bytes } (duration_s and bytes once stopped). The next published proof takes the recording, stopping it first if it still runs: its markdown gets a line ▶️ [Screen recording · 12 s](…/screen.mp4) and the response a video URL. Two publishes at once: the first takes it. Before/after: start recording after publishing the Before proof, or that proof takes it. If the recording cannot be saved, the proof is still published, without the video, and its notice says so. The MP4 is stored and deleted like the proof’s screenshots: an unguessable address, not indexed, served as video/mp4 with byte ranges, deleted 30 days after publishing or with DELETE /v1/proofs/{id}, and counted in the workspace’s proof storage. Parking, rebooting or deleting the phone ends a recording, and one not yet published is dropped; start it again after a park. Stop with nothing recorded is 409 no_recording; a stop the phone did not finish is 502 recording_failed. No extra charge: the phone’s minutes are the cost.
Send actions
POST /v1/phones/{id}/actions accepts an actions array of 1 to 20 items. It returns results and a fresh screen. It stops on first failure; earlier actions stay applied. HTTP 200 can contain a failed action: inspect every results[i].ok. Do not replay an entire batch blindly.
{
"actions": [
{ "type": "open_app", "package": "com.android.settings" },
{ "type": "home" }
]
}{
"results": [{ "type": "tap", "ok": false,
"error": { "code": "stale_ref", "message": "Illustrative error",
"next": "Observe again and use a current target.", "retryable": false } }],
"screen": { "app": "com.android.settings", "elements": [], "text": "Illustrative screen" }
}The example shows the failure envelope, not a live response. Screen app and element details are described in OpenAPI. A batch stops starting new actions after 120 seconds. Use wait_for for a screen condition; avoid long blind sleeps.
Target vocabulary
| Shape | Meaning |
|---|---|
| {"text":"Save"} | Exact match, then contains; optional nth starts at 1 |
| {"ref":4} | Reference from the most recent observed screen |
| {"id":"com.app:id/save"} | Resource id |
| {"desc":"Navigate up"} | Accessibility content description |
| {"x":540,"y":1080} | Raw pixels; verify with a current screenshot |
Action vocabulary
| type | Fields and limits |
|---|---|
| tap | target |
| long_press | target; duration_ms 100 to 10,000, default 800 |
| swipe | from and to as [x,y]; duration_ms 50 to 5,000, default 300 |
| scroll | direction: up, down, left, right |
| scroll_to | text; direction up/down (default down); max_swipes 1 to 30 (default 10) |
| type | text up to 2,000 chars; target optional; clear/submit default false |
| key | key: back, home, enter, delete, recents, tab |
| back / home | No additional fields |
| open_app / close_app | package; close_app backgrounds then force-stops |
| wait | ms 0 to 10,000 |
| wait_for | text; gone default false; timeout_ms 100 to 30,000, default 10,000 |
| receive_sms | from: a number (+491701234567, 12345) or a sender name of up to 11 letters and digits; text up to 160 characters (70 with emoji or non-Latin letters) |
receive_sms delivers a test SMS to the phone, e.g. a one-time code: apps that read incoming texts (RECEIVE_SMS) get it as they would from the network. No real number, SIM or carrier is involved, and nothing is sent anywhere. Google’s SMS Retriever API needs Play services, which cloud phones do not have. The phone has no SMS app, so the text is not shown in a notification or kept in an inbox.
Coordinates are integers from 0 to 10,000. Text targets are nonempty and up to 500 characters. Ref range: 1 to 10,000. Text nth range: 1 to 100. type goes into the focused text field: tap it first or pass target. type_not_applied means text did not reach it. With no text field on screen (terminals such as Termux, web editors) the text goes as key presses to whatever has input focus, unconfirmed: the result’s note says so; check the screen. Terminals take ASCII only.
Network
| Network | Price | Ask with |
|---|---|---|
| Standard network | included | default (network: "datacenter") |
| Residential IP: city targeting, sticky per phone | $8 per GB | network: "residential" |
| Mobile carrier IP: city targeting, sticky per phone | $15 per GB | network: "mobile" |
| Your own proxy | included | proxy |
Add country and city to choose where, e.g. {"network": "residential", "country": "DE", "city": "Berlin"}. A city sets GPS, timezone and locale to match it (Berlin: 52.52, 13.405, Europe/Berlin, de-DE), and implies its country. Any city name works (letters, spaces and hyphens, up to 64): for one we’re still setting up, the phone uses its country’s location meanwhile and notice says so. Residential and mobile traffic is billed per GB. Your own proxy wins over network. A notice field says anything worth knowing about the network the phone is on. PATCH /v1/phones/{id}/device and MCP set_device take network, country and city too.
Acceptable use: no fake engagement, fake accounts, spam or evading platform protections (terms).
Install and manage apps
POST /v1/phones/{id}/apps accepts binary APK/.apks/.xapk bytes, or JSON {"url":"https://download.example/app.apk"}. Optional grant_permissions=true is accepted in the query or JSON install body. The response is 201 with package, version_code, and version_name. Split selection uses arm64-v8a, density, language, base and feature splits.
GET /v1/phones/{id}/apps lists user-installed packages and version_code. DELETE /v1/phones/{id}/apps/{package} uninstalls and deletes app data, returning 204. Updating retains data when the signature is compatible; signature_mismatch requires an intentional fresh-install decision, not automatic uninstall.
GET /v1/phones/{id}/apps/{package}/logs returns an installed app’s own log lines and its last exits: {"lines": [{"time", "pid", "level", "tag", "message"}], "exits": [{"time", "pid", "process", "reason", "subreason", "status", "description"}]}, both newest last. Lines come from the phone’s logcat (main, system and crash buffers, which hold Java exceptions and native crash reports), only those logged under the app’s own uid: never the system’s, the kernel’s or another app’s. Query: level V, D, I, W or E, the lowest level shown (default W); lines 1 to 1000, the newest lines (default 200); since an ISO 8601 time, for lines and exits alike (default: all the phone still holds, its ring buffers keep about 256 KB each). Messages are cut at 300 characters. exits are the last 5 ApplicationExitInfo records: reason is crash, crash_native, anr, low_memory, signaled, user_requested (a force stop, subreason force_stop), exit_self and the other REASON_ names in lower case; status is the exit status or signal; description is Android’s, or null. Exit times come from Android’s dump in the phone’s time zone, converted with its current UTC offset: an exit from before a daylight saving change is off by that shift. A package that is not user-installed is 404 app_not_installed.
Files on the phone
Files live in the phone’s shared storage, /sdcard (the same as /storage/emulated/0). path is a file name, which goes to /sdcard/Download (Downloads in Android’s file picker, so apps that import a file can pick it), or a path under /sdcard/. .. and paths outside /sdcard are refused with invalid_path.
POST /v1/phones/{id}/files?path=game.apk accepts the file bytes as the body (up to 2 GB, streamed; any content type, a .json file too), or without ?path= JSON {"url":"https://download.example/world.mcworld","path":"world.mcworld"} for a download. Folders on the way are created and a file at that path is replaced. The response is 201 with path and size. The file shows in the picker at once. Pushed files can fill up to 4 GB of a phone’s shared storage (phone_storage_full past that), one push at a time per phone (push_in_progress).
GET /v1/phones/{id}/files?path=… returns a file’s bytes (application/octet-stream, up to 2 GB), or for a folder JSON {path, data: [{name, type: "file" or "dir", size}]}. Without path it lists /sdcard/Download.
Configure device settings
GET /v1/phones/{id}/device reads adapter-reported settings. PATCH accepts country and city (GPS, timezone and locale together), network (see Network), timezone (IANA), locale (BCP-47), location {lat,lng}, proxy (a supplied socks5:// URL or null for direct egress), battery {level 1 to 100, charging default false}, camera_image (an https link to a JPEG, PNG or WebP up to 10 MB, or null for a test pattern), and google ("microg" or "none", see Google services (microG)); explicit fields win over the ones a city sets. These settings persist across park/start. Changing locale restarts the UI; changing google restarts the phone (below); observe again afterward. GET and PATCH report battery {level, charging}, camera ("image" or "test pattern") and google ("microg" or "none").
New phones have a full battery on AC power. camera_image is what an app gets when it asks the camera app for a photo (ACTION_IMAGE_CAPTURE, e.g. "take a photo" for a profile picture or document upload): use it for a QR code, an ID card or a selfie. Apps that open the camera inside themselves (most QR scanners, KYC selfie SDKs) find no camera on cloud phones; use a real device for those. Cloud phones have no motion or light sensors.
Country and city are shortcuts for timezone, locale, and GPS; the IP comes from the network (see Network). Proxy credentials are redacted from phone metadata; keep secrets out of your own logs and screenshots too.
Google services (microG)
google: "microg" on create (REST, MCP create_phone) or on PATCH /v1/phones/{id}/device (MCP set_device) gives the phone Google services via microG, open source (Apache-2.0): Google’s own Play services are not on it. Apps that need Google services find them: push (Firebase Cloud Messaging), Firebase Auth, Maps and location work; Play Integrity/SafetyNet (and so most banking apps and anti-cheat), the Play Store, Play billing and licensing don’t, and Google sign-in and Play Games are partial and need a Google account. Install apps with install_app.
Switching on a running phone restarts it once (about 25 s) in the same session; its apps, data and logins stay, and every other setting is applied again. A parked phone gets it at its next start; a phone still booting answers phone_starting. "none" (the default) takes it off again; turning it off and on again starts microG fresh (its Google account, device registration and push tokens are gone), while apps and their data stay. The phone JSON’s settings show "google": "microg" while it is on. Same price as any cloud phone. If the host cannot provide it, the answer is 503 microg_unavailable and nothing changes (see errors).
microG (GmsCore and Companion, https://github.com/microg/GmsCore) is Copyright 2013-2025 microG Project Team, licensed under the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0). We run the official, unmodified microG release builds. microG is not affiliated with Google; Google Play is a trademark of Google LLC.
Python client
pip install mobilebox (PyPI): a typed client for the REST API, Python 3.10 and newer, standard library only. Mobilebox() reads MOBILESANDBOX_API_KEY and MOBILESANDBOX_URL (default https://mobilebox.dev), waits 65 s per request and sends mobilebox-python/<version> as User-Agent; pass api_key, base_url, timeout or user_agent to change them. Quickstart example.
| Method | Does | REST |
|---|---|---|
create_phone(**options) | Create a phone and return it ready (wait=False returns at once; idempotency_key= to retry across processes). Options are the create fields above | POST /v1/phones |
list_phones(), get_phone(id) | This project’s phones, one phone | GET /v1/phones, GET /v1/phones/{id} |
park_phone(id), start_phone(id) | Shut down and stop billing; resume with apps and data | POST /v1/phones/{id}/park, /start |
delete_phone(id) | Delete the phone and everything on it | DELETE /v1/phones/{id} |
observe(id) | The screen: Screen(text, app, elements); screen.find(text) returns the element | GET /v1/phones/{id}/observe |
act(id, actions) | Run 1 to 20 actions, stop at the first failure: ActResult(results, screen) | POST /v1/phones/{id}/actions |
screenshot(id) | PNG bytes | GET /v1/phones/{id}/screenshot |
install_app(id, url=None, file=None, grant_permissions=False) | Install an APK, .apks or .xapk from a public URL, a path or bytes | POST /v1/phones/{id}/apps |
watch(id) | A live view link for a person, who can take control | POST /v1/phones/{id}/view |
request(method, path, body) | Any other endpoint, with the same auth and errors | Any |
Every API error raises MobileboxError with code, message, next, retryable, retry_after and the HTTP status; do what next says before retrying. A failed action is not an exception: act returns result.ok == False and result.error, earlier actions stay applied, and you continue from result.screen. create_phone sends an Idempotency-Key (a UUID unless you pass one) and retries retryable errors with it; phone_limit and box_full are not retried.
For LangChain and LangGraph agents, pip install langchain-mobilebox (PyPI) wraps this client as tools: MobileboxToolkit().get_tools() returns seven tools (mobilebox_create_phone, mobilebox_observe, mobilebox_act, mobilebox_screenshot, mobilebox_install_app, mobilebox_park_phone, mobilebox_delete_phone), or pass client= to single tools like MobileboxObserve and MobileboxAct so your code owns the phone. Errors come back to the model as text with code and next. LangGraph example.
MCP mapping
The authenticated /mcp endpoint uses stateless Streamable HTTP. Tools: list_phones, create_phone, start_phone, park_phone, delete_phone, install_app, list_apps, uninstall_app, app_logs, push_file, pull_file, observe, act, screenshot, set_device, watch_phone, record_screen, publish_proof, request_capability. publish_proof mirrors POST /v1/phones/{id}/proofs and returns the PR comment’s Markdown (see Publish a proof). record_screen {action: start|stop} mirrors POST /v1/phones/{id}/recording/start and /stop (see Screen recording). request_capability {what, why?} records something the agent needed that Mobilebox doesn’t offer yet, for the team to answer. Call tools/list through a compatible client for the actual input schemas. create_phone accepts idempotency_key with the same rules as the Idempotency-Key header. MCP installation accepts a URL; use REST for local binary uploads. push_file {path, url or content (text, or base64 with encoding "base64")} mirrors POST /v1/phones/{id}/files; pull_file {path?} returns a file inline, text or base64 up to 100 KB and PNG or JPEG as an image up to 1 MB, or a folder’s listing. app_logs {package, since?, lines?, level?} mirrors GET /v1/phones/{id}/apps/{package}/logs as text, one time pid level tag: message line each, the whole answer up to 20 KB (older lines are left out first, and it says so). REST exposes account/session/device-read endpoints beyond the current tool set. Every /mcp request needs a key or an OAuth access token on that same request; without one it answers 401 with a WWW-Authenticate header that names the sign-in (see MCP sign-in). Server card: GET /mcp/server-card, listed in /.well-known/ai-catalog.json.
MCP tool errors set isError and include code, message, and next guidance in text. An act result can contain a failed action within its normal result text; inspect the full result. Keep your API key out of model-visible prose.
MCP sign-in
Clients with MCP OAuth (Claude and ChatGPT connectors, Claude Code, Cursor, VS Code) need no key: add https://mobilebox.dev/mcp and the client signs your user in. A request without credentials gets 401 with WWW-Authenticate: Bearer resource_metadata="https://mobilebox.dev/.well-known/oauth-protected-resource/mcp"; the same document is also at /.well-known/oauth-protected-resource. It names the authorization server, https://mobilebox.dev, described at /.well-known/oauth-authorization-server.
- Registration: POST /oauth/register (RFC 7591). Every client is public (token_endpoint_auth_method none). redirect_uris: https, http on loopback (any port at sign-in) or an app scheme, no fragment.
- Authorization: GET /oauth/authorize with response_type=code, PKCE (code_challenge_method=S256 only), state and resource=https://mobilebox.dev/mcp. Your user signs in (GitHub, Google or an email code) and chooses Allow or Cancel for one workspace. The consent page names your client by its client_name only when the redirect goes back to a known client (claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, loopback, or the cursor, vscode and vscode-insiders schemes); otherwise it leads with the return host and shows client_name as what the client calls itself, not verified. The code works once, for 5 minutes; using it twice revokes what it gave.
- Tokens: POST /oauth/token (form-encoded) with authorization_code or refresh_token. Access tokens last an hour and work on /mcp only, not REST. Refresh tokens rotate: each works once, and a used one coming back revokes the connection. POST /oauth/revoke ends the connection.
- Your user sees connected apps under API keys in the dashboard and can revoke any of them at once.
Source: docs/REFERENCE.md in the repo, rendered at build time.