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 configure     Change the daemon address or Cloudflare Access token
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:

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

Connecting Through a Tunnel

To reach the daemon from outside its LAN, give the agent a full WebSocket URL instead of a host and port. If the hostname is protected by Cloudflare Access, also give it a service token. The token needs an Access policy with the Service Auth action on that application.

snippbot-device configure --url wss://daemon.example.com/device/ws \
    --cf-access-client-id <CLIENT_ID>          # prompts for the secret
snippbot-device stop && snippbot-device start

This doesn't need re-pairing, because the device authenticates with its token, not its address. snippbot-device configure --local switches back to the paired host and port, and --clear-cf-access removes the token. You can also pair through the tunnel with snippbot-device pair --url <wss-url>; run configure first if the tunnel needs an Access token.

The settings are stored in the [connection] section:

daemon_url = "wss://daemon.example.com/device/ws"
cf_access_client_id = "....access"
cf_access_client_secret = "..."

On Windows, Ctrl+V doesn't paste into the hidden secret prompt; right-click to paste instead.

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