Skip to main content

orion-phone

Give your agent its own phone.

Open source (MIT) · MCP server and CLI · Claude Code, Codex, or any MCP client · Linux and WSL2.

The problem

Agents that share one desktop browser collide when two of them want it at once, and they cannot use apps that exist only on phones. Handing an agent your own phone is worse: everything on it is then within reach.

orion-phone runs Android phones (emulators) that AI agents drive through an MCP server or a CLI. An agent leases a phone, reads its screen as text, taps, types and opens apps, and every action leaves an audit record with a screenshot. The phones are signed in to the accounts you choose, and a phone in the locked tier does nothing until you unlock it yourself.

Quickstart

Linux with systemd user services and KVM, or Windows through WSL2. Python 3.11+, Java 17+, and Google’s Android command-line tools; setup downloads the rest.

Install and set up (Read and accept the Android SDK License yourself before setup):

uv tool install 'orion-phone==0.2.0'
orion-phone init      # the example config: phone a open, phone b locked
orion-phone setup     # SDK packages, phones, systemd user units
orion-phone status a  # exits 0 once the first boot finishes

Command surface

  • lease: Take a phone for one agent session. A second agent gets BUSY with the holder’s name and expiry instead of stepping on the first.
  • ui: Read the screen as text: its elements, with the center to tap for each.
  • shot: Take a screenshot of the phone.
  • tap · type · swipe · key · open: Act on the phone. Every holder action writes an audit line, and each successful one a screenshot.
  • release: Give the phone back. A locked phone shuts down when its session is released.
  • status: Report each phone healthy only with proof: boot completed and a fresh screenshot that is not blank.
  • init · setup · install-units: Write the example config, then install the SDK packages, the phones and their systemd user units.

Why it is different

  • A locked tier that waits for unlock: A locked phone cold-boots for each session. The tool permits holder actions only after observing a secure lock screen and then an unlock. It shuts down on release, lease expiry, or the session cap. Use it on a trusted host: these checks govern cooperative tool callers, not local adb or host access, and they do not identify who supplied the credential. Independent verification of credential-encrypted storage remains open as Q2; see the security model.
  • One agent per phone: An agent leases a phone before it acts. Two agents never drive the same phone at once: the second gets BUSY, with the holder and the expiry, and can wait or take another phone.
  • A record of everything: Each holder action writes an audit line, and each successful one a screenshot, to a private state directory outside any repository.
  • Measured, every run listed: In six measured runs with Claude Code on Claude Opus 5.5, reading two facts in Settings cost $0.20 to $0.38 a run, and creating, checking and deleting an alarm in Clock $0.33 to $0.46. The README lists every run and the method.

Links