DarwinRelay

Convierte ChatGPT en un agente local para tu Mac.

DarwinRelay es un runtime MCP de macOS que prioriza el código fuente y ofrece a ChatGPT y otros clientes MCP acceso estructurado al Mac que ya usas: shell y archivos, PTYs reales, trabajos de larga duración, Chrome en segundo plano, control nativo del escritorio e historial de Codex persistido.

Usa ChatGPT como un agente de codificación local: deja que inspeccione un repositorio, reproduzca un fallo, cambie el código, ejecute las pruebas y verifique el resultado en tu máquina, sin insertar otro modelo de codificación entre la conversación y macOS.

[!CAUTION] DarwinRelay es intencionadamente potente. No es un sandbox y no implementa una lista blanca de comandos de shell ni de sistema de archivos. Un cliente conectado puede actuar con los permisos efectivos del usuario de macOS que ejecuta el puente. Lee SECURITY.md antes de conectar un cliente o exponer el runtime más allá de localhost.

Usa ChatGPT como agente local

Una tarea típica de desarrollo puede comenzar tan simplemente como:

Use DarwinRelay and work on ~/Projects/myapp.

Find why authentication is failing. Reproduce the problem, fix the underlying
cause, run the relevant tests, and verify the result locally.

Cuando ChatGPT expone la superficie completa de herramientas de DarwinRelay, la misma conversación puede llevar la tarea a través de todo el bucle local:

understand → inspect → reproduce → modify → execute → verify → iterate

DarwinRelay no requiere Codex para ese flujo de trabajo. ChatGPT es el cliente de razonamiento; DarwinRelay es el runtime de ejecución en tu Mac.

Disponibilidad de ChatGPT

La disponibilidad de MCP personalizado de ChatGPT está controlada por OpenAI y puede cambiar independientemente de DarwinRelay. El plan, el espacio de trabajo, el despliegue y el comportamiento de la interfaz pueden diferir de la documentación actual, por lo que debes tratar la superficie de herramientas que se muestra en tu cuenta como autoritativa para lo que esa sesión de ChatGPT puede usar. Consulta la documentación actual de OpenAI sobre el modo desarrollador y los conectores MCP al configurar la conexión.

DarwinRelay en sí sigue siendo neutral respecto al cliente MCP y también puede ser utilizado por otros clientes que admitan la superficie de herramientas MCP requerida.

Aquí, "agente local" describe el flujo de trabajo, no la característica separada de modo Agente de ChatGPT. OpenAI actualmente dice que el modo Agente no usa aplicaciones personalizadas; usa DarwinRelay desde una conversación normal de ChatGPT con la aplicación personalizada seleccionada.

Related MCP server: mcp-server-macos-use

¿Qué puede hacer?

• Shell y archivos — ejecutar comandos, inspeccionar o modificar archivos, aplicar parches y gestionar procesos locales.

• PTYs reales — shells interactivos, REPLs, SSH, prompts de sudo, TUIs y programas de terminal de larga duración.

• Trabajos y ciclo de vida de procesos — iniciar trabajo que sobrevive a una sola llamada de herramienta, inspeccionarlo más tarde y recuperarlo al apagar.

• Uso nativo del ordenador — consultas/acciones semánticas de Accesibilidad, ventanas, diálogos, paneles de archivos, capturas de pantalla, OCR, teclado/ratón de respaldo y esperas visuales.

• Automatización de navegador en segundo plano — un perfil de Chrome dedicado y un grupo de pestañas propiedad de la extensión que puede navegar, inspeccionar, rellenar y hacer clic sin robar el foco de forma rutinaria.

• Historial de Codex — leer hilos de Codex persistidos sin reanudarlos ni iniciar otro turno de modelo.

• Transporte MCP autenticado — stdio localmente, o el front-end HTTP/OAuth incluido detrás de un túnel que tú controlas.

• Controles de ciclo de vida con cierre ante fallos — desbloqueo explícito de acceso completo, metadatos de auditoría, recuperación de procesos, propiedad de menú singleton y actualizaciones de aplicaciones conscientes de la reversión.

Flujo de trabajo para desarrolladores

El primer flujo de trabajo útil de DarwinRelay no debería requerir automatización de navegador, permisos de interfaz nativa ni historial de Codex.

ChatGPT
  ↓
