agentwatch-cli 0.1.0__tar.gz

agentwatch_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AgentWatch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentwatch_cli-0.1.0/PKG-INFO

@@ -0,0 +1,461 @@
+Metadata-Version: 2.4
+Name: agentwatch-cli
+Version: 0.1.0
+Summary: Connect your local Moltbot gateway to AgentWatch cloud
+Home-page: https://github.com/helivan-research/agentwatch-cli
+Author: AgentWatch
+Author-email: AgentWatch <support@agentwatch.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/helivan-research/agentwatch-cli
+Project-URL: Documentation, https://docs.agentwatch.io/agentwatch-cli
+Project-URL: Repository, https://github.com/helivan-research/agentwatch-cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-socketio>=5.8.0
+Requires-Dist: websockets<15.1,>=12.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# agentwatch-cli
+
+[![PyPI version](https://badge.fury.io/py/agentwatch-cli.svg)](https://badge.fury.io/py/agentwatch-cli)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Connect your local Moltbot (OpenClaw) gateway to AgentWatch cloud without exposing your local network.
+
+## Overview
+
+`agentwatch-cli` is a secure bridge that allows AgentWatch to communicate with your locally-running Moltbot gateway. Instead of exposing your local network, the connector establishes an outbound WebSocket connection to AgentWatch cloud and relays messages between the two.
+
+**Architecture:**
+```
+AgentWatch Cloud <--WebSocket--> agentwatch-cli <--HTTP--> Local Moltbot Gateway
+     (cloud)                     (your machine)              (your machine)
+```
+
+**Key Benefits:**
+- **No port forwarding required** - All connections are outbound
+- **Secure** - TLS encryption, credentials never stored in plain text
+- **Automatic reconnection** - Handles network interruptions gracefully
+- **Service mode** - Runs in background, starts on boot
+
+## Requirements
+
+- Python 3.9 or higher
+- A running Moltbot (OpenClaw) gateway on your local machine
+- An AgentWatch account with a custom agent configured
+
+## Installation
+
+### macOS
+
+**Option 1: Using pipx (Recommended)**
+```bash
+# Install pipx if you don't have it
+brew install pipx
+pipx ensurepath
+
+# Install agentwatch-cli
+pipx install agentwatch-cli
+```
+
+**Option 2: Using pip**
+```bash
+pip install --user agentwatch-cli
+
+# Add to PATH (add this line to ~/.zshrc for persistence)
+export PATH="$HOME/Library/Python/3.11/bin:$PATH"
+```
+
+Note: Replace `3.11` with your Python version (check with `python3 --version`).
+
+### Linux (Ubuntu/Debian)
+
+**Option 1: Using pipx (Recommended)**
+```bash
+# Install pipx if you don't have it
+sudo apt install pipx
+pipx ensurepath
+
+# Install agentwatch-cli
+pipx install agentwatch-cli
+```
+
+**Option 2: Using pip**
+```bash
+pip install --user agentwatch-cli
+```
+
+The script is installed to `~/.local/bin/` which should already be in your PATH.
+
+### Linux (Fedora/RHEL)
+
+```bash
+# Install pipx
+sudo dnf install pipx
+pipx ensurepath
+
+# Install agentwatch-cli
+pipx install agentwatch-cli
+```
+
+### Verify Installation
+
+```bash
+agentwatch-cli --version
+```
+
+If you get "command not found", ensure your PATH includes the installation directory:
+```bash
+# For pip --user installs:
+# macOS: ~/Library/Python/3.X/bin
+# Linux: ~/.local/bin
+
+# For pipx installs:
+# Usually ~/.local/bin (run `pipx ensurepath` to fix)
+```
+
+## Quick Start
+
+### 1. Create a Custom Agent in AgentWatch
+
+1. Go to AgentWatch and navigate to **Custom Agents**
+2. Click **Add Agent** and select **Moltbot**
+3. You'll receive an 8-character enrollment code (e.g., `ABCD-1234`)
+
+### 2. Enroll the Connector
+
+```bash
+agentwatch-cli enroll --code ABCD-1234
+```
+
+This will:
+- Register your connector with AgentWatch
+- Auto-discover your gateway token from `~/.openclaw/openclaw.json`
+- Enable the HTTP chat completions endpoint in OpenClaw (if needed)
+- Save configuration to `~/.agentwatch-cli/config.json`
+
+### 3. Install as a Service (Recommended)
+
+```bash
+# Linux (requires sudo)
+sudo agentwatch-cli install-service
+
+# macOS (no sudo needed - uses launchd)
+agentwatch-cli install-service
+```
+
+That's it! The connector will now:
+- Start automatically on boot
+- Run in the background
+- Reconnect automatically if disconnected
+
+### Alternative: Run Manually
+
+```bash
+agentwatch-cli start
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `enroll` | Enroll with an enrollment code from AgentWatch |
+| `start` | Start the connector manually |
+| `status` | Check connector status and gateway connectivity |
+| `config` | Update configuration settings |
+| `revoke` | Revoke enrollment and clear credentials |
+| `install-service` | Install as a system service (auto-start) |
+| `uninstall-service` | Remove the system service |
+| `service-status` | Check if the background service is running |
+
+### enroll
+
+Enroll the connector with an enrollment code from AgentWatch.
+
+```bash
+agentwatch-cli enroll --code ABCD-1234
+```
+
+### start
+
+Start the connector and begin relaying messages.
+
+```bash
+agentwatch-cli start
+
+# With custom gateway URL (if not localhost)
+agentwatch-cli start --gateway-url http://192.168.1.100:18789
+
+# With explicit gateway token
+agentwatch-cli start --gateway-token your-token-here
+```
+
+### status
+
+Check the connector status and test gateway connectivity.
+
+```bash
+agentwatch-cli status
+```
+
+Example output:
+```
+AgentWatch CLI Connector Status
+========================================
+Enrolled: Yes
+Agent: My Moltbot
+Agent ID: abc123...
+Connector ID: def456...
+
+Gateway URL: http://127.0.0.1:18789
+AgentWatch URL: wss://agentwatch.helivan.io
+Gateway Token: <auto-discovered>
+
+Testing gateway connection...
+Gateway Status: ONLINE
+```
+
+### config
+
+Configure connector settings.
+
+```bash
+# Set gateway URL (for remote gateways)
+agentwatch-cli config --gateway-url http://192.168.1.100:18789
+
+# Set gateway token explicitly
+agentwatch-cli config --gateway-token your-token-here
+
+# Set AgentWatch cloud URL (for self-hosted deployments)
+agentwatch-cli config --agentwatch-url wss://your-agentwatch-instance.com
+```
+
+### revoke
+
+Revoke enrollment and clear credentials.
+
+```bash
+agentwatch-cli revoke
+
+# Skip confirmation prompt
+agentwatch-cli revoke --force
+```
+
+### install-service
+
+Install as a system service for automatic startup.
+
+**Linux (systemd):**
+```bash
+# Requires sudo
+sudo agentwatch-cli install-service
+
+# Specify user (default: current user)
+sudo agentwatch-cli install-service --user myuser
+```
+
+**macOS (launchd):**
+```bash
+# No sudo needed - installs to ~/Library/LaunchAgents
+agentwatch-cli install-service
+```
+
+### uninstall-service
+
+Remove the system service.
+
+```bash
+# Linux
+sudo agentwatch-cli uninstall-service
+
+# macOS
+agentwatch-cli uninstall-service
+```
+
+### service-status
+
+Check if the service is running.
+
+```bash
+agentwatch-cli service-status
+```
+
+## Configuration
+
+Configuration is stored in `~/.agentwatch-cli/config.json`:
+
+```json
+{
+  "connector_id": "uuid",
+  "secret": "encrypted-secret",
+  "agent_id": "uuid",
+  "agent_name": "My Moltbot",
+  "gateway_url": "http://127.0.0.1:18789",
+  "gateway_token": null,
+  "agentwatch_url": "wss://agentwatch.helivan.io"
+}
+```
+
+### Gateway Token Auto-Discovery
+
+If `gateway_token` is `null`, the connector automatically discovers the token from `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "gateway": {
+    "auth": {
+      "token": "your-gateway-token"
+    }
+  }
+}
+```
+
+This is the recommended approach - the token is read fresh each time, so if OpenClaw rotates it, the connector automatically uses the new one.
+
+## How It Works
+
+1. **Enrollment**: When you run `enroll`, the CLI exchanges the one-time enrollment code for permanent credentials (connector_id + secret).
+
+2. **Connection**: On `start`, the connector establishes a WebSocket connection to AgentWatch cloud, authenticating with its credentials.
+
+3. **Message Relay**: When a user sends a message to your custom agent in AgentWatch:
+   - AgentWatch sends the request through the WebSocket to your connector
+   - The connector forwards it to your local Moltbot gateway via HTTP
+   - The response flows back through the same path
+
+4. **Streaming**: For streaming responses, the connector handles chunked responses and forwards them in real-time.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGENTWATCH_ENROLLMENT_URL` | Override the enrollment API URL (for testing/self-hosted) |
+
+## Security
+
+- **Credentials protected**: Config file has restricted permissions (0600)
+- **No plain text secrets**: The connector secret is hashed on the cloud side
+- **TLS encryption**: All WebSocket and HTTP communication is encrypted
+- **Outbound only**: No inbound ports required - the connector initiates all connections
+
+## Troubleshooting
+
+### "Cannot connect to local gateway"
+
+Ensure your Moltbot gateway is running:
+```bash
+# Check if gateway is listening
+curl http://127.0.0.1:18789/v1/models
+```
+
+If you get a connection refused error, start your Moltbot/OpenClaw gateway.
+
+### "Invalid enrollment code"
+
+- Enrollment codes expire after 24 hours
+- Each code can only be used once
+- Generate a new code in AgentWatch if yours has expired
+
+### "Authentication failed"
+
+Your connector credentials may have been revoked. Re-enroll:
+```bash
+agentwatch-cli revoke --force
+agentwatch-cli enroll --code NEW_CODE
+```
+
+### "command not found: agentwatch-cli"
+
+The CLI isn't in your PATH. Add the installation directory:
+
+**macOS (pip --user):**
+```bash
+echo 'export PATH="$HOME/Library/Python/3.11/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Linux (pip --user):**
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**pipx:**
+```bash
+pipx ensurepath
+# Then restart your terminal
+```
+
+### Service won't start
+
+Check the service logs:
+
+**Linux:**
+```bash
+sudo journalctl -u agentwatch-cli -f
+```
+
+**macOS:**
+```bash
+cat ~/Library/Logs/agentwatch-cli.log
+```
+
+## Upgrading
+
+**pipx:**
+```bash
+pipx upgrade agentwatch-cli
+```
+
+**pip:**
+```bash
+pip install --user --upgrade agentwatch-cli
+```
+
+After upgrading, restart the service if installed:
+```bash
+# Linux
+sudo systemctl restart agentwatch-cli
+
+# macOS
+launchctl unload ~/Library/LaunchAgents/io.agentwatch.cli.plist
+launchctl load ~/Library/LaunchAgents/io.agentwatch.cli.plist
+```
+
+## Uninstalling
+
+```bash
+# Remove service first (if installed)
+agentwatch-cli uninstall-service  # or with sudo on Linux
+
+# Remove package
+pipx uninstall agentwatch-cli
+# or
+pip uninstall agentwatch-cli
+
+# Optionally remove config
+rm -rf ~/.agentwatch-cli
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/helivan-research/agentwatch-cli/issues)
+- **Documentation**: [docs.agentwatch.io](https://docs.agentwatch.io)