snippbot-device 0.1.5

Snippbot device agent - connect any machine to Snippbot

Snippbot Device Agent

Connect any machine to Snippbot as a remote execution node.

What It Does

The device agent runs on a remote machine and connects back to your Snippbot daemon via WebSocket. Once paired, the AI agent can route tool calls — shell commands, file operations, screenshots, browser automation — to the remote device.

Installation

pipx install snippbot-device

Or in a virtual environment:

pip install snippbot-device

With optional capabilities (use pip in a venv):

pip install snippbot-device[screen]    # Screenshots (Pillow + mss)
pip install snippbot-device[browser]   # Browser automation (Playwright)
pip install snippbot-device[camera]    # Camera capture (OpenCV)
pip install snippbot-device[all]       # All optional capabilities

Requires Python 3.11 or higher.

Quick Start

1. Pair with your Snippbot daemon

From the Snippbot UI, click Pair Device to generate a 6-digit pairing code. Then on the remote machine:

snippbot-device pair --host DAEMON_IP --port 18781 --code XXXXXX

2. Start the agent

snippbot-device start        # Background (daemonized)
snippbot-device start -f     # Foreground (see logs)

3. Verify

snippbot-device status       # Check connection and resource usage
snippbot-device capabilities # List detected capabilities

Commands

snippbot-device pair          Pair this device with a Snippbot daemon
snippbot-device start         Start the device agent
snippbot-device stop          Stop the running agent
snippbot-device status        Show agent status and connection info
snippbot-device capabilities  List detected capabilities

Capabilities

The agent auto-detects what the machine can do:

Capability	Requirement	Description
execution.bash	Built-in	Shell commands (bash, zsh, cmd)
execution.python	Built-in	Python script execution
filesystem.read	Built-in	Read files
filesystem.write	Built-in	Write files
filesystem.transfer	Built-in	Send/receive files to daemon
system.info	Built-in	OS, CPU, memory, disk info
capture.screenshot	[screen] extra	Take screenshots
capture.camera_photo	[camera] extra	Camera capture
browser.navigate	[browser] extra	Browser automation
display.remote_view	[remote] extra	Screen streaming
execution.docker	Docker CLI in PATH	Docker container management

Configuration

Config is stored at ~/.snippbot-device/config.toml after pairing.

daemon_host = "192.168.1.100"
daemon_ws_port = 18781
device_name = "my-laptop"
device_token = "device_..."
device_id = "..."
max_concurrent_tasks = 4
heartbeat_interval = 15
auto_update = true

How It Works

1. The agent connects to the daemon via WebSocket (ws://host:port/ws/device)
2. Authenticates using the token received during pairing
3. Advertises its capabilities (what tools it can execute)
4. Enters a message loop waiting for tool requests
5. Sends heartbeats every 15 seconds with CPU/memory/disk metrics
6. Auto-reconnects with exponential backoff if the connection drops

Security

• Device tokens are stored locally and validated on each connection
• Environment variables matching *_KEY, *_SECRET, *_TOKEN, *_PASSWORD are stripped from command execution
• File operations are restricted to allowed paths (configurable)
• Execution timeout: 5 minutes max per tool call
• Output limit: 1 MB per result

Logs

# Foreground mode: logs to stdout
# Background mode: logs to ~/.snippbot-device/agent.log
tail -f ~/.snippbot-device/agent.log

See Also

• Snippbot - Main project
• Snippbot Docs - Full documentation