serve-droid

Android를 위한 공유 브라우저 콕핏이자 에이전트 컨트롤 플레인. 에뮬레이터나 실물 기기를 스트리밍하고 Chrome이나 Edge에서 제어하며, 시맨틱 UI 트리와 Logcat을 검사하거나, 동일한 세션을 MCP 호환 코딩 에이전트에 넘길 수 있습니다.

상태: v0.1 개발 릴리스. 공개 API는 버전이 관리되지만, 비디오 전송과 기기 호환성은 게시된 지원 매트릭스에서 검증이 필요합니다.

npx serve-droid
# → Browser cockpit at a local authenticated URL

하나의 공유 세션: 간결한 활성 기기 컨트롤은 왼쪽에 유지되고, 실시간 Android 화면이 기본 작업 공간을 차지합니다. 넓은 화면에서는 에이전트 인스펙터가 상황에 맞게 오른쪽에 플로팅되어 필터링된 Logcat, 시맨틱 UI, 프라이버시 보호 Activity 사이를 전환합니다. 더 좁은 창에서는 상호작용 영역을 줄이는 대신 기기 아래에 쌓입니다. 결정적 데모는 인증된 파일 설치 및 클립보드 흐름도 실행합니다. 실제 기기 검증은 아니며, 하드웨어 증거는 릴리스 체크리스트에서 별도로 추적됩니다.

제공 기능

• 릴리스 전 단계에서는 동일한 실시간 scrcpy 세션을 통해 전달되는 직접 포인터 DOWN, 병합된 MOVE, UP/CANCEL 이벤트를 갖춘 반응형 브라우저 콕핏의 H.264 기기 스트리밍.

• 기기 위 마우스 휠 및 트랙패드 스크롤. 고해상도 브라우저 입력이 기기 명령 백로그를 만들지 않도록 제한된 scrcpy 터치 제스처로 병합됩니다.

• 디코딩된 실시간 프레임에서 원클릭 스크린샷 캡처. 인증된 기기 폴백, 미리보기, 다운로드, 지원되는 브라우저 클립보드 동작 포함.

• 누락되거나 모호한 일치에서 중단되는 정확한 시맨틱 요소 타기팅.

• 검색 가능하고 우선순위 필터링된 Logcat과 일시정지, 지우기, 복사 컨트롤.

• 브라우저 재생 음소거와 분리된, 기기 레일의 명시적 Android 시스템 볼륨 내림/올림 컨트롤.

• 최근 구조화된 세션, 기기, 제어 이벤트에 대한 프라이버시 필터링된 인메모리 Activity 타임라인.

• 안전한 LAN 토큰 입력과 포커스된 Android 필드로의 제한된 클립보드 붙여넣기.

• 바이트 진행률과 명시적 Android 처리 단계가 있는 APK 또는 파일 드래그 앤 드롭 전송.

• 화면, UI 계층, 포그라운드 앱, 기기 상태, 증분 로그를 포함한 하나의 제한된 관찰.

• CLI, 인증된 HTTP/WebSocket API, MCP, Agent Skill을 통한 동일한 기능.

Related MCP server: Android MCP

배경

Android Studio는 기기를 미러링하고, scrcpy는 훌륭한 네이티브 디스플레이/제어를 제공하며, Maestro는 강력한 테스트 자동화 시스템입니다. serve-droid는 다른 루프에 초점을 맞춥니다: 개발 및 디버깅 중에 인간과 AI 에이전트가 하나의 관찰 가능한 브라우저 세션을 공유하는 것입니다.

영감

브라우저 우선 콕핏 방향은 Evan Bacon의 serve-sim에서 영감을 받았습니다. serve-droid는 ADB, scrcpy 전송, Logcat, 시맨틱 관찰, MCP를 기반으로 구축된 독립적인 Android 중심 구현입니다.

요구 사항

• Node.js 22 이상

• adb가 PATH, ANDROID_HOME, 또는 ANDROID_SDK_ROOT에 포함된 Android SDK Platform Tools

• adb devices -l에 표시되는 Android 8 / API 26+ 에뮬레이터 또는 기기

