Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

KnifeLemon/Droidline

AI Engineering

Automate and test real Android phones from Python, Node.js, C#, CLI, HTTP or Appium without ADB, USB or root.

547
58
Go
MIT
42 days old

What it does

Droidline drives physical Android phones from code. A Go server runs on your PC, and a companion Android app on the phone connects out to it, so no ADB, USB debugging or root is required. Commands are described once in spec/commands.json and generated into consistent APIs for Python, Node.js/TypeScript, C#, the CLI, HTTP and MCP tools, so touch, input and dump mean the same thing in every language.

It targets developers testing their own apps across app boundaries, people running a shelf of phones through repeated routines, and AI agents that need to see a screen and act on it. Elements are selected by text, id or desc rather than pixels; touch, input and wait wait for their element by default, while exists, checked and which answer immediately. One PC can command many phones: commands to one phone run in order, and different phones run in parallel.

Quick start

You need a Windows, macOS or Linux PC and an Android 9+ phone, both on the same Wi-Fi for the first run. The installation guide has step-by-step screenshots.

  1. Download the server archive for your system from Releases, put droidline on your PATH, and start it:

    droidline serve
    
  2. Install droidline-agent.apk from the same release page. In the app's Setup tab, enable the accessibility service, the Droidline keyboard, notifications and unrestricted battery use. On Android 13+, allow restricted settings first.

  3. Pair the phone. On the PC run:

    droidline pair
    

    Scan the QR code with the app's Pair tab, or choose Pair on this Wi-Fi and enter the 6-digit code: droidline pair 482913.

  4. Send commands:

    droidline launch com.android.settings
    droidline touch text "Network & internet"
    

If you have no phone, droidline-fakephone ships with every release and simulates a device with a demo app; the first-script tutorial builds a login script against it. From Python (pip install droidline, Python 3.9+), the same server is used:

from droidline import connect

d = connect()
d.launch("dev.droidline.demo")
if d.exists("text", "Close ad"):
    d.touch("text", "Close ad")
d.input("id", "email", "knife")
d.touch("text", "Log in")
print(d.get_text("id", "greeting"))

Remote phones and agent access

Because the phone always opens the connection, it needs no inbound port. The same Wi-Fi route uses a UDP broadcast; other options are one forwarded TLS port, a cloudflared/ngrok tunnel, or a relay you deploy on Cloudflare Workers or a VPS. Past the handshake, traffic uses P-256 key agreement and AES-256-GCM, so a tunnel or relay carries only ciphertext. The remote connection guides cover each route.

For AI agents, droidline mcp exposes the phone over MCP and is listed in the MCP Registry as io.github.KnifeLemon/droidline. Agents can be restricted with --tools dump,screenshot,touch or --read-only. Optional tools include an inspector/recorder, a WebDriver bridge for Appium clients, a pytest plugin, phone leases and image/text matching.

Constraints

Droidline relies only on permissions an ordinary app can obtain, which limits it to exported screens, so it cannot open another app's private screens, unlock PIN/pattern/password locks, or force-stop and clear app data with a single command (Settings-based recipes press buttons and may need label adjustments). Games and custom-drawn UIs expose no elements, so coordinate taps and pixel color checks are needed there. Android 15+ hides one-time codes in notifications. Per-app proxying uses a local VPN and one upstream per phone without root. The project is at version 0.1: server, CLI, MCP adapter, relay and SDKs are tested against the phone simulator, and the app has been run on an Android 13 emulator; testing across phone brands is still pending, and STATUS.md lists what has been verified. The license is MIT. Use it only on phones and accounts you own or are permitted to automate.

HotRepo's take

The repository has 547 stars and 58 forks, but no HotRepo daily ranking, snapshot or Hacker News discussion records are available, so this page cannot attest to trending behavior. What the material does show is a concrete, spec-generated multi-language stack: the Go server, Kotlin app, Python/Node.js/C# SDKs and relay are all present, with CI and an integration path that runs the server, simulated phone and SDK demos together. The 0.1 status and the reliance on a simulated phone mean the real-world signal to watch is the cross-brand behavior of its Settings recipes rather than current popularity.

Written by AI from the project's README, updated . The project's own docs are the source of truth.

You might also like

  1. ZSeven-W/dsh-androidDeepSeek Harness plugin that streams a live Android emulator or USB device into the conversation and drives it through adb.TypeScript355
  2. kilolonion/agent-vscreenRun Android apps on an invisible virtual display so phone AI agents can operate them while you keep using your own screen.Kotlin117
  3. droidrun/mobilerunAn LLM-agnostic framework that lets AI agents inspect, tap, swipe, and type on real Android and iOS devices via CLI or Python.Python10,059
  4. phone-harness/mcpA hosted MCP server that lets AI agents control real iPhones and Android emulators in the cloud.Python812
  5. hridaya423/phonedriverMCP server and CLI that let AI agents read and control Android phones and iPhones with a confirmation step before payments.Rust150