Apus macOS IPC architecture

A local Unix socket connects the node host service to the macOS app for exec approvals and system.run. The bundled apus-mac CLI uses a separate local control socket to inspect and configure primary and saved Gateway connections. Agent actions still flow through the Gateway WebSocket and node.invoke. The node-backed computer.act path runs embedded Peekaboo automation in-process. Standalone Peekaboo clients use 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, in-process computer.act, plus PeekabooBridge for standalone UI automation clients.
• Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.

How it works

Gateway + node transport

• 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.present).
• Node commands include canvas.present, canvas.hide, canvas.navigate, camera.list, camera.snap, camera.clip, camera.ptz.status, camera.ptz.control, screen.snapshot, screen.record, computer.act, system.run, and system.notify.
• The node reports a permissions map. Agents use it to see whether screen, camera, microphone, speech, automation, or accessibility access is available.

Node service + app IPC

• A headless node host service connects to the Gateway WebSocket.
• system.run requests are forwarded to the macOS app over a local Unix socket (ExecApprovalsSocket.swift).
• The app performs the exec in UI context, prompts if needed, and returns output.
• The socket owns the request lifetime. Node cancellation or a socket deadline closes the response reader, cancelling the native prompt or command and its process group. Stopping the app's exec server also cancels and drains active requests before releasing its socket lease.
• Clients still half-close their write side after sending one JSONL request. That normal request EOF does not cancel execution. The response reader remains open until the result arrives.

The exec response deadline includes the requested command timeoutMs, the companion's 15-second approval window, and 5 seconds for transport overhead. An omitted timeout keeps the 20-second default; timeoutMs: 0 disables the response deadline while preserving cancellation. After submission, a response deadline reports TIMEOUT and a lost or oversized reply reports UNKNOWN. Both mean the execution outcome is unknown; the command is never replayed locally. COMPANION_APP_UNAVAILABLE is reserved for requests that could not be submitted to the companion.

Diagram (SCI):

Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)

App control socket

apus-mac sends one JSONL request and receives one JSONL response per Unix-domain connection. The running app starts and stops this listener with its exec-approvals lifecycle owner. The shared listener owns the socket path lease, guarded filesystem cleanup, connection framing, and shutdown drainage. It exposes only these operations:

Requests identify the operation with an operation string. Primary SSH settings include sshTarget, optional ports, identityPath, and hostKeyPolicy (strict or openssh). Direct settings include url and an optional tlsFingerprint. Credential-bearing operations accept token or password inside the authenticated request. The CLI reads these from files or stdin. Saved-Gateway requests use name, url, and browser, or idOrName for removal/reconnection. Matching tries an exact ID first, then a unique case-insensitive name. Ambiguity is an error with candidate names/IDs.

The default profile uses ~/.apus/mac-control.sock and ~/.apus/mac-control.token. Named profiles use the corresponding ~/.apus-<name>/ directory. These paths follow AppProfile.stateDirectoryURL, independently of config/state environment overrides. The app owns token creation. The token must be a regular, user-owned file with mode 0600. Missing or unsafe credentials reject requests. Clients must have the app's peer UID (getpeereid). The JSON envelope carries a nonce, millisecond timestamp, encoded request, and HMAC-SHA256 over the nonce, timestamp, and exact request bytes. Requests have a 15-second authentication TTL. A successfully authenticated browser sign-in may remain open for the coordinator's bounded 300-second operation.

Socket responses use {ok:true,result:...} or {ok:false,error:{code,message}}. The CLI's --json success output unwraps result. status contains:

• primary: mode, nullable transport, URL, optional SSH target/remote port, tunnel state/local port, and connection state/version/error.
• gateways: ID, name, URL, authentication kind (token, password, or browser), optional Cloudflare Access identity subject/expiry, and connection state/error.
• app: version, build, and profile.

Responses never include tokens, passwords, browser-session credentials, or Keychain contents. Saved-Gateway mutations execute inside the signed app, where the profile store owns Keychain access, connection retirement, dashboard cookies, and device-token cleanup. The CLI never writes the saved-Gateway registry.

See remote control for shell examples, profile selection, safe credential input, and background app launch.

PeekabooBridge (UI automation)

• The built-in agent computer tool does not use this socket. A paired macOS node fulfills computer.act in the app process with embedded Peekaboo services.
• UI automation uses a separate UNIX socket (~/Library/Application Support/Apus/<socket>) and the PeekabooBridge JSON protocol.
• Host preference order (client-side): Peekaboo.app -> Claude.app -> Apus.app -> local execution.
• Security: bridge hosts require the exact signed Peekaboo client bundle identifier and Peekaboo's canonical current/legacy release signer set. PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 guards a DEBUG-only same-UID escape hatch (Peekaboo convention).
• See: PeekabooBridge usage for details.

Operational flows

• Restart/rebuild: scripts/restart-mac.sh kills existing instances, rebuilds via Swift, repackages, and relaunches. It auto-detects an available signing identity. It falls back to --no-sign if it finds no identity. Pass --sign to require signing, which fails if no key is available. Pass --no-sign to force the unsigned path. Packaging preserves an explicit SIGN_IDENTITY. Otherwise scripts/codesign-mac-app.sh auto-detects the certificate.
• Single instance: the app checks NSWorkspace.runningApplications for a duplicate bundle ID. It exits if it finds more than one instance (isDuplicateInstance() in MenuBar.swift).

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. Keep the signed bundle ID stable across rebuilds.
• Exec approvals socket hardening: file mode 0600, shared token stored in the exec_approvals_config row of state/apus.sqlite, peer-UID check (getpeereid), HMAC-SHA256 challenge/response, and a short TTL on requests.

Related

• macOS app
• macOS IPC flow (Exec approvals)