92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
---
|
||
name: clawdis-nodes
|
||
description: Discover, interpret, and target Clawdis nodes (paired devices) via the Gateway/CLI. Use when an agent must find available nodes, choose the best target machine, or reason about presence vs node availability (Tailnet/Tailscale optional).
|
||
homepage: https://clawdis.ai
|
||
metadata: {"clawdis":{"emoji":"🛰️"}}
|
||
---
|
||
|
||
# Clawdis Nodes
|
||
|
||
Use the node system to target specific devices (macOS node mode, iOS, Android) for canvas/camera/screen/system actions. Use presence to infer which **user machine** is active, then pick the matching node.
|
||
|
||
## Quick start
|
||
|
||
List known nodes and whether they are paired/connected:
|
||
```bash
|
||
clawdis nodes status
|
||
```
|
||
|
||
Inspect a specific node (commands, caps, permissions):
|
||
```bash
|
||
clawdis nodes describe --node <idOrNameOrIp>
|
||
```
|
||
|
||
## Node discovery workflow (agent)
|
||
|
||
1) **List nodes** with `clawdis nodes status`.
|
||
2) **Choose a target**:
|
||
- Prefer `connected` nodes with the capabilities you need.
|
||
- Use `perms` (permissions map) to avoid asking for actions that will fail.
|
||
3) **Confirm commands** with `clawdis nodes describe --node …`.
|
||
4) **Invoke actions** via `clawdis nodes …` (camera, canvas, screen, system).
|
||
|
||
If no nodes are connected:
|
||
- Check pairing: `clawdis nodes pending` / `clawdis nodes list`
|
||
- Ask the user to open/foreground the node app if the action requires it (canvas/camera/screen on iOS/Android).
|
||
|
||
## Presence vs nodes (don’t confuse them)
|
||
|
||
**Presence** shows Gateway + connected clients (mac app, WebChat, CLI).
|
||
**Nodes** are paired devices that expose commands.
|
||
|
||
Use presence to infer **where the user is active**, then map that to a node:
|
||
|
||
```bash
|
||
clawdis gateway call system-presence
|
||
```
|
||
|
||
Heuristics:
|
||
- Pick the presence entry with the smallest `lastInputSeconds` (most active).
|
||
- Match presence `host` / `deviceFamily` to a node `displayName` / `deviceFamily`.
|
||
- If multiple matches, ask for clarification or use `nodes describe` to choose.
|
||
|
||
Note: CLI connections (`client.mode=cli`) do **not** show up in presence.
|
||
|
||
## Tailnet / Tailscale (optional context)
|
||
|
||
Node discovery is Gateway‑owned; Tailnet details only matter for reaching the Gateway:
|
||
- On LAN, the Gateway advertises a Bridge via Bonjour.
|
||
- Cross‑network, prefer Tailnet MagicDNS or Tailnet IP to reach the Gateway.
|
||
- Once connected, always target nodes by id/name/IP via the Gateway (not direct).
|
||
|
||
## Pairing & approvals
|
||
|
||
List pairing requests:
|
||
```bash
|
||
clawdis nodes pending
|
||
```
|
||
|
||
Approve/reject:
|
||
```bash
|
||
clawdis nodes approve <requestId>
|
||
clawdis nodes reject <requestId>
|
||
```
|
||
|
||
## Typical agent usages
|
||
|
||
Send a notification to a specific Mac node:
|
||
```bash
|
||
clawdis nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
|
||
```
|
||
|
||
Capture a node canvas snapshot:
|
||
```bash
|
||
clawdis nodes canvas snapshot --node <idOrNameOrIp> --format png
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
- `NODE_BACKGROUND_UNAVAILABLE`: the node app must be foregrounded (iOS/Android).
|
||
- Missing permissions in `nodes status`: ask the user to grant permissions in the node app.
|
||
- No connected nodes: ensure the Gateway is reachable; check tailnet/SSH config if remote.
|