Nodes

एक node एक companion device (macOS/iOS/Android/headless) है जो Gateway WebSocket (operators के समान port) से role: "node" के साथ connect होता है और node.invoke के माध्यम से एक command surface (जैसे canvas.*, camera.*, system.*) expose करता है। Protocol विवरण: Gateway protocol।

Legacy transport: Bridge protocol (TCP JSONL; deprecated/वर्तमान nodes के लिए removed)।

macOS node mode में भी चल सकता है: menubar app Gateway के WS server से connect होता है और अपने स्थानीय canvas/camera commands को एक node के रूप में expose करता है (ताकि mayros nodes … इस Mac के खिलाफ काम करे)।

नोट्स:

  • Nodes peripherals हैं, gateways नहीं। वे gateway service नहीं चलाते।
  • Telegram/WhatsApp/आदि संदेश gateway पर land होते हैं, nodes पर नहीं।
  • Troubleshooting runbook: /nodes/troubleshooting

Pairing + status

WS nodes device pairing का उपयोग करते हैं। Nodes connect के दौरान device identity present करते हैं; Gateway role: node के लिए device pairing request बनाता है। Devices CLI (या UI) के माध्यम से approve करें।

Quick CLI:

bash
mayros devices list
mayros devices approve <requestId>
mayros devices reject <requestId>
mayros nodes status
mayros nodes describe --node <idOrNameOrIp>

नोट्स:

  • nodes status एक node को paired के रूप में mark करता है जब इसकी device pairing role में node शामिल हो।
  • node.pair.* (CLI: mayros nodes pending/approve/reject) एक अलग gateway-owned node pairing store है; यह WS connect handshake को gate नहीं करता।

Remote node host (system.run)

जब आपका Gateway एक मशीन पर चलता है और आप commands को दूसरी पर execute करना चाहते हैं तो node host का उपयोग करें। Model अभी भी gateway से बात करता है; gateway exec calls को node host पर forward करता है जब host=node selected हो।

क्या कहां चलता है

  • Gateway host: संदेश receive करता है, model चलाता है, tool calls को route करता है।
  • Node host: node मशीन पर system.run/system.which execute करता है।
  • Approvals: ~/.mayros/exec-approvals.json के माध्यम से node host पर enforced।

Node host शुरू करें (foreground)

Node मशीन पर:

bash
mayros node run --host <gateway-host> --port 18789 --display-name "Build Node"

SSH tunnel के माध्यम से Remote gateway (loopback bind)

यदि Gateway loopback से bind करता है (gateway.bind=loopback, local mode में डिफ़ॉल्ट), तो remote node hosts सीधे connect नहीं हो सकते। एक SSH tunnel बनाएं और node host को tunnel के स्थानीय end पर point करें।

उदाहरण (node host -> gateway host):

bash
# Terminal A (चलता रहे): local 18790 -> gateway 127.0.0.1:18789 forward करें
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: gateway token export करें और tunnel के माध्यम से connect करें
export MAYROS_GATEWAY_TOKEN="<gateway-token>"
mayros node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

नोट्स:

  • Token gateway config (~/.mayros/mayros.json gateway host पर) से gateway.auth.token है।
  • mayros node run auth के लिए MAYROS_GATEWAY_TOKEN पढ़ता है।

Node host शुरू करें (service)

bash
mayros node install --host <gateway-host> --port 18789 --display-name "Build Node"
mayros node restart

Pair + नाम

Gateway host पर:

bash
mayros nodes pending
mayros nodes approve <requestId>
mayros nodes list

नामकरण विकल्प:

  • mayros node run / mayros node install पर --display-name (node पर ~/.mayros/node.json में persist होता है)।
  • mayros nodes rename --node <id|name|ip> --name "Build Node" (gateway override)।

Commands को allowlist करें

Exec approvals प्रति node host हैं। Gateway से allowlist entries जोड़ें:

bash
mayros approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
mayros approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

Approvals node host पर ~/.mayros/exec-approvals.json में रहते हैं।

Exec को node पर point करें

Defaults configure करें (gateway config):

bash
mayros config set tools.exec.host node
mayros config set tools.exec.security allowlist
mayros config set tools.exec.node "<id-or-name>"

या प्रति session:

/exec host=node security=allowlist node=<id-or-name>

एक बार set होने पर, host=node के साथ कोई भी exec call node host पर चलता है (node allowlist/approvals के अधीन)।

संबंधित:

Commands invoke करना

Low-level (raw RPC):

bash
mayros nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

सामान्य "एजेंट को MEDIA attachment दें" workflows के लिए higher-level helpers मौजूद हैं।

Screenshots (canvas snapshots)

यदि node Canvas (WebView) दिखा रहा है, तो canvas.snapshot { format, base64 } return करता है।

CLI helper (temp file में लिखता है और MEDIA:<path> print करता है):

bash
mayros nodes canvas snapshot --node <idOrNameOrIp> --format png
mayros nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas controls

bash
mayros nodes canvas present --node <idOrNameOrIp> --target https://example.com
mayros nodes canvas hide --node <idOrNameOrIp>
mayros nodes canvas navigate https://example.com --node <idOrNameOrIp>
mayros nodes canvas eval --node <idOrNameOrIp> --js "document.title"

नोट्स:

  • canvas present URLs या local file paths (--target) स्वीकार करता है, साथ ही positioning के लिए वैकल्पिक --x/--y/--width/--height।
  • canvas eval inline JS (--js) या positional arg स्वीकार करता है।

A2UI (Canvas)

bash
mayros nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
mayros nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
mayros nodes canvas a2ui reset --node <idOrNameOrIp>

नोट्स:

  • केवल A2UI v0.8 JSONL supported है (v0.9/createSurface rejected है)।

Photos + videos (node camera)