• 최신 Chrome, Edge, Safari, Firefox 브라우저. Chromium은 WebCodecs를 사용하고, Safari와 Firefox는 비용이 더 높은 TinyH264 소프트웨어 폴백을 사용합니다.

Android Platform Tools는 사용자 모르게 다운로드되거나 재배포되지 않습니다.

빠른 시작

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activity는 브라우저 인스펙터에 표시되는 동일한 제한적이고 프라이버시 필터링된 세션 타임라인을 읽습니다. 하나의 활성 세션을 선택하고 내부적으로 해당 세션으로 인증하며, 베어러 토큰을 노출하지 않고 커서 재개를 지원합니다. Activity 가이드를 참조하세요.

고정 포트를 선택할 때는 기기를 건드리기 전에 포트를 먼저 확인하세요. 사용 중인 포트는 안정적인 PORT_IN_USE 코드와 종료 상태 31을 반환하며, --port 0은 안전한 임시 할당을 유지합니다.

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

기기 재생 오디오는 옵트인이며, 사용자가 활성화하기 전까지 브라우저 재생은 음소거 상태로 유지됩니다:

npx serve-droid start --audio

기기 오디오 및 프라이버시를 참조하세요.

출력된 로컬 URL을 여세요. 서버는 127.0.0.1에서 수신 대기하며, 임의 토큰을 생성하여 로컬 UI에 주입합니다. 기기를 선택하려면:

npx serve-droid --device emulator-5554

설치된 에뮬레이터는 serve-droid avd start <name> 및 serve-droid avd stop <serial>로 명시적으로 관리할 수 있습니다. SDK 콘텐츠는 자동으로 다운로드되거나 라이선스가 부여되지 않습니다. AVD 수명 주기 가이드를 참조하세요.

독립적인 토큰과 제한된 리소스로 여러 연결된 기기를 검사하려면:

npx serve-droid grid --max-devices 4

다중 기기 그리드 보안 및 격리 모델을 참조하세요.

좌표는 정규화됩니다: (0, 0)은 논리적 왼쪽 위, (1, 1)은 오른쪽 아래입니다.

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

실패한 ADB 상호작용은 Android가 명시적인 키가드 또는 입력 정책 증거를 보고하지 않는 한 일반 오류를 유지합니다. DEVICE_LOCKED, SECURE_SCREEN, INPUT_RESTRICTED 계약은 상호작용 실패 진단을 참조하세요.

직접 브라우저 포인터는 커서나 손가락이 움직이는 동안 인증된 begin → move* → end 수명 주기를 제어 WebSocket을 통해 스트리밍합니다. 브라우저는 하나의 요청과 하나의 최신 이동을 보류 상태로 유지하며, 서버는 스트림에 scrcpy 핑거 하나에 대한 단독 소유권을 부여하고 이를 고정된 인코딩 프레임 크기에 매핑합니다. begin 전에 scrcpy를 사용할 수 없으면 기기 입력 전에 요청이 거부되고 콕핏은 기존의 제한된 포인터 해제 시 동작을 안전하게 사용합니다. begin이 성공한 후에는 실패가 ADB를 통해 재생되지 않습니다. 동일 지점의 드문 하트비트는 의도적인 길게 누르기를 유지하고, 중단된 스트림은 2초간 비활성 상태 후 최선의 취소를 받습니다.

브라우저에서 Android 화면 위에 마우스를 올리고 마우스 휠이나 두 손가락 트랙패드 스크롤을 사용하세요. 연속 입력은 하나의 제한되고 커서에 고정된 터치 스와이프로 병합됩니다. 수정자 키를 사용하는 브라우저 확대/축소 제스처는 그대로 유지됩니다.

세션 캡처는 명시적이고 제한적입니다. --record ./recordings는 원본 H.264 스트림과 프라이버시 필터링된 이벤트 요약을 저장하며, 토큰, Logcat, 입력된 텍스트, URL, 파일 내용은 절대 기록하지 않습니다. 즉시 녹화하지 않고 브라우저 시작/중지를 허용하려면 대신 --record-controls ./recordings를 사용하세요. 콕핏은 호스트 경로나 제한을 선택하지 않습니다. 녹화 및 보존 가이드를 참조하세요. 완료된 녹화는 Perfetto에서 타임라인을 검사하기 위해 serve-droid recording trace로 내보낼 수도 있습니다.

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

