Mobilerun
Mobilerun is an open-source (MIT) framework for controlling Android and iOS devices through LLM agents.
It enables mobile automation using natural language commands.
Architecture
Mobilerun uses a multi-agent architecture coordinated by MobileAgent:
- Reasoning mode (
reasoning=True): Manager plans → Executor acts → loop until done
- Direct mode (
reasoning=False): CodeActAgent generates and executes Python code directly
Key agents: ManagerAgent (planning), ExecutorAgent (actions), CodeActAgent (direct execution),
ScripterAgent (off-device computation), StructuredOutputAgent (typed data extraction).
Atomic actions available to agents: click, long_press, type, system_button, swipe,
open_app, get_state, take_screenshot, complete.
Repository Structure
Source code is at mobilerun/ (Python package). Key locations:
| Path |
Description |
mobilerun/agent/droid/ |
MobileAgent orchestrator |
mobilerun/agent/codeact/ |
CodeActAgent (direct mode) |
mobilerun/agent/scripter/ |
ScripterAgent (off-device scripts) |
mobilerun/agent/oneflows/ |
StructuredOutputAgent |
mobilerun/agent/utils/ |
Tools, executor, tracing, async utils |
mobilerun/tools/ |
Device tools (ADB, iOS, portal client) |
mobilerun/cli/ |
CLI entry point (click-based) |
mobilerun/config/prompts/ |
Jinja2 prompt templates per agent |
mobilerun/config/app_cards/ |
App-specific instruction cards |
mobilerun/credential_manager/ |
YAML-based credential storage |
mobilerun/telemetry/ |
Phoenix tracing integration |
Documentation
Read the relevant file(s) from docs/v5/ based on the user's question. Do not guess — always
read the doc before answering.
| Topic |
File |
| Overview |
docs/v5/overview.mdx |
| Quickstart |
docs/v5/quickstart.mdx |
| Concepts |
|
| Architecture & agents |
docs/v5/concepts/architecture.mdx |
| Events & workflows |
docs/v5/concepts/events-and-workflows.mdx |
| Prompts |
docs/v5/concepts/prompts.mdx |
| Scripter agent |
docs/v5/concepts/scripter-agent.mdx |
| Shared state |
docs/v5/concepts/shared-state.mdx |
| Features |
|
| App cards |
docs/v5/features/app-cards.mdx |
| Credentials |
docs/v5/features/credentials.mdx |
| Custom tools |
docs/v5/features/custom-tools.mdx |
| Custom variables |
docs/v5/features/custom-variables.mdx |
| Structured output |
docs/v5/features/structured-output.mdx |
| Telemetry |
docs/v5/features/telemetry.mdx |
| Tracing |
docs/v5/features/tracing.mdx |
| Guides |
|
| CLI usage |
docs/v5/guides/cli.mdx |
| Device setup |
docs/v5/guides/device-setup.mdx |
| Docker |
docs/v5/guides/docker.mdx |
| Migration v3→v4 |
docs/v5/guides/migration-v3-to-v4.mdx |
| SDK |
|
| MobileAgent |
docs/v5/sdk/droid-agent.mdx |
| ADB tools |
docs/v5/sdk/adb-tools.mdx |
| iOS tools |
docs/v5/sdk/ios-tools.mdx |
| Base tools |
docs/v5/sdk/base-tools.mdx |
| Configuration |
docs/v5/sdk/configuration.mdx |
| API reference |
docs/v5/sdk/reference.mdx |
For deeper implementation details, check the source code directly in mobilerun/.
1---2name: mobilerun-docs3description: Mobilerun documentation reference. Use when users ask about Mobilerun setup, configuration, SDK usage, CLI commands, device setup, agents, architecture, app cards, credentials, tracing, Docker, migration, structured output, or any Mobilerun "how do I..." questions.4---56# Mobilerun78Mobilerun is an open-source (MIT) framework for controlling Android and iOS devices through LLM agents.9It enables mobile automation using natural language commands.1011- **GitHub**: https://github.com/droidrun/mobilerun12- **Docs site**: https://docs.mobilerun.ai13- **License**: MIT14- **Install**: `uv tool install mobilerun` (Google Gemini, OpenAI, DeepSeek, Ollama, OpenRouter included by default)15- **Optional extras**: `anthropic`, `langfuse`16- **Requires**: Python 3.11+, ADB, Portal APK on device1718## Architecture1920Mobilerun uses a multi-agent architecture coordinated by `MobileAgent`:2122- **Reasoning mode** (`reasoning=True`): Manager plans → Executor acts → loop until done23- **Direct mode** (`reasoning=False`): CodeActAgent generates and executes Python code directly2425Key agents: ManagerAgent (planning), ExecutorAgent (actions), CodeActAgent (direct execution),26ScripterAgent (off-device computation), StructuredOutputAgent (typed data extraction).2728Atomic actions available to agents: `click`, `long_press`, `type`, `system_button`, `swipe`,29`open_app`, `get_state`, `take_screenshot`, `complete`.3031## Repository Structure3233Source code is at `mobilerun/` (Python package). Key locations:3435| Path | Description |36|------|-------------|37| `mobilerun/agent/droid/` | MobileAgent orchestrator |38| `mobilerun/agent/codeact/` | CodeActAgent (direct mode) |39| `mobilerun/agent/scripter/` | ScripterAgent (off-device scripts) |40| `mobilerun/agent/oneflows/` | StructuredOutputAgent |41| `mobilerun/agent/utils/` | Tools, executor, tracing, async utils |42| `mobilerun/tools/` | Device tools (ADB, iOS, portal client) |43| `mobilerun/cli/` | CLI entry point (click-based) |44| `mobilerun/config/prompts/` | Jinja2 prompt templates per agent |45| `mobilerun/config/app_cards/` | App-specific instruction cards |46| `mobilerun/credential_manager/` | YAML-based credential storage |47| `mobilerun/telemetry/` | Phoenix tracing integration |4849## Documentation5051Read the relevant file(s) from `docs/v5/` based on the user's question. Do not guess — always52read the doc before answering.5354| Topic | File |55|-------|------|56| Overview | docs/v5/overview.mdx |57| Quickstart | docs/v5/quickstart.mdx |58| **Concepts** | |59| Architecture & agents | docs/v5/concepts/architecture.mdx |60| Events & workflows | docs/v5/concepts/events-and-workflows.mdx |61| Prompts | docs/v5/concepts/prompts.mdx |62| Scripter agent | docs/v5/concepts/scripter-agent.mdx |63| Shared state | docs/v5/concepts/shared-state.mdx |64| **Features** | |65| App cards | docs/v5/features/app-cards.mdx |66| Credentials | docs/v5/features/credentials.mdx |67| Custom tools | docs/v5/features/custom-tools.mdx |68| Custom variables | docs/v5/features/custom-variables.mdx |69| Structured output | docs/v5/features/structured-output.mdx |70| Telemetry | docs/v5/features/telemetry.mdx |71| Tracing | docs/v5/features/tracing.mdx |72| **Guides** | |73| CLI usage | docs/v5/guides/cli.mdx |74| Device setup | docs/v5/guides/device-setup.mdx |75| Docker | docs/v5/guides/docker.mdx |76| Migration v3→v4 | docs/v5/guides/migration-v3-to-v4.mdx |77| **SDK** | |78| MobileAgent | docs/v5/sdk/droid-agent.mdx |79| ADB tools | docs/v5/sdk/adb-tools.mdx |80| iOS tools | docs/v5/sdk/ios-tools.mdx |81| Base tools | docs/v5/sdk/base-tools.mdx |82| Configuration | docs/v5/sdk/configuration.mdx |83| API reference | docs/v5/sdk/reference.mdx |8485For deeper implementation details, check the source code directly in `mobilerun/`.
droidrun