# macOS IPC

## Overview

OpenClaw's macOS architecture uses a local Unix socket connecting a node host service to the macOS app for execution approvals and system commands. A debug CLI tool (`openclaw-mac`) supports discovery and connection checks.

## Key Architecture Components

### Primary Goal

Maintain a single GUI app instance that handles all TCC-related operations while minimizing the automation surface area.

### System Layers

The system operates through three main layers:

#### 1. Gateway + Node Transport

The application runs the Gateway locally and connects as a node, executing agent actions via `node.invoke` for commands like `system.run` and `system.notify`.

#### 2. IPC Layer

A headless node service connects to the Gateway WebSocket, forwarding `system.run` requests to the macOS app through a local Unix socket with security measures:

- Tokens
- HMAC validation
- TTL

#### 3. UI Automation

PeekabooBridge operates on a separate socket (`bridge.sock`), following a preference hierarchy:

1. Peekaboo.app
2. Claude.app
3. OpenClaw.app
4. Local execution

## Security Considerations

Protection mechanisms include:

- Socket permissions set to `0600`
- Peer UID verification checks
- HMAC-based challenge/response protocols
- Short time-to-live values on tokens
- TeamID matching requirements for privileged operations
- Signed bundle ID stability across rebuilds

Communication remains entirely local without exposed network sockets.