Droidline 문서

Droidline을 쓰면 컴퓨터의 프로그램이 사람처럼 안드로이드 폰을 다룰 수 있습니다. 앱을 열고, 버튼을 탭하고, 텍스트를 입력하고, 스크롤하고, 화면에 있는 내용을 읽고, 스크린샷을 찍습니다. 동작 하나에 d.touch("text", "Log in")처럼 한 줄을 씁니다. Python, Node.js, 셸, 일반 HTTP는 물론 네트워크 연결을 열 수 있는 언어라면 무엇이든 됩니다.

ADB도, USB 케이블도, 루팅도 필요 없습니다. 폰에는 Droidline 앱을 설치하고 권한 몇 가지를 한 번 켜 두기만 하면 됩니다.

활용 사례

• 내 앱 테스트를 실제 폰에서 합니다. 문자 메시지로 받은 코드로 로그인하는 것처럼 다른 앱을 거치는 흐름도 포함됩니다.
• 선반 가득한 폰이 매일 같은 루틴을 실행합니다. 폰마다 자기 네트워크나 프록시를 거칩니다.
• AI 에이전트에게 손 달아 주기: MCP를 통해 Claude, Cursor 같은 에이전트가 폰 화면을 보고 조작할 수 있습니다.
• 작은 개인 자동화도 됩니다. 밤에 Wi-Fi를 끄거나 한 시간마다 앱에서 값을 하나 가져오는 식입니다.

Droidline은 일반 앱이 받을 수 있는 권한만 쓰기 때문에 할 수 없는 일이 몇 가지 있습니다. 큰 프로젝트를 계획하기 전에 제한 사항을 읽어 보세요.

동작 방식

Droidline은 세 부분으로 이루어집니다. 앞의 두 가지는 한 번만 설치하면 되고, 세 번째는 직접 작성하는 코드입니다.

구성 요소	실행 위치	하는 일
droidline serve	내 PC(Windows, macOS, Linux)	페어링된 모든 폰과 암호화된 연결을 유지하고, localhost:8780에서 내 코드가 보내는 명령을 받는 작은 서버입니다.
Droidline 앱	각 안드로이드 폰(Android 9 이상)	서버에 접속하고, 안드로이드 접근성 서비스, 자체 키보드, 원하면 앱별 VPN으로 명령을 실행합니다.
내 코드	내 PC	Python이나 Node.js 스크립트, 셸의 droidline 명령, MCP로 연결한 AI 에이전트, curl, 또는 어떤 언어에서든 여는 소켓 직접 연결.

명령은 이렇게 오갑니다.

your script ──one JSON line──▶ droidline serve ──encrypted──▶ phone
your script ◀──one JSON line── droidline serve ◀──encrypted── phone

연결은 항상 폰이 PC 쪽으로 엽니다. 반대 방향은 없습니다. 그래서 폰에 열린 포트가 필요 없고, 폰이 모바일 데이터를 쓸 때도 직접 운영하는 터널이나 릴레이를 거쳐 같은 구성 그대로 동작합니다.

준비물

• 스크립트를 실행하는 동안 켜 둘 PC. Windows 10이나 11, macOS, Linux 중 하나이고 64비트(x86 또는 ARM)여야 합니다.
• Android 9 이상인 안드로이드 폰. 루팅할 필요도, 개발자 옵션을 켤 필요도 없습니다.
• 처음 설정할 때는 같은 Wi-Fi 네트워크에 있는 PC와 폰. 다른 네트워크는 원격 연결에서 다룹니다.
• Python이나 Node.js로 스크립트를 쓰려면 Python 3.9 이상 또는 Node.js 18 이상. 명령줄은 둘 다 없어도 동작합니다.

아직 폰이 없나요? droidline-fakephone이 PC에서 폰을 흉내 냅니다. 첫 스크립트는 처음부터 끝까지 이것을 씁니다.

다음에 볼 문서

하고 싶은 일	읽을 문서
모든 것을 단계별로 설정하기	설치
최대한 빨리 첫 명령 보내기	빠른 시작
폰 없이, 한 줄씩 설명을 들으며 실제 스크립트 작성하기	첫 스크립트
선택자, 대기, 에러 이해하기	개념
내 언어로 쓰기	Python, Node.js, CLI, HTTP, 다른 언어, AI 에이전트
화면에서 알맞은 요소 찾기	요소 찾기
동작하는 패턴 가져다 쓰기	레시피
명령 찾아보기	명령어 레퍼런스
동작하지 않는 문제 해결하기	문제 해결

선택자, dump, 페어링처럼 처음 보는 용어는 용어집에서 설명합니다.

현재 상태

Droidline은 0.1 버전입니다. 서버, CLI, MCP 어댑터, 릴레이, SDK는 폰 시뮬레이터를 상대로 테스트를 통과했고, 안드로이드 앱은 Android 13 에뮬레이터에서 테스트했습니다. 다음 단계는 실제 폰에서 받는 보고, 특히 여러 제조사 폰에서 설정 매크로가 동작하는지에 대한 보고입니다. 무엇을 확인했는지는 검증 기록에 정확히 적혀 있습니다.