clawdbot/docs/ios/connect.md

summary, read_when

summary	read_when
Runbook: connect/pair the iOS node (Iris) to a Clawdis Gateway and drive its Canvas	Pairing or reconnecting the iOS node Debugging iOS bridge discovery or auth Sending screen/canvas commands to iOS

iOS Node Connection Runbook (Iris)

This is the practical “how do I connect Iris” guide:

iOS app ⇄ (Bonjour + TCP bridge) ⇄ Gateway bridge ⇄ (loopback WS) ⇄ Gateway

The Gateway WebSocket stays loopback-only (ws://127.0.0.1:18789). Iris talks to the LAN-facing bridge (default tcp://0.0.0.0:18790) and uses Gateway-owned pairing.

Prerequisites

• You can run the Gateway on the “master” machine.
• Iris (iOS app) is on the same LAN (Bonjour/mDNS must work).
• You can run the CLI (clawdis) on the gateway machine (or via SSH).

1) Start the Gateway (with bridge enabled)

Bridge is enabled by default (disable via CLAWDIS_BRIDGE_ENABLED=0).

pnpm clawdis gateway --port 18789 --verbose

Confirm in logs you see something like:

• bridge listening on tcp://0.0.0.0:18790 (Iris)

2) Verify Bonjour discovery (optional but recommended)

From the gateway machine:

dns-sd -B _clawdis-bridge._tcp local.

You should see your gateway advertising _clawdis-bridge._tcp.

If browse works, but Iris can’t connect, try resolving one instance:

dns-sd -L "<instance name>" _clawdis-bridge._tcp local.

More debugging notes: docs/bonjour.md.

3) Connect from Iris (iOS)

In Iris:

• Pick the discovered bridge (or hit refresh).
• If not paired yet, Iris will initiate pairing automatically.
• After the first successful pairing, Iris will auto-reconnect to the last bridge on launch (including after reinstall), as long as the iOS Keychain entry is still present.

Connection indicator (always visible)

The Settings tab icon shows a small status dot:

• Green: connected to the bridge
• Yellow: connecting
• Red: not connected / error

4) Approve pairing (CLI)

On the gateway machine:

clawdis nodes pending

Approve the request:

clawdis nodes approve <requestId>

After approval, Iris receives/stores the token and reconnects authenticated.

Pairing details: docs/gateway/pairing.md.

5) Verify the node is connected

• In the macOS app: Instances tab should show something like iOS Node (...).
• Via nodes list (paired + connected):

  clawdis nodes list
  

• Via Gateway (paired + connected):

  clawdis gateway call node.list --params "{}"
  

• Via Gateway presence (legacy-ish, still useful):

  clawdis gateway call system-presence --params "{}"
  

  Look for the node instanceId (often a UUID).

6) Drive the iOS Canvas (draw / snapshot)

Iris runs a WKWebView “Canvas” scaffold which exposes:

• window.__clawdis.canvas
• window.__clawdis.ctx (2D context)
• window.__clawdis.setStatus(title, subtitle)

Draw with screen.eval

clawdis nodes invoke --node "iOS Node" --command screen.eval --params "$(cat <<'JSON'
{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdis; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"}
JSON
)"

Snapshot with screen.snapshot

clawdis nodes invoke --node 192.168.0.88 --command screen.snapshot --params '{"maxWidth":900}'

The response includes base64 PNG data (for debugging/verification).

Common gotchas

• iOS in background: all screen.* commands fail fast with NODE_BACKGROUND_UNAVAILABLE (bring Iris to foreground).
• mDNS blocked: some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see docs/discovery.md).
• Wrong node selector: --node can be the node id (UUID), display name (e.g. iOS Node), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
• Stale pairing / Keychain cleared: if the pairing token is missing (or iOS Keychain was wiped), Iris must pair again; approve a new pending request.
• App reinstall but no reconnect: Iris restores instanceId + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.

Related docs

• docs/ios/spec.md (design + architecture)
• docs/gateway.md (gateway runbook)
• docs/gateway/pairing.md (approval + storage)
• docs/bonjour.md (discovery debugging)
• docs/discovery.md (LAN vs tailnet vs SSH)