MCP 표면은 임의의 셸 액세스 대신 명시적이고 제한된 도구를 의도적으로 제공합니다. MCP 가이드를 참조하세요.

보안

• 기본적으로 루프백 전용 바인딩.

• 읽기, 변경, 비디오, 제어에 대한 베어러 인증.

• 브라우저 WebSocket은 자격 증명을 URL이 아닌 하위 프로토콜 헤더로 전달합니다.

• 임의의 ADB 또는 호스트 셸 엔드포인트 없음.

• 업로드는 256 MiB로 제한되며, 전용 임시 디렉터리에 기록되고 즉시 제거됩니다.

• clear 및 uninstall은 비대화형 클라이언트의 명시적 확인을 요구합니다.

LAN 인터페이스에 바인딩하기 전에 SECURITY.md를 읽으세요.

기존 명명된 Cloudflare Tunnel을 통한 단기 원격 액세스는 명시적 동의, HTTPS, 베어러 인증, 하드 만료가 있는 경우에만 사용할 수 있습니다. 사용 전에 터널 위협 모델 및 설정 가이드를 읽으세요.

지원 및 보류

v0.1은 macOS, Linux, Windows, Android API 26+, 로컬 에뮬레이터, USB 기기, Wi-Fi ADB, Chrome, Edge, Safari, Firefox를 대상으로 합니다. 설치된 AVD 수명 주기 컨트롤, 옵트인 제한 로컬 녹화, TinyH264 브라우저 폴백, API 30+용 옵트인 기기 오디오, 옵트인 만료 명명 터널 지원이 포함됩니다. 클라우드 기기 랩, 계정, 다중 사용자 역할, AVD 생성/프로비저닝, iOS, 임의 셸 액세스는 보류됩니다. 브라우저 지원 매트릭스를 참조하세요.

개발

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

Android 픽스처 소스는 fixtures/android-test-app에 있습니다. 실기기 테스트는 SERVE_DROID_DEVICE_TEST=1이 설정된 경우에만 실행됩니다.

완료된 작업과 남은 하드웨어, 플랫폼, 게시 게이트는 증거 기반 릴리스 체크리스트를 참조하세요.

프로젝트 TODO

• 보호된 main, CodeQL, Dependabot, 비밀 스캐닝으로 공개 저장소 게시.

• 공유 CLI, HTTP/WebSocket, MCP, Agent Skill, 브라우저 콕핏 기반 제공.

• 재현 가능하고 명확하게 라벨링된 콕핏 스크린샷을 이 README에 추가.

• 브라우저 콕핏을 상황별 인스펙터가 있는 기기 우선 반응형 작업 공간으로 개선.

• 우선순위 필터링, 일시정지, 지우기, 복사가 있는 검색 가능한 Logcat 컨트롤 추가.

• 브라우저, CLI, 인증된 HTTP 전반에 제한적이고 프라이버시 보호 Activity 추가.

• 안전한 LAN 토큰 전달과 제한된 브라우저 클립보드 컨트롤 추가.

• Android 화면 위 병합된 마우스 휠 및 트랙패드 스크롤 추가.

• 활성 scrcpy 제어 채널을 통한 브라우저 포인터 및 제스처 입력 라우팅.

• 제한된 병합 및 취소와 함께 릴리스 전 직접 포인터 이동 스트리밍.

• macOS, Linux, Windows에서 실기기 승인 매트릭스 완료.

• v0.1.0 태그를 만들기 전에 npm 릴리스 후보 게시 및 검증.

전체 증거 기반 체크리스트는 docs/TODO.md에 있습니다. 항목은 저장소에 구현 또는 필요한 외부 증거가 포함될 때까지 체크되지 않은 상태로 유지됩니다.

라이선스

Apache-2.0. THIRD_PARTY_NOTICES.md를 참조하세요.