DarwinRelay

Native macOS-Laufzeitumgebung für MCP-Agenten: Shell, PTY, Hintergrund-Chrome und Accessibility-basierte Desktop-Steuerung.

DarwinRelay verbindet einen MCP-Client mit dem Mac, den Sie bereits verwenden. Es stellt strukturierte Funktionen des lokalen Rechners bereit, ohne eine weitere Modellschleife zwischen Client und macOS einzufügen: uneingeschränkter Shell- und Dateisystemzugriff, interaktive PTYs, langlaufende Jobs, persistierte Codex-Chronik, ein verwalteter Chrome-Arbeitsbereich im Hintergrund sowie native Desktop-Steuerung über Accessibility, ScreenCaptureKit, Vision und CoreGraphics.

[!CAUTION] DarwinRelay ist bewusst sehr mächtig. Es ist keine Sandbox und implementiert keine Zulassungsliste für Dateisystem- oder Shell-Operationen. Ein verbundener Client kann mit den effektiven Berechtigungen des macOS-Kontos handeln, das die Brücke ausführt. Lesen Sie SECURITY.md, bevor Sie DarwinRelay über localhost hinaus bereitstellen.

Warum DarwinRelay

Viele MCP-Server exponieren nur eine schmale API. DarwinRelay ist als lokale Ausführungslaufzeit für Entwickler- und Computer-Use-Workflows entwickelt, bei denen der nützliche Zustand ohnehin bereits auf dem Mac liegt:

• Shell und Dateien — Befehle ausführen, Dateien inspizieren oder modifizieren, Patches anwenden und lokale Prozesse verwalten.

• Echte PTYs — interaktive Shells, REPLs, SSH, Sudo-Eingabeaufforderungen, TUIs und langlaufende Terminal-Programme.

• Nativer Computer-Use — semantische AX-Abfragen und Aktionen, Fenster, Dialoge, Öffnen/Speichern-Dialoge, Tastatur- und Maus-Fallback, Screenshots, OCR und visuelle Wartezeiten.

• Chrome-Automatisierung im Hintergrund — ein eigens von einer Chrome-Erweiterung verwalteter Tab-Pool, der navigieren, inspizieren, ausfüllen und klicken kann, ohne regelmäßig den Vordergrund zu übernehmen.

• Codex-Verlauf — Persistierte Codex-Threads lesen, ohne eine neue Modellrunde zu starten.

• Remote-MCP-Transport — stdio bei lokaler Nutzung oder dem mitgelieferten authentifizierten HTTP-/OAuth-Frontend hinter einem Tunnel, den Sie kontrollieren.

• Fail-Closed-Lebenszyklus — explizite Vollzugriff-Entsperrung, Audit-Logging, Prozess-Wiedergewinnung, Single-Instance-Menüzustand und rollbackfähige App-Updates.

Related MCP server: mcp-server-macos-use

Systemarchitektur

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

Der native Desktop-Helfer ist bewusst nur kurzlebig und nicht als privilegierter Daemon ausgelegt. Die Menü-App, der MacUIHelper und der virtuelle Cursor verwenden gemeinsame, stabile Codesignierung-IDs, sodass macOS-TCC-Gewährungen normale Rebuilds überstehen können, wenn eine geeignete Signierung verfügbar ist.

Voraussetzungen

• macOS 13 oder neuer

• Node.js 18 oder neuer (Node.js 22 wird in CI verwendet)

• Xcode Command Line Tools bzw. swiftc für die native Desktop- Steuerung und die Menü-App

• Accessibility- und Bildschirmaufnahme-Berechtigungen für nativen Computer-Use

• Google Chrome nur, wenn Sie den verwalteten chrome_*-Arbeitsbereich im Hintergrund verwenden möchten

• cloudflared oder ein anderer HTTPSusingled nur, falls Sie den HTTP-Transport entfernt bereitstellen

• Codex CLI nur, wenn Sie die codex_thread_*-Verlaufs-Werkzeuge verwenden möchten

Schnellstart

Klonen Sie das Popository und bauen Sie die Menü-App:

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

Die App erscheint in der macOS-Menüleiste als DR. Gewähren Sie die angefragten Desktop-Berechtigungen und starten Sie dann über Start den von Ihnen konfigurierten HTTP-/Tunnel-Pfad.

Für rein lokale MCP-Nutzung aus den Quellen kann die Brücke auch direkt ausgeführt werden. Der volle Zugriff muss dabei ausdrücklich bestätigt werden:

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

Der Standardablageort der Laufzeitdaten liegt unter:

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