DarwinRelay
  ↓
local repository
  ↓
read files / run commands / edit code / run tests
  ↓
verify the result on the same Mac

Una vez que el bucle de codificación principal funciona, añade capacidades solo cuando la tarea las necesite:

• usa un PTY para un depurador interactivo, REPL, sesión SSH o TUI;

• usa Chrome en segundo plano para flujos de trabajo web;

• concede permisos de escritorio nativos cuando ChatGPT necesite operar una app real de macOS;

• usa el historial de Codex cuando quieras que ChatGPT inspeccione o continúe trabajo anterior de Codex.

Consulta examples/README.md para flujos de trabajo listos para copiar y pegar.

Más allá de la codificación

DarwinRelay puede combinar código local, procesos, estado del navegador e interfaz nativa de macOS en un solo bucle de ejecución. Por ejemplo, una tarea de depuración de una app de escritorio puede verse así:

launch the app
→ reproduce the issue through the real UI
→ inspect logs and code
→ fix the implementation
→ restart the app
→ repeat the UI flow
→ verify the fix

La capa de escritorio nativa usa Accesibilidad primero y recurre a ScreenCaptureKit/Vision y entrada sintetizada cuando es necesario. La capa de navegador usa un perfil local de Chrome dedicado por defecto, en lugar de tomar silenciosamente tu perfil habitual.

¿Ya usas Codex?

DarwinRelay puede leer el historial de Codex persistido sin iniciar otro turno de modelo de Codex. Eso convierte a Codex en una fuente de continuidad útil, no en un intermediario necesario:

Find the latest Codex thread for this project.
Summarize the objective, branch, changed files, current errors, and unfinished step.
Then inspect the live repository and continue the work from ChatGPT.

Inicio rápido

DarwinRelay es actualmente de código fuente primero / auto-compilado. Los lanzamientos de GitHub no incluyen un .app o .dmg precompilado, y no se requiere una membresía de pago del Programa de Desarrolladores de Apple para el modelo de producto actual.

1. Requisitos

Núcleo de auto-compilación:

• macOS 13 o posterior;

• Node.js 18 o posterior (Node.js 22 se usa en CI);

• Xcode Command Line Tools / swiftc para la app de menú y el helper nativo.

Para ChatGPT a través de la ruta HTTP/Server URL de la app de menú, instala también cloudflared y asegúrate de que esté disponible en tu PATH de shell de inicio de sesión.

Capacidades opcionales:

• Permisos de Accesibilidad, Grabación de Pantalla y Entrada/Eventos de Post — solo para control nativo del escritorio;

• Acceso a Disco Completo — solo cuando las tareas necesiten ubicaciones del sistema de archivos protegidas por macOS;

• Google Chrome — solo para el espacio de trabajo gestionado chrome_* en segundo plano;

• CLI/historial de Codex — solo para las herramientas de continuidad codex_thread_*.

2. Elige una ruta de instalación

Opción A — Instalar con un agente de codificación local

¿Ya usas Codex, Claude Code u otro agente de codificación local con acceso a shell/sistema de archivos? Deja que realice la auto-compilación por ti:

Install DarwinRelay on this Mac from:
https://github.com/dcierra/darwinrelay

Read AGENTS.md and the installation documentation first.

Install or verify the required dependencies, then build and install DarwinRelay
using the documented source-first/self-build path. Configure everything that
can be configured without weakening the project's security model.

Do not bypass macOS security controls. Do not use my personal Chrome profile.

When macOS requires Accessibility, Screen Recording, Input/Post Events, Full
Disk Access, Keychain access, or another user-consent step, stop and tell me
exactly what I need to approve manually.

After installation, verify that DarwinRelay starts correctly and report what
remains to connect it to my MCP client.

El agente debe seguir el repositorio en lugar de adivinar. Si esta ruta expone una dependencia ambigua, un paso de compilación o una transferencia de permisos, eso es un error de incorporación que debe corregirse en los scripts/documentos de DarwinRelay, no algo que deba ocultarse con un prompt más largo.

Opción B — Instalar manualmente

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

El script de compilación instala la app de menú compilada localmente en /Applications cuando es posible (con respaldo en ~/Applications). Mantén el checkout de DarwinRelay en su lugar: la app auto-compilada resuelve intencionadamente su runtime desde ese paquete fuente.

