Metadata-Version: 2.4
Name: snippbot-device
Version: 0.1.2
Summary: Snippbot device agent - connect any machine to Snippbot
Project-URL: Homepage, https://snippbot.com
Project-URL: Documentation, https://docs.snippbot.com
Project-URL: Repository, https://github.com/snippbot/snippbot
Author: Snippbot Team
License: Proprietary
Keywords: agents,ai,device,remote-execution,snippbot
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: psutil>=5.9
Requires-Dist: pyotp>=2.9
Requires-Dist: rich>=13.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: mss>=9.0; extra == 'all'
Requires-Dist: opencv-python-headless>=4.8; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: playwright>=1.40; extra == 'all'
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: camera
Requires-Dist: opencv-python-headless>=4.8; extra == 'camera'
Provides-Extra: remote
Requires-Dist: mss>=9.0; extra == 'remote'
Requires-Dist: pillow>=10.0; extra == 'remote'
Provides-Extra: screen
Requires-Dist: mss>=9.0; extra == 'screen'
Requires-Dist: pillow>=10.0; extra == 'screen'
Description-Content-Type: text/markdown

# Snippbot Device Agent

Connect any machine to [Snippbot](https://snippbot.com) 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

```bash
pipx install snippbot-device
```

Or in a virtual environment:

```bash
pip install snippbot-device
```

With optional capabilities (use pip in a venv):

```bash
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:

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

### 2. Start the agent

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

### 3. Verify

```bash
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.

```toml
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

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

## See Also

- [Snippbot](https://snippbot.com) - Main project
- [Snippbot Docs](https://docs.snippbot.com) - Full documentation
