Skip to main content
The computer suite has three members. The sandbox is a Linux micro-VM with a shell and a filesystem; the browser is a managed remote browser opened beside it; a mobile device is a cloud phone: a screen, touch input and an app lifecycle. It is its own resource: it needs no sandbox, and nothing about it is a shell.

Android or iPhone

What you get

  • A cloud phone, usually ready in under a minute (a few minutes with apps at create; an iPhone up to about three), placed in the us, eu or as jurisdiction you ask for. POST waits up to about 45 seconds and answers with whatever is true then, usually creating; poll GET until it is ready.
  • A local network: the phone runs in the US, Germany or Singapore, and its traffic exits through a residential IP in that country, with GPS, timezone, locale and carrier matched to it — so apps see a phone that is where it says it is.
  • Nine actions: screenshot, element_tree, tap (by coordinates or by an element’s text, id or accessibility label), type, press_key, scroll, open_url, launch_app (an installed app by package name, such as com.android.settings), install_app. press_key names are Android’s; an iPhone has no BACK or RECENTS, so navigate it with taps and HOME. Most iPhones publish no element tree, so element_tree and a tap by selector are 400 there: tap by coordinates from the screenshot. On an iPhone, open_url is 400 (“this device cannot open url”) and launch_app is for Android phones (on an iPhone it can wait 30 s and answer 409): open links and apps by tapping. An iPhone can show a landscape StandBy screen, at boot and again 15–45 s after you go HOME; a tap does not leave it. The platform opens Settings to leave it when the phone becomes ready and whenever a screenshot finds it, so that screenshot shows Settings in portrait. A tap made from an older screenshot can land on StandBy instead: take a fresh screenshot first.
  • A realtime view of the screen in the dashboard, beside the controls, started on demand.
  • Apps from the platform’s app catalogue: many, not all, store apps (Spotify, WhatsApp, Instagram, TikTok and Firefox install; Wikipedia and DuckDuckGo on Android are not offered). There is no list of the catalogue: an app it lacks fails in a second or two, 404 at create and 400 from install_app, so try one with install_app on a running phone. No upload and no store account: named at create (apps) or installed on the running phone with install_app — a package name on Android (com.spotify.music), an App Store bundle id on iOS (com.burbn.instagram). iPhones carry fewer apps than Android phones.

How it ends — timers, not pause

There is no pause. A device lives until you delete it or one of two timers fires, both set at create: The platform checks every running device once a minute, so a device ends within a minute of its timer. GET /v1/mobile_devices/{id} also reconciles: it asks the provider and rewrites the stored status when they disagree, filling terminated_at and termination_reason (requested, idle_timeout, max_duration, or unknown when the provider ended it). A fifth reason, unfunded, is the platform stopping a device whose organization can no longer pay for it; see Limits and billing. The list reads stored rows and can lag until a device is opened.

Drive it

A screenshot is a JPEG at half the screen’s resolution on Android (540 × 1200 on a typical phone) and full resolution on an iPhone (393 wide), and its pixels map 1:1 to tap coordinates, which is what the dashboard’s click-to-tap uses. element_tree lists the named elements on the screen with their bounds in the same pixels, so a tap can name an element instead of a point. An action answers with words; take a screenshot to see its result. install_app waits up to about a minute and answers installed, failed or installing — a large app still going; call it again with the same app to check.

Agents

An agent uses a phone through the built-in mobile tool, on the pi harness only; the other harnesses have no mobile tool. The first call opens a phone for the session, the model sees each screenshot, and the phone shows up in the chat’s Computer panel and on the Mobile page (Computers → Mobile) while the agent works, so you can watch it live. The tool asks for approval by default; approve it for the session once and the agent carries on.
  • An agent’s phone takes the tool’s config: platform (ios for an iPhone), the same timers, except max_duration_minutes is 1–60 and defaults to 60. The tool waits out an iPhone’s longer boot.
  • open_url is not bound by the browser’s allowed_domains: a phone opens any URL or deep link. For an agent whose web reach you narrowed, keep the tool on ask or set it to deny.

Live view

The device page’s screen panel has two modes. Screenshot is a picture you click to tap. Live swaps the picture for a realtime stream of the screen, in the same place and at the same size, so the controls beside it stay where they are; Screenshot switches back and drops the stream. The credential behind the stream is a bearer credential — anyone holding it sees and drives the device — so it is held on that screen only, never stored, never logged, never returned inside another object, and withheld from the agent-facing tool catalogue. Each mint is written to the audit log as mobile_device.live_view_opened, without the credential. In Screenshot mode the page takes a new screenshot after each action, and again when you switch back from Live (the stream can drive the phone too). Taps in Live go straight to the phone, so while it plays the page also takes a screenshot every 30 seconds: that keeps the idle timer from ending a phone you are using. Live is offered once the device is ready; asked for while it is still starting, it answers 409 computer_unavailable.

Limits and billing

  • One person or script should drive a device at a time; actions on one device run one after another.
  • Apps: up to 10 at create, and any number on a running phone with install_app, all from the platform’s app catalogue, which carries many but not all store apps (there is no upload route and no catalogue listing).
  • Capacity: no per-organization limit on live devices. A create is refused with 429 rate_limited only when every phone slot on the platform is in use; try again shortly.
  • Cost: 250 credits per Android phone-minute (15,000 credits an hour) and 400 credits per iPhone-minute (24,000 credits an hour), each including the phone’s residential network, from create to end, rounded up to whole minutes with a one-minute minimum. It is one mobile line on the ledger, booked once when the device ends. Actions, app installs included, are free beyond the minutes they run in, and a device that fails to provision bills nothing (one still not ready 10 minutes after its create is ended failed); one that ran and then hit an error is ended and billed for the minutes it ran. The device page shows the rate and the cost so far. See Pricing.
  • Money: a create is admitted when the balance covers 10 minutes for every live device and the new one, each at its rate (2,500 credits for one Android phone, 4,000 for one iPhone; an agent’s phone included), plus what the live ones have run so far; otherwise it is 402 insufficient_credits, naming the amount needed. Once a minute the platform checks every running device. If the organization’s plan has lapsed, or its balance no longer covers what its running devices have accrued, it ends them with termination_reason: "unfunded" and bills the minutes they ran. A plan that is past_due keeps its devices through the payment grace period.
  • Phone minutes bill the organization’s balance directly, including a phone an agent opens. They are not held against a session’s or an agent’s budget cap; the timers and the funded-balance check above are what bound them.

Reference