La compilación usa una identidad de firma de código local persistente cuando está disponible y, de lo contrario, recurre a la firma ad-hoc. Las compilaciones ad-hoc funcionan sin una membresía de pago de Apple Developer, pero las concesiones TCC de macOS pueden necesitar volver a otorgarse después de recompilaciones porque el requisito designado puede cambiar.

Para una prueba de humo de compilación/firma sin efecto secundario de instalación, usa:

DARWINRELAY_APP_OUTPUT=/tmp/DarwinRelay.app ./menubar/build.sh --build-only

Actualizar DarwinRelay

./scripts/update.sh se incluye a partir de DarwinRelay v0.6.5. Si una instalación existente está en v0.6.4 o anterior, realiza una última actualización/reinstalación manual de código fuente primero a v0.6.5 usando los pasos de instalación anteriores; desde v0.6.5 en adelante, usa el actualizador para cambios de versión a versión.

Desde DarwinRelay v0.6.9 en adelante, la barra de menú también expone Actualizar DarwinRelay…. Pide confirmación explícita, abre el mismo actualizador canónico en una ventana de Terminal independiente y muestra el progreso mientras la app se reinicia. No hay ruta de actualización silenciosa ni automática.

Puedes ejecutar el mismo actualizador directamente desde una sesión normal de Terminal/iTerm local (u otro shell local independiente), no a través de la conexión MCP de DarwinRelay que está a punto de reiniciarse:

cd /path/to/darwinrelay
./scripts/update.sh

Eso actualiza a la última versión estable vMAJOR.MINOR.PATCH. Para seleccionar una versión publicada exacta en su lugar:

./scripts/update.sh v0.6.5

El actualizador trata el checkout de Git y /Applications/DarwinRelay.app como una sola transacción. Verifica el origen canónico de GitHub, requiere un checkout limpio fijado a una etiqueta de versión estable exacta, comprueba la integridad del código fuente, rechaza etiquetas movidas y degradaciones, instala atómicamente la nueva app con la misma identidad de firma, refresca el inicio automático, reinicia con cierre ante fallos y requiere que el doctor MCP real devuelva CORE VERDICT: READY. Si la activación falla, intenta restaurar tanto el checkout anterior como la app de reversión retenida.

Deliberadamente no usa git pull, git reset --hard ni elimina trabajo local. Un checkout sucio/de desarrollo se rechaza; mantén los cambios de desarrollo en otra rama/worktree en lugar de usar la instalación de producción como checkout de codificación.

Debido a que la extensión de Chrome en segundo plano se carga sin empaquetar desde este checkout, una versión que cambie su manifest/código fuente puede requerir una Recarga manual desde la página de Extensiones de Chrome en el perfil dedicado DarwinRelay. El actualizador informa de esto cuando cambia la versión de la extensión; nunca sustituyas un perfil personal.

Para los mantenedores del proyecto, los cambios de actualizador/ciclo de vida tienen una puerta de pre-lanzamiento adicional: el candidato exacto sin etiquetar se prueba en un Mac real con scripts/test-update-candidate.sh antes de crear una etiqueta pública. Esto está deliberadamente separado del actualizador orientado al usuario para que los commits arbitrarios nunca se conviertan en un objetivo de actualización normal.

3. Conecta ChatGPT

Abre el elemento de la barra de menú DR y pulsa Iniciar. Cuando el transporte MCP esté en ejecución, elige Copiar configuración de ChatGPT y sigue docs/CHATGPT.md.

El primer flujo de trabajo de codificación no requiere Chrome, historial de Codex, Accesibilidad, Grabación de Pantalla ni permiso de Entrada. Configúralos más tarde cuando una tarea realmente los necesite.

4. Verifica antes de modificar nada

Comienza con una comprobación de solo lectura:

Use DarwinRelay. Call bridge_status first.
Then list ~/Projects/myapp and read its top-level README/package metadata.
Do not modify files or run shell commands yet.

Luego, si ChatGPT expone las herramientas de escritura/ejecución de DarwinRelay en tu cuenta, prueba el flujo de trabajo real:

Use DarwinRelay and work on ~/Projects/myapp.
Run the test suite, find one failing test, fix the underlying issue, rerun the
relevant tests, and verify the result. Do not deploy or force-push anything.

