serve-droid

Ein gemeinsames Browser-Cockpit und eine Agenten-Steuerungsebene für Android. Streamen Sie einen Emulator oder ein physisches Gerät, steuern Sie es über Chrome oder Edge, inspizieren Sie seinen semantischen UI-Baum und Logcat oder übergeben Sie dieselbe Sitzung an einen MCP-kompatiblen Codierungsagenten.

Status: v0.1-Entwicklungsversion. Die öffentliche API ist versioniert, aber der Videotransport und die Gerätekompatibilität müssen noch auf der veröffentlichten Support-Matrix validiert werden.

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

Eine gemeinsame Sitzung: Kompakte Steuerelemente für das aktive Gerät bleiben links, während die Live-Android-Oberfläche den primären Arbeitsbereich einnimmt. Auf breiten Bildschirmen schwebt der Agenten-Inspektor kontextuell rechts und wechselt zwischen gefiltertem Logcat, semantischer UI und datenschutzsicherer Activity; bei schmaleren Fenstern stapelt er sich unterhalb des Geräts, anstatt die Interaktionsfläche zu verkleinern. Die deterministische Demo übt auch authentifizierte Dateiinstallation und Zwischenablage-Flows. Es ist keine Validierung auf echten Geräten; Hardware-Nachweise werden separat in der Release-Checkliste verfolgt.

Was Sie bekommen

• H.264-Gerätestreaming in einem responsiven Browser-Cockpit mit direkten Pointer-DOWN-, zusammengeführten MOVE- und UP/CANCEL-Ereignissen, die von derselben Live-scrcpy-Sitzung vor der Veröffentlichung übertragen werden.

• Mausrad- und Trackpad-Scrollen über das Gerät, zusammengeführt in begrenzte scrcpy-Touch-Gesten, sodass hochauflösende Browser-Eingaben keinen Rückstau an Gerätebefehlen erzeugen können.

• Ein-Klick-Screenshot-Erfassung aus dem dekodierten Live-Frame, mit authentifiziertem Geräte-Fallback, Vorschau, Download und Zwischenablage-Aktionen für unterstützte Browser.

• Exakte semantische Elementzielung, die bei fehlenden oder mehrdeutigen Übereinstimmungen stoppt.

• Durchsuchbares, nach Priorität gefiltertes Logcat mit Pause-, Lösch- und Kopier-Steuerelementen.

• Explizite Android-Systemlautstärke-Regler (leiser/lauter) in der Geräteleiste, getrennt von der Browser-Wiedergabestummschaltung.

• Datenschutzgefilterte In-Memory-Activity-Zeitleiste für aktuelle strukturierte Sitzungs-, Geräte- und Steuerungsereignisse.

• Sichere LAN-Token-Eingabe und begrenztes Einfügen aus der Zwischenablage in das fokussierte Android-Feld.

• Drag-and-Drop-APK- oder Dateiübertragung mit Byte-Fortschritt und einer expliziten Android-Verarbeitungsphase.

• Eine begrenzte Beobachtung, die Bildschirm, UI-Hierarchie, Vordergrund-App, Gerätezustand und inkrementelle Protokolle enthält.

• Dieselben Fähigkeiten über CLI, authentifizierte HTTP/WebSocket-APIs, MCP und eine Agent-Skill.

Related MCP server: Android MCP

Warum

Android Studio spiegelt Geräte, scrcpy bietet hervorragende native Anzeige/Steuerung und Maestro ist ein starkes Testautomatisierungssystem. serve-droid konzentriert sich auf eine andere Schleife: ein Mensch und ein KI-Agent teilen sich eine beobachtbare Browser-Sitzung während Entwicklung und Debugging.

Inspiration

Die browsererste Cockpit-Richtung wurde von Evan Bacons serve-sim inspiriert. serve-droid ist eine unabhängige, auf Android fokussierte Implementierung, die auf ADB, scrcpy-Transport, Logcat, semantischen Beobachtungen und MCP aufbaut.

Anforderungen

• Node.js 22 oder neuer

• Android SDK Platform Tools mit adb in PATH, ANDROID_HOME oder ANDROID_SDK_ROOT

• Ein Android 8 / API 26+ Emulator oder Gerät, sichtbar in adb devices -l

• Ein aktueller Chrome-, Edge-, Safari- oder Firefox-Browser. Chromium verwendet WebCodecs; Safari und Firefox verwenden den teureren TinyH264-Software-Fallback.

