Droidline documentation
What Droidline is, how its three parts fit together, what you need before you start, and which page to read next.
Droidline lets a program on your computer use an Android phone the way a person would: open apps, tap buttons, type text, scroll, read what is on the screen and take screenshots. You write one line per action, such as d.touch("text", "Log in"), in Python, Node.js, the shell, plain HTTP or any language that can open a network connection.
It needs no ADB, no USB cable and no root. The phone only needs the Droidline app and a few permissions you turn on once.
What people use it for
- Testing your own app on real phones, including flows that cross into other apps, such as a login with a code from a text message.
- A shelf of phones running the same routine every day, each through its own network or proxy.
- Giving an AI agent hands: through MCP, Claude, Cursor and other agents can look at a phone screen and act on it.
- Small personal automations, such as turning Wi-Fi off at night or collecting a value from an app every hour.
Droidline uses only permissions an ordinary app can get, so a few things are out of reach. Read Limitations before you plan a big project.
How it works
Droidline has three parts. You install the first two once; the third is whatever you write.
| Part | Where it runs | What it does |
|---|---|---|
droidline serve | your PC (Windows, macOS or Linux) | A small server that keeps an encrypted connection to every paired phone and takes commands from your code on localhost:8780. |
| The Droidline app | each Android phone (Android 9 or later) | Connects to the server and carries out commands with Android's accessibility service, its own keyboard and, if you want, a per-app VPN. |
| Your code | your PC | A Python or Node.js script, a droidline command in the shell, an AI agent over MCP, curl, or a raw socket from any language. |
A command travels like this:
your script ──one JSON line──▶ droidline serve ──encrypted──▶ phone
your script ◀──one JSON line── droidline serve ◀──encrypted── phoneThe phone always opens the connection to the PC, never the other way round. That is why the phone needs no open port, and why the same setup also works when the phone is on mobile data, through a tunnel or a relay you run yourself.
What you need
- A PC that stays on while your scripts run. Windows 10 or 11, macOS or Linux, 64-bit (x86 or ARM).
- An Android phone with Android 9 or later. It does not need to be rooted, and it does not need developer options.
- For this first setup, the PC and the phone on the same Wi-Fi network. Other networks are covered in Remote phones.
- Python 3.9 or later, or Node.js 18 or later, if you want to write scripts in those languages. The command line works without either.
No phone at hand yet? droidline-fakephone simulates one on your PC, and Your first script uses it from start to finish.
Where to go next
| If you want to | Read |
|---|---|
| Set everything up step by step | Installation |
| Send a first command as fast as possible | Quick start |
| Write a real script, with each line explained, without a phone | Your first script |
| Understand selectors, waiting and errors | Concepts |
| Use your language | Python, Node.js, CLI, HTTP, other languages, AI agents |
| Find the right element on a screen | Finding elements |
| Copy a working pattern | Recipes |
| Look up a command | Command reference |
| Fix something that does not work | Troubleshooting |
Words you have not met before, such as selector, dump or pairing, are explained in the Glossary.
Status
Droidline is at version 0.1. The server, CLI, MCP adapter, relay and SDKs pass their tests against the phone simulator, and the Android app has been tested on an Android 13 emulator. Reports from real phones, especially for the settings shortcuts on different brands, are the next step. The verification record lists exactly what has been checked.