Para solucionar problemas, ejecuta:

./scripts/doctor.sh

El doctor ahora da un veredicto bloqueante de ruta de codificación Core / MCP por separado de las capacidades opcionales de escritorio nativo, sistema de archivos protegido, Chrome en segundo plano y Codex. Realiza una comprobación de humo local real de initialize → bridge_status para el transporte seleccionado e imprime la siguiente acción para fallos bloqueantes. Los diagnósticos más profundos de ciclo de vida/navegador continúan evolucionando en la hoja de ruta.

Uso MCP local solo de código fuente

Para clientes MCP que puedan conectarse a un servidor stdio local, el puente también puede ejecutarse directamente sin la app de menú. El acceso completo debe reconocerse explícitamente:

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

Estado de runtime por defecto:

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

Usa variables de entorno como DARWINRELAY_DATA_DIR, DARWINRELAY_LOG_DIR, DARWINRELAY_SHELL y DARWINRELAY_AUDIT_MODE para aislar instancias de desarrollo/pruebas.

Cómo funciona

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]

El helper de escritorio nativo es deliberadamente de corta duración, no un daemon privilegiado. La app de menú, MacUIHelper y el cursor virtual usan identificadores de firma de código estables para que las concesiones TCC de macOS puedan sobrevivir a recompilaciones normales cuando hay una identidad de firma persistente disponible.

Consulta docs/ARCHITECTURE.md para componentes, flujo de datos y límites de confianza.

Para IA y agentes de codificación

Este repositorio incluye documentación orientada a agentes a propósito. Si le das el repositorio a Codex, Claude, ChatGPT u otro agente de codificación, apúntalo a AGENTS.md primero. Describe el mapa del repositorio, invariantes, comandos de desarrollo, expectativas de pruebas, reglas de firma/navegador y restricciones de lanzamiento.

Para un agente que opera un runtime de DarwinRelay ya instalado en lugar de modificar el código fuente, usa docs/AGENT_OPERATIONS.md. Contiene el mapa completo de familias de herramientas, el orden de decisión preferido, estados de fallo comunes y flujos de trabajo de runtime seguros.

Control nativo del escritorio

DarwinRelay prefiere operaciones semánticas de Accesibilidad y usa entrada visual/bruta como respaldo. Las capacidades principales incluyen:

• ui_observe, ui_tree, ui_ax_query, ui_ax_at;

• referencias AX con huella y detección de referencias obsoletas;

• ui_action, ui_wait_for, ui_assert;

• ui_app_*, ui_window_*, diálogos y paneles de archivos;

• capturas de pantalla de ScreenCaptureKit y OCR de Vision;

• entrada dirigida a PID en segundo plano donde macOS lo soporta, con verificación semántica y respaldo de primer plano acotado;

• ui_sequence para ráfagas nativas deterministas de múltiples pasos;

• un cursor virtual de IA de clic transparente que no mueve el puntero físico.

Consulta docs/DESKTOP_CONTROL.md para el modelo de control y las limitaciones.

Espacio de trabajo de Chrome en segundo plano

DarwinRelay utiliza una extensión de Chrome sin empaquetar más Native Messaging. La identidad pública de la extensión es estable; el id de extensión esperado es:

pfhahlehpahegefejooendokpkklgmgd

El instalador crea o reutiliza un perfil local de Chrome sin sesión iniciada llamado DarwinRelay de forma predeterminada. Esto mantiene el estado de navegación del agente separado de un perfil de Google cotidiano:

# 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

Si el perfil de DarwinRelay aún no existe, cierra Chrome una vez antes de ejecutar el instalador para que Chrome no pueda reescribir simultáneamente su Local State; después de que el perfil exista, las reinstalaciones normales pueden ejecutarse con Chrome abierto. Desinstalar DarwinRelay deja deliberadamente ese perfil en su lugar porque el contenido del perfil del navegador son datos del usuario.

Luego, solo en el perfil seleccionado, abre chrome://extensions, activa el modo de desarrollador, elige Load unpacked y selecciona el directorio chrome-extension/ de este repositorio. Puedes pasar --open al instalador para este paso de configuración único.

La extensión posee un grupo de pestañas nativo de Chrome llamado DR. Las llamadas rutinarias de chrome_open alquilan pestañas inactivas precreadas en lugar de crear pestañas de primer plano arbitrarias. chrome_close devuelve las pestañas del espacio de trabajo al grupo.

