openclaw/docs/mac/xpc.md

---
summary: "macOS IPC architecture for Clawdbot app, gateway node bridge, and PeekabooBridge"
read_when:
  - Editing IPC contracts or menu bar app IPC
---
# Clawdbot macOS IPC architecture (Dec 2025)

**Current model:** there is **no local control socket** and no `clawdbot-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.

## Goals
- Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
- A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.
- Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.

## How it works
### Gateway + node bridge (current)
- The app runs the Gateway (local mode) and connects to it as a node.
- Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`).

### PeekabooBridge (UI automation)
- UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
- Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
- Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
- See: [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo) for the Clawdbot plan and naming.

### Mach/XPC (future direction)
- Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.

## Operational flows
- Restart/rebuild: `SIGN_IDENTITY="Apple Development: Peter Steinberger (2ZAC4GM7GD)" scripts/restart-mac.sh`
  - Kills existing instances
  - Swift build + package
  - Writes/bootstraps/kickstarts the LaunchAgent
- Single instance: app exits early if another instance with the same bundle ID is running.

## Hardening notes
- Prefer requiring a TeamID match for all privileged surfaces.
- PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
- All communication remains local-only; no network sockets are exposed.
- TCC prompts originate only from the GUI app bundle; run `scripts/package-mac-app.sh` so the signed bundle ID stays stable.
docs: add docs:list helper and front matter 2025-12-09 17:51:05 +00:00			`---`
chore: rename project to clawdbot 2026-01-04 14:32:47 +00:00			`summary: "macOS IPC architecture for Clawdbot app, gateway node bridge, and PeekabooBridge"`
docs: add docs:list helper and front matter 2025-12-09 17:51:05 +00:00			`read_when:`
feat(mac): host PeekabooBridge for ui 2025-12-13 16:55:41 +00:00			`- Editing IPC contracts or menu bar app IPC`
docs: add docs:list helper and front matter 2025-12-09 17:51:05 +00:00			`---`
chore: rename project to clawdbot 2026-01-04 14:32:47 +00:00			`# Clawdbot macOS IPC architecture (Dec 2025)`
Docs: describe mac XPC setup 2025-12-07 02:27:59 +00:00
chore: rename project to clawdbot 2026-01-04 14:32:47 +00:00			Current model: there is no local control socket and no `clawdbot-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.
chore: share bonjour escapes + refresh webchat bundle 2025-12-13 10:59:48 +00:00
Docs: describe mac XPC setup 2025-12-07 02:27:59 +00:00			`## Goals`
			`- Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).`
refactor(cli): unify on clawdis CLI + node permissions 2025-12-20 02:08:04 +00:00			`- A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.`
Docs: describe mac XPC setup 2025-12-07 02:27:59 +00:00			`- Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.`

			`## How it works`
refactor(cli): unify on clawdis CLI + node permissions 2025-12-20 02:08:04 +00:00			`### Gateway + node bridge (current)`
			`- The app runs the Gateway (local mode) and connects to it as a node.`
			- Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`).
feat(mac): host PeekabooBridge for ui 2025-12-13 16:55:41 +00:00
			`### PeekabooBridge (UI automation)`
			- UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
chore: rename project to clawdbot 2026-01-04 14:32:47 +00:00			`- Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.`
feat(mac): host PeekabooBridge for ui 2025-12-13 16:55:41 +00:00			- Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
docs: make internal links clickable 2026-01-06 18:59:06 +01:00			- See: [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo) for the Clawdbot plan and naming.
feat(mac): host PeekabooBridge for ui 2025-12-13 16:55:41 +00:00
			`### Mach/XPC (future direction)`
refactor(cli): unify on clawdis CLI + node permissions 2025-12-20 02:08:04 +00:00			`- Still optional for internal app services, but not required for automation now that node.invoke is the surface.`
Docs: describe mac XPC setup 2025-12-07 02:27:59 +00:00
			`## Operational flows`
			- Restart/rebuild: `SIGN_IDENTITY="Apple Development: Peter Steinberger (2ZAC4GM7GD)" scripts/restart-mac.sh`
			`- Kills existing instances`
			`- Swift build + package`
			`- Writes/bootstraps/kickstarts the LaunchAgent`
			`- Single instance: app exits early if another instance with the same bundle ID is running.`

			`## Hardening notes`
feat(mac): host PeekabooBridge for ui 2025-12-13 16:55:41 +00:00			`- Prefer requiring a TeamID match for all privileged surfaces.`
refactor(cli): unify on clawdis CLI + node permissions 2025-12-20 02:08:04 +00:00			- PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
Docs: describe mac XPC setup 2025-12-07 02:27:59 +00:00			`- All communication remains local-only; no network sockets are exposed.`
refactor(cli): unify on clawdis CLI + node permissions 2025-12-20 02:08:04 +00:00			- TCC prompts originate only from the GUI app bundle; run `scripts/package-mac-app.sh` so the signed bundle ID stays stable.