41 lines
2.4 KiB
Markdown
41 lines
2.4 KiB
Markdown
---
|
|
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`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) so the signed bundle ID stays stable.
|