Modelo de seguridad del navegador

Las aprobaciones relajadas son la opción predeterminada. El trabajo HTTP/HTTPS normal a través del espacio de trabajo chrome_* configurado no necesita una concesión de terminal por sitio. Habilitar aprobaciones estrictas en la aplicación de menú restaura las concesiones de URL con ámbito y las aprobaciones de mutación nativa de un solo uso con ámbito de aplicación.

La automatización directa de Chrome a través de shell/AppleScript/JXA permanece bloqueada por el puente, de modo que el trabajo web normal se mantiene en la ruta de fondo administrada. La superficie nativa separada ui_* aún puede interactuar con la interfaz de Chrome en primer plano cuando las superficies de seguridad del navegador/SO realmente lo requieren.

Existe un adaptador opcional de Browser Harness/CDP sin procesar detrás de DARWINRELAY_ADVANCED_BROWSER=1. Está deshabilitado de forma predeterminada y falla cerrado bajo aprobaciones estrictas porque el CDP arbitrario no puede reducirse de manera sólida a ámbitos de URL.

Transporte HTTP / OAuth

mcp-http.mjs se vincula a loopback y admite el transporte HTTP de MCP con un token de portador estático más flujos OAuth 2.1 utilizados por clientes MCP remotos. Un túnel como Cloudflare puede publicar el servicio de loopback a través de HTTPS.

La aplicación de menú es el punto de entrada preferido para la ruta normal de URL del servidor ChatGPT. DEPLOY.md documenta la configuración de transporte manual/avanzada, incluida la ruta de OpenAI Secure MCP Tunnel conservada del proyecto upstream.

No expongas el endpoint HTTP sin leer el modelo de amenazas de acceso remoto en SECURITY.md. Una credencial aceptada por este front end finalmente controla la ejecución de código local como tu usuario de escritorio.

Desarrollo

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

El CI público expone intencionalmente comprobaciones separadas en lugar de un único trabajo test opaco:

• Comprobaciones estáticas — validación de compilación de sintaxis/nativa y escaneo de gitleaks de historial completo;

• Pruebas de núcleo y protocolo — pruebas de MCP, HTTP/OAuth, PTY, federación, navegador y adversariales;

• Pruebas de control de escritorio — pruebas deterministas de protocolo de escritorio más compilación de fixtures nativos;

• Pruebas de instalación y ciclo de vida — instaladores, inicio automático, propiedad de singleton, reversión y comportamiento de desinstalación.

El E2E real de AppKit mutable necesita un Mac con sesión iniciada y permisos de TCC, por lo que no se considera confiable en sesiones GUI desechables alojadas en GitHub. Los mantenedores pueden ejecutarlo localmente con:

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

Consulta CONTRIBUTING.md antes de abrir una solicitud de extracción. Las prioridades de desarrollo actuales se rastrean en ROADMAP.md.

Seguridad

El límite importante es simple: DarwinRelay tiene la autoridad de la cuenta de macOS que lo ejecuta. Las características de seguridad como el archivo de desbloqueo, las aprobaciones estrictas, los metadatos de auditoría, OAuth, el enrutamiento del navegador en segundo plano y la recuperación de procesos reducen el uso indebido accidental o remoto; no convierten el acceso arbitrario al shell en un sandbox.

Los informes de seguridad deben usar el informe de vulnerabilidad privado de GitHub en lugar de un problema público. Consulta SECURITY.md.

Linaje del proyecto

DarwinRelay se mantiene de forma independiente y ha divergido sustancialmente de Mac Developer Bridge de Alexander Rådahl Benz. La historia upstream heredada se conserva intencionalmente, y el aviso de copyright MIT original permanece en LICENSE. Consulta UPSTREAM.md para conocer el linaje exacto y la política de atribución.

El repositorio público dcierra/darwinrelay es la fuente de desarrollo canónica. Consulta docs/DEVELOPMENT_MODEL.md para el modelo de desarrollo/lanzamiento.

DarwinRelay no está afiliado ni respaldado por OpenAI, Apple, Google, Cloudflare ni el mantenedor upstream.

Licencia

MIT. Consulta LICENSE y UPSTREAM.md.