Verwenden Sie Umgebungsvariablen wie DARWINRELAY_DATAG_DIR, DARWINRELAY_LOG_DIR, DARWINRELAY_SHELL und DARWINRELAY_AUDIT_MODE, um Entwicklungs-/Testinstanzen zu isolieren.

Für KI- und Coding-Agenten

Dieses Repository enthält bereits vorgesehene, agentenorientierte Dokumentation. Wenn Sie das Repository an Codex, Claude, ChatGPT oder einen anderen Coding-Agenten übergeben, verweisen Sie ihm zuerst auf AGENTS.md. Diese Datei beschreibt die Verzeichnisstruktur, Invarianten, Entwicklungsbefehle, Test-/Testingredingut, Signier-Regeln und Release-Grenzen.

Für einen Agenten, der eine bereits installierte DarwinRelay-Laufzeitumgebung bedient und keine Quelltext-Änderungen vornimmt, verwenden Sie docs/AGENT_OPERATIONS.md. Es enthält die vollständige Tool-Abbildung, die bevorzugte Entscheidungslogik, häufige Fehlerzustände und sichere Runtime-Arbeitsabläufe. docs/ARCHITECTURE.md beschreibt die Komponenten-/Datenflüsse und Vertrauensgrenzen für eine tiefere Begründung.

Native Desktop-Steuereinheit

DarwinRelay bevorzugen semantische Accessibility-Operationen und nutzt visuelle/rohe Eingaben als Fallback. Zu den Kernfunktionen gehören:

• ui_observe, ui_tree, ui_ax_query, ui_ax_at

• Fingerprinting-AX-Referenzen mit Erkennung veralteter Referenzen

• ui_action, ui_wait_for, ui_assert

• ui_app_*, ui_Window_*, Dialoge und Dateisystem: Dialogs

• ScreenCaptureKit-Screenshots und Vision-OCR

• Hintergrund-Targets: PID-gerichtete Eingabe, wo unterstützt, mit semantischer Verifikation und begrenztem Vordergrund-Fallback

• ui_sequence für deterministische, mehr tiefgestufene native Aktionen

• einen click-through-virtuellen KI-Cursor, der den physischen Zeiger nicht bewegt

Weiterführende Informationen zum Kontrollmodell und den Grenzen finden Sie in docs/DESKTOP_CONTROL.md.

Chrome-Arbeitsbereich im Hintergrund

DarwinRelay verwendet eine ungepackte Chrome-Erweiterung sowie Native Messaging. Die öffentliche Erweiterungsidentität ist stabil; die erwartete Extension-ID ist:

GXP1 (Expected extension ID placeholder? Actually GXP5)

Der Installer erstellt oder verwendet standardmäßig ein abgemeldetes lokales Chrome-Profil mit dem Namen DarwinRelay. Dadurch bleibt der agentische Browser-State von normalen, privaten Google-Profilen getrennt:

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

Das Standardprofil wird ohne Löschung zusätzlicher Browser- oder Anmeldedaten angelegt. Wenn das DarwinRelay-Profil noch nicht existiert, beenden Sie Chrome einmal, bevor der Installer läuft, damit Chrome für dabei nicht gleichzeitig Local State überschreiben kann; nachdem das Profil existiert, können normale Reinstall läuft auch bei geöffnetem Chrome problemlos durchgeführt werden. Die Deinstallation von DarwinRelay lässt das Profil bewusst bestehen, weil Browserprofilinhalte private Benutzerdaten sind.

Aktivieren Sie dann nur im ausgewählten Projekt chrome://extensions, um den Entwicklermodus zu aktivieren, klicken Sie auf Load unpacked und wählen Sie das chrome-extension/-Verzeichnis dieses Repositorys aus. Sie können dazu --open an den Installer übergeben, um diesen einmaligen Einrichtungs-Schritt zu erleichtern.

Die Extension betreibt einen Chrome-eigenen Tab-Bereich namens DR. Reguläre chrome_open-Aufrufeisten proto erzeugte Leerlauf-Tabs anstelle von beliebigen Vordergrund-Tabs; chrome_close gibt Arbeitsbereich-Thicles in den Pool zurück.

Browser-Sicherheitsmodell

Die Abgenehmigungen sind standardmäßig großzügig. Die normale HTTP/HTTPS-Nutzung über den konfigurierten chrome_*-Arbeitsbereich erfordert keine einzelseitige Zugriffsfreigabe. Das Aktivieren von Striskt Approvings in der Menü-App stellt wieder seitenabhängige URL-Zugriffe sind einmalige, Anwend- bezogene Mutations-Erlaubnisse her.

