mobilebox (Python)

Python client for Mobilebox: cloud Android phones your agent drives over REST. Create a phone, read the screen as numbered elements, tap and type, install apps, delete the phone. Standard library only, Python 3.10+, typed.

pip install mobilebox
export MOBILESANDBOX_API_KEY=...   # from https://mobilebox.dev/dashboard; never in a prompt or a commit

from mobilebox import Mobilebox

mb = Mobilebox()
phone = mb.create_phone(name="settings-check", idle_timeout=120, max_duration=300)
try:
    result = mb.act(phone.id, [
        {"type": "open_app", "package": "com.android.settings"},
        {"type": "scroll_to", "text": "Display"},
        {"type": "tap", "target": {"text": "Display"}},
        {"type": "wait_for", "text": "Brightness level"},
    ])
    if not result.ok:
        raise result.error            # has .code and .next: what to do instead
    print(result.screen.find("Brightness level").summary)
finally:
    mb.delete_phone(phone.id)         # always clean up; park_phone() keeps apps and logins

create_phone returns once the phone is ready (about 18 s). A new account has $2 of credit; a cloud phone costs $0.01 per minute while ready, parked phones are free.

Methods

Actions and targets: {"type": "tap", "target": {"text": "Sign in"}}, {"type": "type", "text": "hello"}, scroll_to, wait_for, back, home, open_app and more in the API reference.

Errors

Every failure raises MobileboxError with code, message, next (what to do instead), 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. Continue from result.screen, don't replay the batch.
• create_phone sends an Idempotency-Key (a UUID unless you pass one) and retries retryable errors with it, so a lost response never makes a second phone. Pass your own key to retry across processes.
• phone_limit (429) and box_full (503) are not retried: park or delete the phone next names, or wait retry_after seconds.

Configuration

For agent frameworks: langchain-mobilebox wraps this client as LangChain tools. Any MCP client can use https://mobilebox.dev/mcp directly (setup).

Development

pip install -e . pytest
pytest                                      # offline, against a local stub
MOBILEBOX_LIVE=1 MOBILESANDBOX_API_KEY=... pytest -m live   # one real phone, deleted at the end (about $0.01)

MIT © fifteenA, Inc.