Photos (jpg):

bash
mayros nodes camera list --node <idOrNameOrIp>
mayros nodes camera snap --node <idOrNameOrIp>            # डिफ़ॉल्ट: दोनों facings (2 MEDIA lines)
mayros nodes camera snap --node <idOrNameOrIp> --facing front

Video clips (mp4):

bash
mayros nodes camera clip --node <idOrNameOrIp> --duration 10s
mayros nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

नोट्स:

  • Node को canvas.* और camera.* के लिए foregrounded होना चाहिए (background calls NODE_BACKGROUND_UNAVAILABLE return करते हैं)।
  • Clip duration clamped है (वर्तमान में <= 60s) oversized base64 payloads से बचने के लिए।
  • Android संभव होने पर CAMERA/RECORD_AUDIO permissions के लिए prompt करेगा; denied permissions *_PERMISSION_REQUIRED के साथ fail होते हैं।

Screen recordings (nodes)

Nodes screen.record (mp4) expose करते हैं। उदाहरण:

bash
mayros nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
mayros nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

नोट्स:

  • screen.record के लिए node app को foregrounded होना आवश्यक है।
  • Android recording से पहले system screen-capture prompt दिखाएगा।
  • Screen recordings <= 60s तक clamped हैं।
  • --no-audio microphone capture disable करता है (iOS/Android पर supported; macOS system capture audio का उपयोग करता है)।
  • कई screens उपलब्ध होने पर display select करने के लिए --screen <index> का उपयोग करें।

Location (nodes)

Nodes location.get expose करते हैं जब Location settings में enabled हो।

CLI helper:

bash
mayros nodes location get --node <idOrNameOrIp>
mayros nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

नोट्स:

  • Location डिफ़ॉल्ट रूप से off है।
  • "Always" के लिए system permission आवश्यक है; background fetch best-effort है।
  • Response में lat/lon, accuracy (meters) और timestamp शामिल हैं।

SMS (Android nodes)

Android nodes sms.send expose कर सकते हैं जब user SMS permission grant करता है और device telephony support करता है।

Low-level invoke:

bash
mayros nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Mayros"}'

नोट्स:

  • Permission prompt को capability advertise होने से पहले Android device पर accept किया जाना चाहिए।
  • Telephony के बिना Wi-Fi-only devices sms.send advertise नहीं करेंगे।

System commands (node host / mac node)

macOS node system.run, system.notify और system.execApprovals.get/set expose करता है। Headless node host system.run, system.which और system.execApprovals.get/set expose करता है।

उदाहरण:

bash
mayros nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
mayros nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

नोट्स:

  • system.run payload में stdout/stderr/exit code return करता है।
  • system.notify macOS app पर notification permission state का सम्मान करता है।
  • system.run --cwd, --env KEY=VAL, --command-timeout और --needs-screen-recording support करता है।
  • system.notify --priority <passive|active|timeSensitive> और --delivery <system|overlay|auto> support करता है।
  • Node hosts PATH overrides को ignore करते हैं। यदि आपको अतिरिक्त PATH entries की आवश्यकता है, तो --env के माध्यम से PATH pass करने के बजाय node host service environment configure करें (या standard locations में tools install करें)।
  • macOS node mode पर, system.run macOS app में exec approvals (Settings → Exec approvals) द्वारा gated है। Ask/allowlist/full headless node host के समान व्यवहार करते हैं; denied prompts SYSTEM_RUN_DENIED return करते हैं।
  • Headless node host पर, system.run exec approvals (~/.mayros/exec-approvals.json) द्वारा gated है।

Exec node binding

जब कई nodes उपलब्ध हों, तो आप exec को एक specific node से bind कर सकते हैं। यह exec host=node के लिए default node set करता है (और प्रति agent override किया जा सकता है)।

Global default:

bash
mayros config set tools.exec.node "node-id-or-name"

प्रति-agent override:

bash
mayros config get agents.list
mayros config set agents.list[0].tools.exec.node "node-id-or-name"

Unset करें ताकि कोई भी node अनुमत हो:

bash
mayros config unset tools.exec.node
mayros config unset agents.list[0].tools.exec.node

Permissions map

Nodes node.list / node.describe में permissions map शामिल कर सकते हैं, permission name (जैसे screenRecording, accessibility) द्वारा keyed boolean values (true = granted) के साथ।

Headless node host (cross-platform)

Mayros एक headless node host (कोई UI नहीं) चला सकता है जो Gateway WebSocket से connect होता है और system.run / system.which expose करता है। यह Linux/Windows पर या server के साथ एक minimal node चलाने के लिए उपयोगी है।

इसे शुरू करें:

bash
mayros node run --host <gateway-host> --port 18789

नोट्स:

  • Pairing अभी भी आवश्यक है (Gateway एक node approval prompt दिखाएगा)।
  • Node host अपनी node id, token, display name और gateway connection info को ~/.mayros/node.json में store करता है।
  • Exec approvals स्थानीय रूप से ~/.mayros/exec-approvals.json के माध्यम से enforced हैं (Exec approvals देखें)।
  • macOS पर, headless node host reachable होने पर companion app exec host को prefer करता है और app unavailable होने पर local execution पर fall back करता है। App को require करने के लिए MAYROS_NODE_EXEC_HOST=app set करें, या fallback disable करने के लिए MAYROS_NODE_EXEC_FALLBACK=0।
  • Gateway WS TLS का उपयोग करते समय --tls / --tls-fingerprint जोड़ें।

Mac node mode

  • macOS menubar app Gateway WS server से एक node के रूप में connect होता है (ताकि mayros nodes … इस Mac के खिलाफ काम करे)।
  • Remote mode में, app Gateway port के लिए एक SSH tunnel खोलता है और localhost से connect होता है।