Android Platform Tools werden niemals stillschweigend heruntergeladen oder weiterverteilt.

Schnellstart

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 liest dieselbe begrenzte, datenschutzgefilterte Sitzungszeitleiste, die auch der Browser-Inspektor anzeigt. Es wählt eine Live-Sitzung aus, authentifiziert sich intern mit dieser Sitzung und unterstützt die Cursor-Fortsetzung, ohne das Bearer-Token offenzulegen. Siehe den Activity-Leitfaden.

Bei der Auswahl eines festen Ports testen Sie ihn, bevor Sie das Gerät berühren. Belegte Ports geben den stabilen Code PORT_IN_USE und den Exit-Status 31 zurück; --port 0 behält die sichere ephemere Zuweisung.

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

Geräte-Wiedergabeaudio ist optional und die Browser-Wiedergabe bleibt stummgeschaltet, bis ein Mensch sie aktiviert:

npx serve-droid start --audio

Siehe Geräteaudio und Datenschutz.

Öffnen Sie die gedruckte lokale URL. Der Server lauscht auf 127.0.0.1, generiert ein zufälliges Token und injiziert es in die lokale Benutzeroberfläche. Um ein Gerät auszuwählen:

npx serve-droid --device emulator-5554

Installierte Emulatoren können explizit mit serve-droid avd start <name> und serve-droid avd stop <serial> verwaltet werden. Es werden keine SDK-Inhalte automatisch heruntergeladen oder lizenziert; siehe den AVD-Lebenszyklus-Leitfaden.

Um mehrere verbundene Geräte mit unabhängigen Tokens und begrenzten Ressourcen zu inspizieren:

npx serve-droid grid --max-devices 4

Siehe das Sicherheits- und Isolationsmodell für das Multi-Geräte-Grid.

Koordinaten sind normalisiert: (0, 0) ist das logische oben links und (1, 1) das unten rechts.

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'

Fehlgeschlagene ADB-Interaktionen bewahren generische Fehler, es sei denn, Android meldet explizite Keyguard- oder Eingaberichtlinien-Hinweise. Siehe die Diagnose von Interaktionsfehlern für den Vertrag von DEVICE_LOCKED, SECURE_SCREEN und INPUT_RESTRICTED.

Direkte Browser-Pointer streamen jetzt einen authentifizierten begin → move* → end-Lebenszyklus über den Steuerungs-WebSocket, während der Cursor oder Finger noch in Bewegung ist. Der Browser hält eine Anfrage und eine letzte Bewegung ausstehend, während der Server dem Stream das exklusive Eigentum an einem scrcpy-Finger gibt und ihn auf eine feste codierte Frame-Größe abbildet. Wenn scrcpy vor begin nicht verfügbar ist, wird die Anfrage vor der Geräteeingabe abgelehnt und das Cockpit verwendet sicher seine bestehende begrenzte Aktion zur Freigabezeit. Nach einem erfolgreichen begin werden Fehler niemals über ADB wiederholt. Ein spärlicher Same-Point-Heartbeat hält absichtliche lange Drücke am Leben, während verlassene Streams nach zwei Sekunden Inaktivität einen Best-Effort-Abbruch erhalten.

Im Browser fahren Sie mit der Maus über die Android-Oberfläche und verwenden das Mausrad oder ein Zwei-Finger-Trackpad-Scrollen. Ein Burst wird zu einem begrenzten, cursorverankerten Touch-Swipe zusammengeführt. Modifikatorgestützte Browser-Zoom-Gesten bleiben unberührt.

Die Sitzungsaufzeichnung ist explizit und begrenzt. --record ./recordings speichert den ursprünglichen H.264-Stream plus datenschutzgefilterte Ereigniszusammenfassungen; es zeichnet niemals Tokens, Logcat, getippten Text, URLs oder Dateiinhalte auf. Verwenden Sie stattdessen --record-controls ./recordings, um Browser-Start/Stopp zu autorisieren, ohne sofort aufzuzeichnen; das Cockpit wählt niemals einen Host-Pfad oder ein Limit. Siehe den Leitfaden zu Aufzeichnung und Aufbewahrung. Finalisierte Aufzeichnungen können auch mit serve-droid recording trace für die Zeitleisten-Inspektion in Perfetto exportiert werden.

