Cloud Quickstart - Mobilerun

This guide takes you from zero to a completed cloud task. You will find a ready device, submit an autonomous goal, wait for it to finish, and read the result. You can do this in TypeScript, in Python, or with plain cURL. Everything here uses the Mobilerun Cloud, which gives you hosted devices and a managed agent. There is no local install, no adb, and no Portal APK. If you would rather run the open source package on your own machine, follow the Framework Quickstart instead.

Prerequisites

A Mobilerun account. You can sign up at cloud.mobilerun.ai.
A cloud API key that starts with dr_sk_ from the API Keys page. This is the only credential you need, because the agent’s LLM usage is billed from your credit balance and you do not need your own model key.
A ready device. You can connect your own phone with the Portal app, or provision a Cloud Phone or a Physical Phone in the dashboard.

Autonomous tasks consume credits at roughly 0.5 credits per agent step. New accounts and device subscriptions include a monthly credit allowance.

1. Set your API key

The examples below read your key from the MOBILERUN_API_KEY environment variable.

export MOBILERUN_API_KEY=dr_sk_your_key_here

If you call new Mobilerun() without an apiKey, the TypeScript SDK auto-detects the MOBILERUN_CLOUD_API_KEY variable instead. The examples pass the key explicitly, so either name works.

The TypeScript example uses top level await, so run it as an ES module. Set "type": "module" in your package.json or use a .mts file, and then run it with npx tsx quickstart.ts.

2. Install

npm install @mobilerun/sdk

# The Python example below uses only the standard requests library
pip install requests

3. Run your first task

Each example does the same four things. It lists a ready device, submits a task, polls until the task finishes, and prints the result.

import Mobilerun from '@mobilerun/sdk';

// Pass your dr_sk_ key explicitly (or set MOBILERUN_CLOUD_API_KEY and call new Mobilerun())
const client = new Mobilerun({ apiKey: process.env.MOBILERUN_API_KEY });

// 1. Find a device that's ready to accept tasks
const devices = await client.devices.list({ state: ['ready'] });
const device = devices.items[0];
if (!device) throw new Error('No ready device. Connect one in the dashboard first.');

// 2. Submit an autonomous task
const task = await client.tasks.run({
  deviceId: device.id,
  task: 'Open Settings and tell me the Android version',
  llmModel: 'mobilerun/mobile-agent-fast',
  maxSteps: 50,
});
console.log('Task started:', task.id);

// 3. Wait for it to finish
let status = await client.tasks.getStatus(task.id);
while (!['completed', 'failed', 'cancelled'].includes(status.status)) {
  await new Promise((r) => setTimeout(r, 3000));
  status = await client.tasks.getStatus(task.id);
}
console.log('Final status:', status.status);

// 4. Read the result from the trajectory
const { trajectory } = await client.tasks.getTrajectory(task.id);
const result = trajectory.find((e) => e.event === 'ResultEvent');
console.log('Result:', result?.data);

import os, time, requests

API = "https://api.mobilerun.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['MOBILERUN_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Find a device that's ready to accept tasks
devices = requests.get(f"{API}/devices", headers=HEADERS, params={"state": "ready"}).json()
device_id = devices["items"][0]["id"]

# 2. Submit an autonomous task
task = requests.post(
    f"{API}/tasks",
    headers=HEADERS,
    json={
        "deviceId": device_id,
        "task": "Open Settings and tell me the Android version",
        "llmModel": "mobilerun/mobile-agent-fast",
        "maxSteps": 50,
    },
).json()
task_id = task["id"]
print("Task started:", task_id)

# 3. Poll until the task finishes
while True:
    status = requests.get(f"{API}/tasks/{task_id}/status", headers=HEADERS).json()
    if status["status"] in ("completed", "failed", "cancelled"):
        break
    time.sleep(3)
print("Final status:", status["status"])

# 4. Read the result from the trajectory
trajectory = requests.get(f"{API}/tasks/{task_id}/trajectory", headers=HEADERS).json()["trajectory"]
result = next((e for e in trajectory if e["event"] == "ResultEvent"), None)
print("Result:", result["data"] if result else None)

# 1. Find a ready device and grab its id
curl -s https://api.mobilerun.ai/v1/devices \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" | jq '.items[0].id'

# 2. Submit a task (use the device id from step 1)
curl -s -X POST https://api.mobilerun.ai/v1/tasks \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "<DEVICE_ID>",
    "task": "Open Settings and tell me the Android version",
    "llmModel": "mobilerun/mobile-agent-fast",
    "maxSteps": 50
  }'

# 3. Check status (use the task id returned in step 2)
curl -s https://api.mobilerun.ai/v1/tasks/<TASK_ID>/status \
  -H "Authorization: Bearer $MOBILERUN_API_KEY"

# 4. Once status is "completed", read the result from the trajectory
curl -s https://api.mobilerun.ai/v1/tasks/<TASK_ID>/trajectory \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  | jq '.trajectory[] | select(.event == "ResultEvent") | .data'

The trajectory is returned as { "trajectory": [ ... ] }, which is an array of events. The final result is the event whose event field equals "ResultEvent", and its data holds the fields success, message, structured_output, and steps. For data extraction tasks you can pass an outputSchema in JSON Schema form when you create the task, and then structured_output is populated with data matching it. See Agent configuration for more.

Read the result without the trajectory

The trajectory is the full step by step record, which is useful when you want to inspect every screenshot and action. For most tasks you do not need it, because the status endpoint already returns the answer. A GET /tasks/{id}/status call returns the task outcome directly.

{
  "status": "completed",
  "succeeded": true,
  "message": "The Android version on your device is 15.",
  "output": null,
  "steps": 5
}

The message field holds the agent’s natural language answer. The output field holds your structured data when you submitted an outputSchema, and it is null otherwise. Because the polling loop in step 3 already calls this endpoint, you can read message and output straight from the final poll and skip the trajectory call entirely.

Use the status endpoint for the answer and for polling. Reach for the trajectory only when you need the detailed run, such as the screenshots, the manager plan, or each executor action.

Choosing a model

Pass llmModel to pick the model that drives the agent. Use one of the identifiers from the cloud model catalog. For example, mobilerun/mobile-agent-fast is tuned for speed and cost, while mobilerun/mobile-agent-thinking gives stronger reasoning for complex flows. Omit the field to use your account default.

Next steps

Agent configuration

All task parameters, including models, vision, reasoning, stealth, memory, and structured output.

API Reference

Full REST schemas for every endpoint, with request and response examples.

MCP Server

Drive Mobilerun from Cursor, Claude Desktop, and other MCP clients.

Webhooks

Get notified when tasks change state instead of polling.

​Prerequisites

​1. Set your API key

​2. Install

​3. Run your first task

​Read the result without the trajectory

​Choosing a model

​Next steps

Agent configuration

API Reference

MCP Server

Webhooks

Prerequisites

1. Set your API key

2. Install

3. Run your first task

Read the result without the trajectory

Choosing a model

Next steps