Add comprehensive deployment documentation

DEPLOYMENT.md

+# Hermes Node Protocol - Deployment Guide
+
+**Version:** 1.0  
+**Date:** 2026-04-29
+
+Complete deployment guide for setting up the Hermes Node Protocol — a reverse-connection node execution system that replaces OpenClaw sexec with a WebSocket-based architecture.
+
+---
+
+## Overview
+
+The Hermes Node Protocol enables remote command execution without SSH keys. Nodes connect to a central gateway via WebSocket, and commands are routed through this persistent connection. The existing `sexec.sh` permission system is preserved.
+
+**Architecture:**
+```
+Remote Nodes (sissy, zeiss, spank, ganeti1, ganeti2)
+    ↓ WebSocket (node-initiated)
+Gateway (Hermes host)
+    ↓ HTTP API
+Hermes Agent (you)
+```
+
+**Key Benefits:**
+- ✅ No SSH keys stored on gateway
+- ✅ Firewall-friendly (nodes connect out)
+- ✅ Reuses existing sexec permission system
+- ✅ Token-based authentication
+- ✅ Real-time command streaming
+
+---
+
+## Prerequisites
+
+### Gateway Host (Hermes)
+- Python 3.7+
+- pip3
+- Root access (for SysV init service)
+- Ports 8765 (WebSocket) and 8766 (HTTP) available
+
+### Remote Nodes
+- Python 3.7+
+- pip3
+- Existing `sexec.sh` installation with `config.json`
+- Network access to gateway host
+
+---
+
+## Part 1: Gateway Installation
+
+### Step 1: Install Gateway
+
+On the Hermes host:
+
+```bash
+cd ~/hermes-node-protocol/gateway
+sudo ./install.sh
+```
+
+This will:
+1. Install Python dependencies (websockets, aiohttp)
+2. Create `hermes` system user
+3. Create config directory `/etc/hermes-node-gateway/`
+4. Generate random tokens for each node
+5. Install SysV init service
+6. Create log file `/var/log/hermes-node-gateway.log`
+
+### Step 2: Review Configuration
+
+```bash
+sudo cat /etc/hermes-node-gateway/config.json
+```
+
+**Example config:**
+```json
+{
+  "websocket_port": 8765,
+  "http_port": 8766,
+  "bind_address": "0.0.0.0",
+  "tokens": {
+    "sissy": "a1b2c3d4e5f6...",
+    "zeiss": "f6e5d4c3b2a1...",
+    "spank": "1a2b3c4d5e6f...",
+    "ganeti1": "6f5e4d3c2b1a...",
+    "ganeti2": "abcdef123456..."
+  }
+}
+```
+
+**Important:** Save these tokens — you'll need them for each node's configuration.
+
+### Step 3: Start Gateway
+
+```bash
+/etc/init.d/hermes-node-gateway start
+/etc/init.d/hermes-node-gateway status
+```
+
+**Check logs:**
+```bash
+tail -f /var/log/hermes-node-gateway.log
+```
+
+You should see:
+```
+Starting Hermes Node Gateway...
+HTTP API listening on 0.0.0.0:8766
+WebSocket server listening on 0.0.0.0:8765
+Gateway is running
+```
+
+### Step 4: Verify Gateway
+
+```bash
+# Check HTTP API
+curl http://localhost:8766/nodes
+
+# Should return:
+{"nodes": []}
+```
+
+Gateway is now ready to accept node connections.
+
+---
+
+## Part 2: Node Agent Installation
+
+Repeat these steps for **each remote node** (sissy, zeiss, spank, ganeti1, ganeti2).
+
+### Step 1: Copy Installer to Node
+
+From the gateway host:
+
+```bash
+# For sissy
+scp -r ~/hermes-node-protocol/node-agent openclaw@192.168.42.115:/tmp/
+
+# For zeiss
+scp -r ~/hermes-node-protocol/node-agent nextime@192.168.42.3:/tmp/
+
+# For spank
+scp -r ~/hermes-node-protocol/node-agent openclaw@192.168.231.26:/tmp/
+
+# For ganeti1
+scp -r ~/hermes-node-protocol/node-agent root@192.168.250.1:/tmp/
+
+# For ganeti2
+scp -r ~/hermes-node-protocol/node-agent root@192.168.11.1:/tmp/
+```
+
+### Step 2: Install Agent on Node
+
+SSH to the node:
+
+```bash
+ssh openclaw@192.168.42.115  # or appropriate user@ip
+```
+
+Run installer:
+
+```bash
+cd /tmp/node-agent
+./install.sh
+```
+
+This will:
+1. Install Python dependencies (websockets)
+2. Create config directory `/etc/hermes-node/`
+3. Install agent script to `/usr/local/bin/hermes-node-agent`
+4. Create example config with random token
+5. Install SysV init service
+6. Update init runlevel links
+
+### Step 3: Configure Node
+
+Edit the config file:
+
+```bash
+nano /etc/hermes-node/config.json
+```
+
+**Update these fields:**
+
+```json
+{
+  "gateway_url": "ws://192.168.42.115:8765",
+  "node_name": "sissy",
+  "token": "PASTE-TOKEN-FROM-GATEWAY-CONFIG",
+  "sexec_path": "/home/openclaw/.openclaw/skills/sexec/sexec.sh",
+  "reconnect_interval": 5,
+  "heartbeat_interval": 30
+}
+```
+
+**Important:**
+- `gateway_url`: WebSocket URL of your gateway (use gateway's IP)
+- `node_name`: Must match the name in gateway's tokens config
+- `token`: Copy from gateway's `/etc/hermes-node-gateway/config.json`
+- `sexec_path`: Path to your existing sexec.sh installation
+
+### Step 4: Verify sexec Installation
+
+Make sure sexec is installed and working:
+
+```bash
+/home/openclaw/.openclaw/skills/sexec/sexec.sh run --command "hostname"
+```
+
+Should return the hostname without errors.
+
+### Step 5: Start Node Agent
+
+```bash
+/etc/init.d/hermes-node-agent start
+/etc/init.d/hermes-node-agent status
+```
+
+**Check logs:**
+```bash
+tail -f /var/log/hermes-node-agent.log
+```
+
+You should see:
+```
+Connecting to gateway: ws://192.168.42.115:8765
+Connected to gateway
+Sent registration for node 'sissy'
+Registration acknowledged by gateway (version 1.0)
+```
+
+### Step 6: Verify Connection
+
+Back on the gateway host, check connected nodes:
+
+```bash
+curl http://localhost:8766/nodes | jq
+```
+
+Should show:
+```json
+{
+  "nodes": [
+    {
+      "name": "sissy",
+      "status": "connected",
+      "last_seen": 1714392000,
+      "uptime": 123,
+      "version": "1.0",
+      "capabilities": ["exec", "sysinfo"]
+    }
+  ]
+}
+```
+
+---
+
+## Part 3: Testing
+
+### Test 1: Simple Command
+
+```bash
+curl -X POST http://localhost:8766/nodes/sissy/exec \
+  -H "Content-Type: application/json" \
+  -d '{"command": ["hostname"], "timeout": 10}' | jq
+```
+
+**Expected output:**
+```json
+{
+  "id": "cmd-a1b2c3d4",
+  "status": "completed",
+  "stdout": "sissy\n",
+  "stderr": "",
+  "exit_code": 0,
+  "error": null,
+  "duration_ms": 234
+}
+```
+
+### Test 2: Command with Output
+
+```bash
+curl -X POST http://localhost:8766/nodes/sissy/exec \
+  -H "Content-Type: application/json" \
+  -d '{"command": ["df", "-h"], "timeout": 10}' | jq -r '.stdout'
+```
+
+Should display disk usage.
+
+### Test 3: Using Helper Script
+
+```bash
+~/hermes-node-protocol/scripts/node-exec.sh sissy hostname
+~/hermes-node-protocol/scripts/node-exec.sh sissy df -h
+~/hermes-node-protocol/scripts/node-exec.sh sissy uptime
+```
+
+### Test 4: All Nodes
+
+```bash
+for node in sissy zeiss spank ganeti1 ganeti2; do
+  echo "=== $node ==="
+  ~/hermes-node-protocol/scripts/node-exec.sh $node hostname 2>/dev/null || echo "  (not connected)"
+done
+```
+
+---
+
+## Part 4: Integration with Hermes
+
+The `hermes-node-exec` skill is already installed at `~/.hermes/skills/hermes-node-exec/`.
+
+### Usage from Hermes
+
+When you ask me to run commands on nodes, I'll use the HTTP API:
+
+**You say:**
+> "Check disk usage on sissy"
+
+**I execute:**
+```bash
+curl -s -X POST http://localhost:8766/nodes/sissy/exec \
+  -H "Content-Type: application/json" \
+  -d '{"command": ["df", "-h"], "timeout": 30}' | jq -r '.stdout'
+```
+
+**You say:**
+> "List Ganeti instances on ganeti1"
+
+**I execute:**
+```bash
+curl -s -X POST http://localhost:8766/nodes/ganeti1/exec \
+  -H "Content-Type: application/json" \
+  -d '{"command": ["sudo", "gnt-instance", "list"], "timeout": 30}' | jq -r '.stdout'
+```
+
+---
+
+## Troubleshooting
+
+### Node Won't Connect
+
+**Symptom:** Node agent logs show connection errors
+
+**Check:**
+1. Gateway is running: `/etc/init.d/hermes-node-gateway status`
+2. Firewall allows port 8765: `sudo ufw status`
+3. Gateway URL is correct in node config
+4. Token matches between node and gateway configs
+
+**Debug:**
+```bash
+# On node
+tail -n 50 /var/log/hermes-node-agent.log
+
+# On gateway
+sudo tail -n 50 /var/log/hermes-node-gateway.log
+```
+
+### Invalid Token
+
+**Symptom:** Node logs show "Invalid token"
+
+**Solution:**
+1. Check gateway config: `sudo cat /etc/hermes-node-gateway/config.json`
+2. Copy correct token to node config: `/etc/hermes-node/config.json`
+3. Restart node agent: `/etc/init.d/hermes-node-agent restart`
+
+### Command Denied
+
+**Symptom:** Command returns "Denied: ..."
+
+**Solution:**
+The command is in the node's sexec deny list. Either:
+1. Remove from deny list: Edit `~/.openclaw/skills/sexec/config.json` on the node
+2. Use a different command
+
+### Command Requires Approval
+
+**Symptom:** Command returns "approval_required"
+
+**Solution:**
+The command is in the sexec "ask" list. Get user approval, then re-run with `"approved": true`:
+
+```bash
+curl -X POST http://localhost:8766/nodes/sissy/exec \
+  -H "Content-Type: application/json" \
+  -d '{"command": ["sudo", "..."], "timeout": 30, "approved": true}'
+```
+
+### Gateway Not Responding
+
+**Symptom:** `curl: (7) Failed to connect`
+
+**Check:**
+```bash
+/etc/init.d/hermes-node-gateway status
+sudo netstat -tlnp | grep 8766
+```
+
+**Restart:**
+```bash
+/etc/init.d/hermes-node-gateway restart
+```
+
+---
+
+## Security Considerations
+
+### 1. Token Security
+
+- Tokens are stored in `/etc/hermes-node-gateway/config.json` (mode 600, owned by hermes)
+- Each node has a unique token
+- Tokens are 64-character random hex strings
+- If a token is compromised, regenerate and update both gateway and node configs
+
+### 2. Network Security
+
+- Gateway listens on `0.0.0.0` by default (all interfaces)
+- Consider binding to specific interface: `"bind_address": "192.168.42.115"`
+- Use firewall rules to restrict access:
+  ```bash
+  sudo ufw allow from 192.168.42.0/24 to any port 8765
+  sudo ufw allow from 192.168.42.0/24 to any port 8766
+  ```
+
+### 3. Permission System
+
+- Each node enforces its own sexec allow/deny/ask lists
+- Gateway cannot bypass node permissions
+- Commands in "ask" list require explicit user approval
+- Commands in "deny" list are rejected immediately
+
+### 4. TLS/WSS (Future Enhancement)
+
+Current version uses unencrypted WebSocket (ws://). For production:
+- Use WSS (WebSocket Secure) with TLS certificates
+- Encrypt HTTP API with HTTPS
+- Use certificate-based authentication instead of tokens
+
+---
+
+## Maintenance
+
+### View Gateway Logs
+
+```bash
+tail -f /var/log/hermes-node-gateway.log
+```
+
+### View Node Logs
+
+```bash
+ssh user@node 'tail -f /var/log/hermes-node-agent.log'
+```
+
+### Restart Gateway
+
+```bash
+/etc/init.d/hermes-node-gateway restart
+```
+
+### Restart Node Agent
+
+```bash
+ssh user@node '/etc/init.d/hermes-node-agent restart'
+```
+
+### Update Gateway
+
+```bash
+cd ~/hermes-node-protocol/gateway
+sudo cp hermes_node_gateway.py /usr/local/bin/hermes-node-gateway
+/etc/init.d/hermes-node-gateway restart
+```
+
+### Update Node Agent
+
+```bash
+# On each node
+cd /tmp/node-agent
+sudo cp hermes_node_agent.py /usr/local/bin/hermes-node-agent
+/etc/init.d/hermes-node-agent restart
+```
+
+---
+
+## Migration from OpenClaw
+
+If you're migrating from OpenClaw sexec:
+
+### What to Keep
+- ✅ Keep `sexec.sh` on all nodes
+- ✅ Keep `config.json` permission files
+- ✅ Keep existing allow/deny/ask lists
+
+### What to Change
+- ❌ Remove OpenClaw gateway (optional)
+- ❌ Remove OpenClaw node agents (optional)
+- ✅ Install Hermes Node Gateway
+- ✅ Install Hermes Node Agents
+- ✅ Update Hermes skills to use new HTTP API
+
+### Coexistence
+
+You can run both systems in parallel during migration:
+- OpenClaw gateway on different ports
+- Hermes gateway on ports 8765/8766
+- Both can use the same sexec.sh installations
+
+---
+
+## Next Steps
+
+1. ✅ Gateway installed and running
+2. ✅ All nodes connected
+3. ✅ Test commands working
+4. ✅ Hermes skill installed
+
+**You're ready to use the system!**
+
+Try asking me:
+- "Check disk usage on all nodes"
+- "List Ganeti instances on ganeti1"
+- "Check uptime on zeiss"
+
+I'll use the Hermes Node Protocol to execute these commands.
+
+---
+
+## Files Reference
+
+| File | Location | Purpose |
+|------|----------|---------|
+| Protocol Spec | `~/hermes-node-protocol/PROTOCOL.md` | Message format and architecture |
+| Gateway Script | `~/hermes-node-protocol/gateway/hermes_node_gateway.py` | Gateway server code |
+| Gateway Config | `/etc/hermes-node-gateway/config.json` | Gateway configuration and tokens |
+| Gateway Service | `/etc/init.d/hermes-node-gateway` | SysV init script |
+| Node Agent Script | `~/hermes-node-protocol/node-agent/hermes_node_agent.py` | Node agent code |
+| Node Agent Config | `/etc/hermes-node/config.json` | Node configuration (on each node) |
+| Node Agent Service | `/etc/init.d/hermes-node-agent` | SysV init script |
+| Helper Script | `~/hermes-node-protocol/scripts/node-exec.sh` | CLI wrapper |
+| Hermes Skill | `~/.hermes/skills/hermes-node-exec/SKILL.md` | Skill documentation |
+
+---
+
+## Support
+
+For issues or questions:
+1. Check logs (gateway and node)
+2. Verify network connectivity
+3. Confirm tokens match
+4. Test with simple commands first
+5. Review the protocol spec for message formats
+
+**Common issues are documented in the Troubleshooting section above.**

DEPLOY_SISSY.md

+# Deploying Browser Control to sissy (Laptop)
+
+## Architecture Recap
+
+```
+sissy (laptop) ←←← Node Agent ←←→ zeiss (workstation) ←→ Hermes
+      ^                              ^
+      └── Browser control runs HERE ─┘
+```
+
+The node agent runs **on sissy**, controlling the local browser.
+Hermes talks to the **gateway on zeiss**, which routes to sissy.
+
+---
+
+## What's Already Done
+
+✅ Code written: `browser_controller.py`, node agent integration, gateway HTTP endpoint
+✅ Playwright + Chromium tested on lisa (this VPS)
+✅ Gateway updated with sissy token and browser endpoint
+✅ Install script prepared: `install-on-sissy.sh`
+✅ Documentation: `BROWSER_CONTROL.md`, `SKILL.md`
+
+---
+
+## Step-by-Step Deployment
+
+### On lisa (this VPS) — Package & Transfer
+
+**1. Archive the node agent code:**
+
+```bash
+cd ~/hermes-node-protocol
+tar -czf node-agent-package.tar.gz node-agent/ install-on-sissy.sh
+```
+
+**2. Transfer to sissy:**
+
+Since you're on sissy writing to me, you already have access. Just copy the package:
+
+From lisa, scp to sissy:
+```bash
+# Assuming you can SSH from lisa to sissy
+scp node-agent-package.tar.gz nextime@sissy:/tmp/
+```
+
+Or simpler: just download it from lisa via your local browser on sissy if you have a web server running.
+
+**Actually — since you're *on* sissy now, do this instead:**
+
+On sissy, clone or copy from lisa:
+```bash
+# If hermes-node-protocol is already on sissy, skip this
+# If not, copy from lisa (assuming SSH access from sissy to lisa):
+scp lisa:~/hermes-node-protocol/node-agent ~/hermes-node-protocol/
+scp lisa:~/hermes-node-protocol/install-on-sissy.sh ~/hermes-node-protocol/
+```
+
+**Where is the code on lisa?**
+It's at: `/home/lisa/hermes-node-protocol/`
+
+Since you're currently on **sissy**, and you have access to your files, you need to get this code onto sissy. How do you want to transfer it?
+
+Options:
+1. **Git repo** — if the code is in a git repo, just `git clone` on sissy
+2. **SCP/rsync** — from sissy to lisa (reverse direction since lisa is the source)
+3. **USB/external drive** — copy manually
+4. **Shared filesystem** — NFS/SMB mount
+
+Which do you prefer? Or is the code already on sissy?
+
+---
+
+### On sissy — Installation
+
+Once the code is on sissy at `~/hermes-node-protocol/`:
+
+```bash
+cd ~/hermes-node-protocol
+sudo ./install-on-sissy.sh
+```
+
+This will:
+- Create `/etc/hermes-node/config.json`
+- Setup Python venv + Playwright
+- Install SysV init script
+- Start the node agent
+
+### On zeiss (gateway) — Verify
+
+Node should auto-register with gateway on zeiss:
+
+```bash
+# On zeiss, check:
+curl http://localhost:8766/nodes/sissy/status
+
+# Should return:
+# {"name":"sissy","status":"connected",...}
+```
+
+### From Hermes — Control sissy's browser
+
+```python
+# Example using curl
+curl -X POST http://zeiss:8766/nodes/sissy/browser \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "launch",
+    "params": {"config": {"headless": false}}
+  }'
+```
+
+---
+
+## Files to Transfer from lisa to sissy
+
+```
+hermes-node-protocol/
+├── node-agent/
+│   ├── hermes_node_agent.py       (main agent)
+│   ├── browser_controller.py      (new)
+│   ├── requirements.txt           (new)
+│   ├── test_browser.py            (test script)
+│   └── venv/                      (will be recreated on sissy)
+├── gateway/
+│   └── hermes_node_gateway.py      (already on zeiss, not needed on sissy)
+├── install-on-sissy.sh             (new)
+├── README.md
+├── PROTOCOL.md
+├── PROJECT_SUMMARY.md
+├── DEPLOYMENT.md
+└── BROWSER_CONTROL.md             (new)
+```
+
+Only `node-agent/` directory and `install-on-sissy.sh` are needed on sissy.
+
+---
+
+## Quick Transfer Command
+
+From **sissy**, run:
+
+```bash
+# Copy from lisa (source) to sissy (current machine)
+scp -r lisa:~/hermes-node-protocol/node-agent ~/hermes-node-protocol/
+scp lisa:~/hermes-node-protocol/install-on-sissy.sh ~/hermes-node-protocol/
+```
+
+If SSH from sissy to lisa isn't set up, we'll need another method.
+
+**Question:** Can sissy SSH into lisa? Or do you want a different transfer method?

WINDOWS_DEPLOYMENT.md

+# Hermes Node Agent — Windows Deployment Guide
+
+**Platform:** Windows 10/11, Windows Server 2016+  
+**Version:** 2.0  
+**Date:** 2026-04-30
+
+This guide covers deploying the Hermes Node Agent on Windows machines using the graphical installer.
+
+---
+
+## Overview
+
+The Windows package includes:
+
+- **hermes-node-agent.exe** — Main agent (connects to gateway)
+- **hermes-node-manager.exe** — System tray GUI for management
+- **NSSM** — Service wrapper (runs agent as Windows service)
+- **Graphical installer** — One-click setup with uninstaller
+
+---
+
+## Installation
+
+### Option A: Graphical Installer (Recommended)
+
+1. **Download** `hermes-node-agent-installer.exe`
+2. **Right-click** → **Run as Administrator**
+3. Follow the installation wizard:
+   - Accept license
+   - Choose install location (default: `C:\Program Files\Hermes Node`)
+   - Select components:
+     - ☑ Install Windows Service (recommended)
+     - ☑ Start Manager at login (recommended)
+     - ☐ Create desktop shortcut (optional)
+4. Click **Install**
+5. When prompted, click **Finish** to launch the manager
+
+### Option B: Silent Installation (for deployment tools)
+
+```cmd
+hermes-node-agent-installer.exe /VERYSILENT /NORESTART /TASKS="starttray"
+```
+
+Parameters:
+- `/VERYSILENT` — No UI, no prompts
+- `/NORESTART` — Don't reboot after install
+- `/TASKS="starttray"` — Enable auto-start at login
+- `/DIR="C:\Custom\Path"` — Custom install directory
+
+---
+
+## First-Time Configuration
+
+After installation, the **Hermes Node Manager** will appear in your system tray (near the clock).
+
+### Step 1: Configure Connection
+
+1. **Right-click** the tray icon (blue "H")
+2. Select **Configuration**
+3. Fill in the required fields:
+   - **Gateway URL**: `wss://your-gateway-host:8765`
+   - **Node Name**: Unique identifier (default: computer name)
+   - **Token**: Authentication token from gateway admin
+   - **sexec Path**: (optional) Path to permission script
+   - **Reconnect**: Seconds between reconnect attempts (default: 5)
+   - **Heartbeat**: Seconds between heartbeats (default: 30)
+4. Click **Save**
+
+### Step 2: Start the Agent
+
+1. **Right-click** the tray icon
+2. Select **Start Agent**
+3. Wait 5-10 seconds for connection
+4. Verify in **Status** window (should show "RUNNING")
+
+---
+
+## Using the Manager
+
+### System Tray Menu
+
+Right-click the tray icon to access:
+
+| Menu Item | Description |
+|-----------|-------------|
+| **Configuration** | Edit gateway URL, token, and settings |
+| **Logs** | View agent logs (last 50 lines or full) |
+| **Status** | Show connection status and config summary |
+| **Start Agent** | Start the Windows service |
+| **Stop Agent** | Stop the Windows service |
+| **Restart Agent** | Restart the service (apply config changes) |
+| **Open Gateway UI** | Open gateway web interface in browser |
+| **Exit** | Close the manager (agent keeps running) |
+
+### Configuration Window
+
+**Fields:**
+
+- **Gateway URL**: WebSocket address of the gateway
+  - Format: `wss://hostname:8765` (secure) or `ws://hostname:8765` (insecure)
+  - Must match the gateway's WebSocket port
+- **Node Name**: Unique identifier for this node
+  - Must match a token entry in gateway's `config.json`
+  - Default: Windows computer name
+- **Token**: Authentication secret
+  - Provided by gateway administrator
+  - Keep this secure (treat like a password)
+- **sexec Path**: (Optional) Path to PowerShell permission script
+  - Default: `%USERPROFILE%\.openclaw\skills\sexec\sexec.ps1`
+  - Leave blank to allow all commands (not recommended)
+- **Reconnect Interval**: Seconds to wait before reconnecting after disconnect
+- **Heartbeat Interval**: Seconds between keep-alive pings
+
+**After changing config:**
+- Click **Save**
+- **Restart Agent** from the tray menu to apply changes
+
+### Log Viewer
+
+View real-time agent logs:
+
+1. Right-click tray icon → **Logs**
+2. Click **Refresh** to reload
+3. Click **Tail (last 50)** to see recent entries
+4. Click **Clear** to empty the view
+
+**Log file location:** `C:\ProgramData\hermes-node\hermes-node-agent.log`
+
+### Status Window
+
+Shows:
+- Service status (RUNNING / STOPPED)
+- Current configuration summary
+- File paths (config, logs, agent)
+- Auto-refreshes every 5 seconds
+
+---
+
+## Service Management
+
+The agent runs as a Windows service named **HermesNodeAgent**.
+
+### Via Tray Manager (Recommended)
+
+- **Start**: Right-click tray icon → Start Agent
+- **Stop**: Right-click tray icon → Stop Agent
+- **Restart**: Right-click tray icon → Restart Agent
+
+### Via Command Line
+
+```cmd
+REM Start service
+sc start HermesNodeAgent
+
+REM Stop service
+sc stop HermesNodeAgent
+
+REM Query status
+sc query HermesNodeAgent
+
+REM View service config
+sc qc HermesNodeAgent
+```
+
+### Via Services.msc
+
+1. Press `Win+R`, type `services.msc`, press Enter
+2. Find **HermesNodeAgent** in the list
+3. Right-click → Start / Stop / Restart
+4. Right-click → Properties to configure startup type
+
+---
+
+## Permissions (sexec)
+
+The Windows agent supports the same permission system as Linux.
+
+### Creating sexec.ps1
+
+Create `%USERPROFILE%\.openclaw\skills\sexec\sexec.ps1`:
+
+```powershell
+# Hermes Node Agent — Permission Enforcement Script
+param()
+
+$command = $env:SEXEC_COMMAND
+if (-not $command) {
+    Write-Error "SEXEC_COMMAND not set"
+    exit 1
+}
+
+# Load permissions from JSON
+$permPath = "$env:USERPROFILE\.openclaw\skills\sexec\permissions.json"
+if (Test-Path $permPath) {
+    $perms = Get-Content $permPath | ConvertFrom-Json
+
+    # Deny list (highest priority)
+    foreach ($pattern in $perms.deny) {
+        if ($command -match $pattern) {
+            Write-Error "Denied by pattern: $pattern"
+            exit 1
+        }
+    }
+
+    # Ask list (requires approval)
+    foreach ($pattern in $perms.ask) {
+        if ($command -match $pattern) {
+            Write-Error "Command requires approval"
+            exit 2
+        }
+    }
+
+    # Allow list (if present, command must match)
+    if ($perms.allow -and $perms.allow.Count -gt 0) {
+        $allowed = $false
+        foreach ($pattern in $perms.allow) {
+            if ($command -match $pattern) {
+                $allowed = $true
+                break
+            }
+        }
+        if (-not $allowed) {
+            Write-Error "Not in allow list"
+            exit 1
+        }
+    }
+}
+
+# Execute command
+Invoke-Expression $command
+exit $LASTEXITCODE
+```
+
+### Creating permissions.json
+
+Create `%USERPROFILE%\.openclaw\skills\sexec\permissions.json`:
+
+```json
+{
+  "allow": [
+    "^dir\\b",
+    "^Get-",
+    "^Test-Path",
+    "^whoami"
+  ],
+  "deny": [
+    "Remove-Item.*-Recurse",
+    "Format-Volume",
+    "Stop-Computer",
+    "Restart-Computer"
+  ],
+  "ask": [
+    "Install-",
+    "Uninstall-",
+    "Set-ExecutionPolicy"
+  ]
+}
+```
+
+**Patterns are PowerShell regex:**
+- `^` = start of command
+- `\\b` = word boundary
+- `.*` = any characters
+- Case-insensitive by default
+
+---
+
+## Firewall Configuration
+
+The agent makes **outbound connections only** (no inbound ports needed).
+
+### Allow Outbound Connection
+
+If Windows Firewall blocks the agent:
+
+1. Open **Windows Defender Firewall with Advanced Security**
+2. Click **Outbound Rules** → **New Rule**
+3. Select **Program** → Next
+4. Browse to: `C:\Program Files\Hermes Node\hermes-node-agent.exe`
+5. Select **Allow the connection** → Next
+6. Apply to all profiles (Domain, Private, Public) → Next
+7. Name: "Hermes Node Agent" → Finish
+
+### Test Connectivity
+
+```powershell
+# Test gateway reachability
+Test-NetConnection -ComputerName your-gateway-host -Port 8765
+
+# Should show: TcpTestSucceeded : True
+```
+
+---
+
+## Troubleshooting
+
+### Agent won't start
+
+**Check service status:**
+```cmd
+sc query HermesNodeAgent
+```
+
+**View service errors:**
+```cmd
+Get-EventLog -LogName Application -Source HermesNodeAgent -Newest 10
+```
+
+**Common causes:**
+- Config file missing or invalid JSON
+- Python not installed (embedded version should be bundled)
+- Gateway URL unreachable
+
+### Connection refused
+
+1. Verify gateway is running: `curl https://your-gateway:8766/health`
+2. Check token matches gateway config
+3. Ensure node name matches token entry in gateway
+4. Check firewall allows outbound HTTPS/WSS
+
+### Permission denied errors
+
+1. Verify `sexec_path` points to an existing `.ps1` file
+2. Check `permissions.json` syntax (valid JSON)
+3. Test sexec manually:
+   ```powershell
+   $env:SEXEC_COMMAND = "whoami"
+   & "$env:USERPROFILE\.openclaw\skills\sexec\sexec.ps1"
+   ```
+
+### Manager won't start
+
+**Check if already running:**
+```powershell
+Get-Process hermes-node-manager -ErrorAction SilentlyContinue
+```
+
+**Kill and restart:**
+```powershell
+Stop-Process -Name hermes-node-manager -Force
+& "C:\Program Files\Hermes Node\hermes-node-manager.exe"
+```
+
+### Logs show "Token invalid"
+
+1. Open config: `notepad C:\ProgramData\hermes-node\config.json`
+2. Verify token matches gateway's `config.json` entry for this node
+3. Restart agent after fixing
+
+---
+
+## Uninstallation
+
+### Via Control Panel
+
+1. Open **Settings** → **Apps** → **Apps & features**
+2. Find **Hermes Node Agent**
+3. Click **Uninstall**
+4. Follow the wizard
+
+### Via Command Line
+
+```cmd
+"C:\Program Files\Hermes Node\unins000.exe" /VERYSILENT /NORESTART
+```
+
+**What gets removed:**
+- Agent executable and manager
+- Windows service registration
+- Start menu shortcuts
+- Desktop shortcut (if created)
+
+**What stays (manual cleanup required):**
+- Config: `C:\ProgramData\hermes-node\config.json`
+- Logs: `C:\ProgramData\hermes-node\hermes-node-agent.log`
+- sexec scripts: `%USERPROFILE%\.openclaw\skills\sexec\`
+
+---
+
+## Advanced: Running Without Service
+
+For testing or development, run the agent directly:
+
+```cmd
+cd "C:\Program Files\Hermes Node"
+hermes-node-agent.exe --config "C:\ProgramData\hermes-node\config.json"
+```
+
+Press `Ctrl+C` to stop.
+
+---
+
+## Files Installed
+
+| Path | Description |
+|------|-------------|
+| `C:\Program Files\Hermes Node\hermes-node-agent.exe` | Main agent executable |
+| `C:\Program Files\Hermes Node\hermes-node-manager.exe` | System tray manager GUI |
+| `C:\Program Files\Hermes Node\nssm.exe` | Service wrapper |
+| `C:\ProgramData\hermes-node\config.json` | Configuration file |
+| `C:\ProgramData\hermes-node\hermes-node-agent.log` | Log file |
+| `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Hermes Node\` | Start menu shortcuts |
+
+---
+
+## Support
+
+For issues:
+- Check logs: `C:\ProgramData\hermes-node\hermes-node-agent.log`
+- Check gateway logs: `/var/log/hermes-node-gateway.log` (on gateway host)
+- Review DEPLOYMENT.md for architecture details
+- Contact gateway administrator for token/connectivity issues