Working with Nodes: Remote System Integration

What Are Nodes?

Nodes are remote devices or systems connected to Clawdbot:

• Mac computers


• Linux servers


• Mobile devices


• IoT devices

They extend your capabilities beyond the local system.

Node Actions

Status

Check node status:

nodes(action="status")

Returns list of connected nodes with their capabilities.

Describe

Get node details:

nodes(action="describe", node="Mac-Studio")

Run Commands

Execute on remote node:

nodes(action="run", node="Mac-Studio", command=["ls", "-la"])

Node Capabilities

Nodes can provide:

• run: Execute commands


• camera: Take photos/video


• screen: Screen recording


• location: GPS location


• notify: Send notifications

Running Commands

Simple Command

nodes(action="run", 
  node="Mac-Studio",
  command=["echo", "Hello from node"]
)

With Working Directory

nodes(action="run",
  node="Mac-Studio",
  command=["git", "status"],
  cwd="/path/to/project"
)

With Environment

nodes(action="run",
  node="Mac-Studio",
  command=["./script.sh"],
  env=["API_KEY=xxx"]
)

Camera Access

Take Photo

nodes(action="camera_snap",
  node="iPhone",
  facing="back"  // or "front" or "both"
)

Camera List

nodes(action="camera_list", node="Mac-Studio")

Video Clip

nodes(action="camera_clip",
  node="iPhone",
  durationMs=5000
)

Screen Recording

nodes(action="screen_record",
  node="Mac-Studio",
  durationMs=10000
)

Location

nodes(action="location_get", node="iPhone")

Returns GPS coordinates.

Notifications

Send notification to device:

nodes(action="notify",
  node="iPhone",
  title="Reminder",
  body="Your meeting starts in 5 minutes"
)

Practical Uses

Mac-Specific Tasks

For macOS-only operations:

nodes(action="run",
  node="Mac-Studio",
  command=["osascript", "-e", "tell app \"Music\" to play"]
)

Server Tasks

For server management:

nodes(action="run",
  node="home-server",
  command=["docker", "compose", "restart"]
)

Mobile Integration

Camera from phone:

nodes(action="camera_snap",
  node="iPhone",
  facing="back"
)

Security

Node Approval

Nodes must be approved before use:

nodes(action="pending")  // See pending nodes
nodes(action="approve", requestId="...")

Command Safety

Be careful with remote commands:

• Don't run destructive commands


• Verify before executing


• Limit to necessary operations

Troubleshooting

Node Not Responding

Check:

• Network connectivity


• Node app running


• Pairing status

Command Failures

// Use timeout for long commands
nodes(action="run",
  node="...",
  command=["..."],
  commandTimeoutMs=60000
)

Camera Access

Verify:

• Camera permissions granted


• Camera not in use


• Device awake

Best Practices

Document Your Nodes

In TOOLS.md:

### Nodes
- Mac-Studio: Main workstation, macOS tasks
- home-server: Docker, backups
- iPhone: Camera, location, notifications

Use Specific Commands

// Good: specific and safe
command=["cat", "/var/log/app.log"]

// Risky: shell interpretation
command=["sh", "-c", "cat /var/log/*"]

Handle Timeouts

Long operations need timeout:

nodes(action="run",
  command=["long-running-script.sh"],
  commandTimeoutMs=300000  // 5 minutes
)

Common Patterns

Cross-Platform Scripts

// Check OS and run appropriate command
if (node.os === "macos") {
  nodes(action="run", command=["open", file])
} else {
  nodes(action="run", command=["xdg-open", file])
}

Periodic Monitoring

// In heartbeat, check server health
nodes(action="run",
  node="server",
  command=["systemctl", "status", "app"]
)

Camera Security

// Take a snapshot when triggered
nodes(action="camera_snap",
  node="security-camera",
  facing="back"
)

Conclusion

Nodes extend Clawdbot's reach:

• Remote command execution


• Camera access


• Location services


• Cross-device notifications

Use them to integrate with the physical world.

---

Next: Clawdbot Memory Systems - Advanced memory management