Configuración de la arquitectura IPC en macOS

¿Te ha pasado que un proceso en segundo plano necesita ejecutar una acción en la interfaz de usuario y macOS bloquea la petición por falta de permisos? Gestionar la comunicación entre procesos (IPC) y mantener la persistencia de los permisos de TCC (Transparencia, Consentimiento y Control) suele ser un dolor de cabeza cuando trabajas con herramientas que mezclan servicios de terminal y aplicaciones con interfaz gráfica.

Esta arquitectura resuelve ese problema centralizando las operaciones que requieren permisos del sistema en una única aplicación firmada.

What You’ll Need

• Un entorno de desarrollo macOS.
• Una identidad de firma válida (SIGN_IDENTITY) con TeamID.
• El script scripts/restart-mac.sh incluido en el repositorio.
• Peekaboo.app, Claude.app o OpenClaw.app para las funciones de automatización de UI.

Quick Start

Puedes configurar el entorno y activar el sistema IPC en menos de 5 minutos siguiendo estos pasos:

1. Configura tu identidad de firma: Define la variable de entorno con tu nombre de desarrollador y TeamID.

   SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)"

2. Ejecuta el script de despliegue: Lanza el script para limpiar instancias previas y configurar el servicio.

   scripts/restart-mac.sh

Este proceso realiza cuatro acciones automáticas: detiene procesos existentes, compila la app en Swift, empaqueta el bundle y activa el LaunchAgent para que el sistema reconozca la firma de forma persistente.

Cómo funciona el transporte

El sistema utiliza una estructura de comunicación local para garantizar la seguridad y el rendimiento:

• Gateway + Node: La aplicación ejecuta el Gateway en modo local. Las acciones del agente se procesan mediante node.invoke para comandos como system.notify o canvas.*.
• IPC mediante Unix Sockets: El servicio host de Node se conecta al Gateway vía WebSocket. Cuando se solicita un system.run, la petición se envía a la App de macOS a través de un Unix socket local protegido con HMAC y un token con TTL corto.
• Automatización de UI: Se utiliza el protocolo JSON de PeekabooBridge mediante un socket dedicado llamado bridge.sock.

El flujo de ejecución sigue este orden: Agent -> Gateway -> Node Service (WS) -> IPC (UDS) -> Mac App

Troubleshooting

• Problemas con permisos TCC: Si macOS te pide permisos repetidamente tras una reconstrucción, verifica que el bundle ID firmado sea idéntico. La estabilidad de los permisos depende de que el binario mantenga la misma identidad de firma.
• Error de conexión en modo Debug: Si necesitas conectar clientes sin firmar durante el desarrollo, utiliza la variable PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1. Esto habilita el acceso a sockets del mismo UID solo en entornos de depuración.

Para resolver dudas específicas sobre la implementación de los sockets o el protocolo de seguridad, consulta al AI Setup Assistant.

What’s Next

• Uso de PeekabooBridge