Eine direkte Chrome-Automation per Shell/AppleScript/JXA bleibt durch die Brücke blockiert, sodass normale Web-Arbeit im betreuten Hintergrund stattfinden muss. Die separate ui_*-Oberfläche kann können Hintergrund-Chrome-UI trotzdem erreichen, wenn Browser-/OS-Sicherheitsflächen dies wirklich erfordern.

Ein optionaler, roher Browser-Harness-/CDP-Adapter existiert hinter DARWINRELAY_ADVANCED_BROWSER=1. Er ist standardmäßig deaktiviert und läuft unter Stricken Approvals im Fail-Closed-Modus, da beliebiges CDP beim nicht sinnvoll auf URL-Bereiche abbilden lässt.

HTTP/OAuth-Transport

mcp-http.mjs bindet an das Loopback und unterstützt den MCP HTTP-Transport mit einem statischen Bearer-Token sowie und-Gelegen: OAuth-2.1 Flows für entfernte MCP-Clients. Ein Tunnel wie Cloudflare kann den Loopback-Dienst über HTTPS publizieren.

Ein minimales lokales Front-End sieht so aus:

mkdir -p "$HOME/Library/Application Support/DarwinRelay"
openssl rand -hex 32 > "$HOME/Library/Application Support/DarwinRelay/http-token"
chmod 600 "$HOME/Library/Application Support/DarwinRelay/http-token"

export DARWINRELAY_HTTP_TOKEN_FILE="$HOME/Library/Application Support/DarwinRelay/http-token"
node mcp-http.mjs

Geben Sie den HTTP-Endpunkt nicht ohne Lektüre des Fernzugriffs-Threat-Modells in SECURITY.md frei. Ein von diesem Frontend akzeptierter Credential’ letztendlich Einfallszer Zugriff auf lokale Codeausführung unter dem Konto Ihres Benutzers.

Das Repo enthält außerdem den vom ursprünglichen Projekt ererbten OpenAI Secure MCP Tunnel-Installer für alle, die den anderen Übertragungsweg bevorzugen. Siehe DEPLOY.md.

Entwicklung

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

Die öffentliche CI verwendet statt einem einzelnen undurchschaubaren test-Job getrennte Checks:

• Statische Checks — Syntax-/Build-Validierung und ein gitleaks-Scan der vollständigen Git-Historie

• Kern- und Protokolltests — MCP-, HTTP/OAuth-, PTY-, Föderations-,- Browser- und Adversarial-Tests

• Desktop-Steuerungstests — deterministische Desktop-Protokolltests sowie native Fixture-Kompilierung

• Installation und Lebenszyklus-Tests — Installer, Autostart, Singleton-Besitz, Rollback und Deinstallation

Der reale AppKit-E2E-Test benötigt einen angemeldeten Mac mit TCC-Permissionen und ist auf nicht beständigen GitHub-GUI-Sessions nicht zuverlässig. Maintainer können das Testcase lokal ausführen:

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

Lesen Sie CONTRIBUTING.md, bevor Sie einen Pull-Request öffnen.

Sicherheit

Die wichtigste Aussage ist einfach: DarwinRelay besitzt die Berechtigungen des macOS-Kontos, das es ausführt. Sicherheitsfeatures wie Sperr-Dateien, Strict-Approvals, Audit-Metadaten, OAuth, Background-Browser-Feating oder Prozess-Reclamation reduzieren unbeabsichtigten oder entfernten Missbrauch; sie machen einen Shell-Zugriff Spein keine Sandbox.

Sicherheitsmeldungen sollten über die private GitHub-eigene „Report a Vulnerability“-Funktion und nicht als öffentlicches Issue eingesendet werden. Siehe SECURITY.md.

Projektgescheckung

DarwinRelay wird unabhängig gewartet und hat sich deutlich von Mac Developer Bridge von Alexander Rådahl Benz entfernt. Die übernommene Upstream-Projektgeschichte ist gewollt vollständig erhalten und der ursprüngliche MIT-Copyright bleibt in LICENSE bestehen. Details zur Herkunft und zur Namensrichtlinie finden Sie in UPSTREAM.md.

Das öffentliche Repository dcierra/darwinrelay ist die offizielle Entwicklungsquelle. Das frühere private Repository dient vorübergehend nur als Legacy-Produktions-/ Rollback-Quelle, bis der installierte 0.5.x-Runtime Prozessumgezogen ist – es ist kein zweiter aktiver Entwicklungsbranch. Siehe docs/DEVELOPMENT_MODEL.md für die Commit-Historie-Map und die weitere Arbeitsweise.

DarwinRelay ist nicht mit OpenAI, Apple, Google, Cloudflare oder dem Upstream-Ehrenamt verbunden und wird von diesen nicht unterstützt oder befürwortet.

Lizenz

MIT. Siehe LICENSE und UPSTREAM.md.