Android automation,
one line at a time.
Test your apps, script the tasks you repeat
and run a shelf of phones
from Python, Node.js, C#,
the shell or an AI agent.
No ADB, no USB cable, no root.
Install
- Python
pip install droidline- Node.js
npm install droidline- .NET
dotnet add package Droidline- Android app
- droidline-agent.apk
- Nothing sent yet. Send the first line, or run the whole script.
d.launch("dev.droidline.demo")Simulated in your browser with the same demo app that droidline-fakephone runs. Requests and replies use the real line format.
The phone dials out.
Your code stays on localhost.
droidline serve runs on your PC. The Droidline app on the phone connects to it, so the phone opens no port and never needs adb forward. Your code sends one JSON line to localhost:8780 and reads one line back.
- Encrypted end to end
- P-256 key exchange and AES-256-GCM on every line after the handshake.
- Waiting happens on the phone
- touch waits up to 10 seconds for its target and falls back to a coordinate tap by itself.
- Three permissions, no root
- An accessibility service, a keyboard and an optional per-app VPN. Nothing needs Shizuku or adb.
Most commands answer
in tens of milliseconds.
The app on the phone already holds the screen through Android's accessibility service, so nothing is dumped to a file and read back first. We timed the same actions on the same Settings screen of two phones with Droidline, with adb and uiautomator, and with Appium's UiAutomator2 driver, ten runs each. Each bar fills at real speed and stops at its median.
Read the screen tree
Find by text
Find and tap
Screenshot
Read the screen tree
Find by text
Find and tap
Screenshot
Median of ten runs, measured on 2026-10-09 on the Settings home screen in Korean. Droidline's link ran through adb reverse on the same connection, so all three shared one transport. Screenshots take about as long with all three. Appium 3.8.0 with UiAutomator2 driver 8.7.0. Scripts and raw results
Not in the bars: an Appium session took 4.3 to 5.9 seconds to start, and connecting with the Droidline SDK and finding the first element took 22 to 42 milliseconds.
Pick the element,
not the pixel.
dump() returns the screen as a tree. Every element has text, id and desc. Pass the field and the value, and touch waits for the element, taps it, and taps the center of its bounds if the element refuses the click.
Choose an element on the phone
This element in dump()
Select an element to see its fields.Select an element to see its fields.One name
in every language.
touch is touch in the SDKs, on the wire, in the CLI and as an MCP tool. They are all generated from one file, commands.json, so a new command reaches every language at once.
pip install droidline
from droidline import connect
d = connect()
d.touch("text", "Log in")npm install droidline
import { connect } from "droidline";
const d = await connect();
await d.touch("text", "Log in");dotnet add package Droidline
using Droidline;
await using var d = await DroidlineClient.ConnectAsync();
await d.TouchAsync("text", "Log in");droidline touch text "Log in"curl -X POST localhost:8780/devices/_/touch \
-H 'content-type: application/json' \
-d '{"by":"text","value":"Log in"}'{"id":1,"cmd":"touch","by":"text","value":"Log in"}Open a TCP socket to localhost:8780, write one JSON line, read one line back.
Read the guide: Any language{
"mcpServers": {
"droidline": { "command": "droidline", "args": ["mcp"] }
}
}Add this to your MCP client. Claude, ChatGPT, Cursor and other agents get every command as a tool, with dump as their eyes.
Read the guide: MCPTools you turn on
when you need them.
None of these runs until you start it, and each one uses the same server and the same commands as your scripts.
droidline inspectClick an element on a screenshot to get its selector and code, or use the phone while it writes the script.
Inspector and recorderdroidline webdriverPoint Appium clients and existing Appium scripts at your phones, without ADB or an Appium server.
Appium and WebDriverpytest -p droidline.pytest_pluginA phone fixture, and for each failed test the commands it sent, a screenshot and the screen tree.
Test frameworkslease()Borrow a free phone so two scripts never act on the same one, and give it back when done.
Share phones between scriptstap_image("play.png")Find a picture or a word on screens without elements, such as games, with template matching or OCR.
Pictures and OCR
Built for
a shelf of phones.
One PC runs many phones. Commands to one phone run in order, and different phones run in parallel.
shelf-01 online lan
Same Wi-Fi: The phone finds the PC with a UDP broadcast and connects directly.
d = dl.device("shelf-01")
d.launch("com.android.chrome")- Names, not serial numbersName a phone once (shelf-01) and address it by that name from every interface.
- A proxy per appSend chosen apps through socks5 or http over a local VPN, one upstream per phone.
- Notifications as eventsWait for one with wait_notification, or receive them all through a signed webhook.
- Nothing runs twiceA phone that drops off mobile data resumes where it left off; a command in flight is never repeated.
Off your Wi-Fi, too.
Phones on mobile data sit behind the carrier's NAT and cannot accept connections, so the phone always connects out. Pick the route that fits your network; the phone tries them in order and switches back to Wi-Fi when it can.
Past the handshake every line is encrypted end to end. A tunnel or relay only carries ciphertext. Remote connection guides
What Droidline
cannot do.
It only uses permissions an ordinary app can get. That rules some things out, and it is better to know before you start.
Full list of limits- Open another app's screens that the app does not export. launch falls back to the start screen.
- Unlock a PIN, pattern or password lock screen.
- Read one-time codes from notifications on Android 15 and later: you learn that a code arrived, then read it in the app.
- Tap elements that games and some custom UIs never expose. Use tap with coordinates and color(x, y) there.
- Force stop apps, clear their data or switch the network with a single command. Settings differs by phone, so these are recipes that press its buttons.
How it differs from ADB tools
and on-phone scripts.
| Droidline | ADB-based toolsuiautomator2 3.x, Appium UiAutomator2 | On-phone scriptsAuto.js, AutoX.js | |
|---|---|---|---|
| Needs ADB | No | Yes | No |
| Where your code runs | Your PC | Your PC | The phone |
| Language | Any, through SDKs, HTTP, a socket or Appium clients | The tool's client libraries | JavaScript |
| Better at | Many phones over Wi-Fi or mobile data, no cable | Installing apps, adb shell, instrumentation, non-exported screens | Running with no PC at all |
Sources: uiautomator2, Appium UiAutomator2 driver, AutoX.js
Questions people
ask first.
Do I need ADB at any point?
No. You install the app from an APK file, turn on its permissions in the phone's settings, and pair it with a QR code or a 6-digit code. On Android 13 and later you also allow restricted settings for the app once, which the app walks you through.
Does it work when the phone is on mobile data?
Yes. The phone always connects out, so it works behind a carrier's NAT. Use a forwarded port, a tunnel such as Cloudflare Tunnel, or a relay you deploy to Cloudflare Workers or a VPS. Nobody runs a public relay for you.
Can the relay or tunnel see my screen or my commands?
No. After the two-line handshake every line is encrypted with AES-256-GCM using keys only your PC and your phone hold. The relay sees device IDs, sizes and timing.
Which Android versions are supported?
Android 9 (API 28) and later. A few features need newer versions: the per-app proxy needs Android 10, and the accessibility screenshot needs Android 11 (older versions ask once for screen capture permission).
Is the app on Google Play?
No. Signed APKs are published on GitHub Releases, and the app tells you when a new version is out.
Does it need root or Shizuku?
No. Everything runs on the accessibility service, the Droidline keyboard and Android's VPN API, which any app can use with your permission.
Can an AI agent use it?
Yes. droidline mcp exposes every command as an MCP tool. The agent calls dump to see the screen and touch, input or scroll_to to act on it.
Can I keep my Appium scripts?
Mostly. droidline webdriver speaks the WebDriver protocol Appium clients use, with XPath, UiSelector, ids and accessibility ids. Anything that needs ADB, such as installing apps or adb shell, is not there.
What happens if the PC restarts while a command is running?
The phone keeps unacknowledged replies and resends them when it reconnects. A command that was in flight is not run twice; if the phone app itself restarted, the call fails with AGENT_RESTARTED so you can decide.
Pair your
first phone.
- Run the server on your PC
droidline serve - Install the app and pair
droidline pair - Send a command
droidline touch text "OK"