MCP

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

Die MCP-Oberfläche bietet bewusst explizite begrenzte Werkzeuge anstelle von beliebigem Shell-Zugriff. Siehe den MCP-Leitfaden.

Sicherheit

• Loopback-only-Bindung standardmäßig.

• Bearer-Authentifizierung für Lese-, Mutations-, Video- und Steuerungsvorgänge.

• Browser-WebSockets übertragen Anmeldeinformationen in einem Subprotokoll-Header, nicht in einer URL.

• Kein beliebiger ADB- oder Host-Shell-Endpunkt.

• Uploads sind auf 256 MiB begrenzt, werden in ein privates temporäres Verzeichnis geschrieben und sofort entfernt.

• clear und uninstall erfordern eine explizite Bestätigung von nicht-interaktiven Clients.

Lesen Sie SECURITY.md, bevor Sie an eine LAN-Schnittstelle binden.

Kurzlebiger Fernzugriff über einen vorhandenen benannten Cloudflare-Tunnel ist nur mit ausdrücklicher Zustimmung, HTTPS, Bearer-Authentifizierung und einer harten Ablaufzeit verfügbar. Lesen Sie das Bedrohungsmodell und den Einrichtungsleitfaden für Tunnel, bevor Sie es verwenden.

Unterstützt und aufgeschoben

v0.1 zielt auf macOS, Linux, Windows, Android API 26+, lokale Emulatoren, USB-Geräte, Wi-Fi-ADB, Chrome, Edge, Safari und Firefox. Enthalten sind installierte AVD-Lebenszyklussteuerungen, optionale begrenzte lokale Aufzeichnung, der TinyH264-Browser-Fallback, optionales Geräteaudio für API 30+ und optionale ablaufende benannte Tunnel-Unterstützung. Cloud-Gerätelabore, Konten, Mehrbenutzerrollen, AVD-Erstellung/-Bereitstellung, iOS und beliebiger Shell-Zugriff sind aufgeschoben. Siehe die Browser-Support-Matrix.

Entwicklung

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

Die Android-Fixture-Quelle befindet sich unter fixtures/android-test-app. Echte Gerätetests laufen nur, wenn SERVE_DROID_DEVICE_TEST=1 gesetzt ist.

Siehe die evidenzbasierte Release-Checkliste für abgeschlossene Arbeiten und die verbleibenden Hardware-, Plattform- und Veröffentlichungs-Gates.

Projekt TODO

• Veröffentlichen Sie das offene Repository mit geschütztem main, CodeQL, Dependabot und Secret-Scanning.

• Liefern Sie die gemeinsame CLI-, HTTP/WebSocket-, MCP-, Agent-Skill- und Browser-Cockpit-Grundlage.

• Fügen Sie einen reproduzierbaren, klar beschrifteten Cockpit-Screenshot zu dieser README hinzu.

• Verfeinern Sie das Browser-Cockpit zu einem geräteersten responsiven Arbeitsbereich mit kontextuellem Inspektor.

• Fügen Sie durchsuchbare Logcat-Steuerelemente mit Prioritätsfilterung, Pause, Löschen und Kopieren hinzu.

• Fügen Sie begrenzte datenschutzsichere Activity über Browser, CLI und authentifiziertes HTTP hinzu.

• Fügen Sie sichere LAN-Token-Übergabe und begrenzte Browser-Zwischenablage-Steuerelemente hinzu.

• Fügen Sie zusammengeführtes Mausrad- und Trackpad-Scrollen über die Android-Oberfläche hinzu.

• Leiten Sie Browser-Pointer- und Gesteneingaben über den aktiven scrcpy-Steuerkanal.

• Streamen Sie direkte Pointer-Bewegungen vor der Veröffentlichung mit begrenzter Zusammenführung und Abbruch.

• Vervollständigen Sie die Akzeptanzmatrix für echte Geräte auf macOS, Linux und Windows.

• Veröffentlichen und validieren Sie den npm-Release-Kandidaten, bevor Sie v0.1.0 taggen.

Die vollständige, evidenzbasierte Checkliste befindet sich in docs/TODO.md. Elemente bleiben ungeprüft, bis das Repository die Implementierung oder die erforderlichen externen Nachweise enthält.

Lizenz

Apache-2.0. Siehe THIRD_PARTY_NOTICES.md.