<!-- Copyright (C) 2026 Stefy Lanza <stefy@nexlab.net> -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
<!-- Copyleft: GNU GPLv3 or later applies to this file. -->

# Hermes Node Agent

**Version:** 2.0  
**Repository:** `git@git.nexlab.net:lisa/hermes-node-agent.git`

Cross-platform node agent for the Hermes Node Protocol. Connects to a central gateway via WebSocket and executes commands with permission enforcement.

---

## Features

- **Cross-platform**: Linux and Windows support
- **Reverse connection**: Nodes connect to gateway (firewall-friendly)
- **Token authentication**: Secure per-node tokens
- **Permission system**: integrated allow/deny/ask rules enforced by the agent
- **Auto-reconnect**: Exponential backoff on disconnect
- **Heartbeat**: Keep-alive mechanism
- **Optional capabilities**: Browser control, computer control

---

## Platforms

### Linux
- Bash installer with SysV init service
- CLI-based configuration
- Runs as daemon

### Windows
- Graphical installer (.exe via Inno Setup)
- System tray GUI manager
- Windows Service integration (NSSM)
- Configuration editor (no manual JSON editing)
- Log viewer with auto-refresh

---

## Installation

### Linux

```bash
sudo ./install.sh
sudo nano /etc/hermes-node/config.json  # Edit gateway_url and token
sudo /etc/init.d/hermes-node-agent start
```

### Windows

1. Build installer (on Windows dev machine):
   ```cmd
   python windows\build.py
   ```

2. Run `windows\Output\hermes-node-agent-installer.exe` as Administrator

3. Configure via system tray: Right-click icon → Configuration

---

## Configuration

**Linux:** `/etc/hermes-node/config.json`  
**Windows:** `C:\ProgramData\hermes-node\config.json`

```json
{
  "gateway_url": "wss://gateway-host:8765",
  "node_name": "my-node",
  "token": "your-token-here",
  "reconnect_interval": 5,
  "heartbeat_interval": 30,
  "capabilities": ["exec"],
  "enable_browser": false,
  "enable_computer_control": false,
  "enable_desktop_observe": false,
  "enable_audio_control": false,
  "enable_camera_control": false,
  "permissions": {
    "deny": ["rm -rf /", "mkfs", "dd if="],
    "ask": ["sudo", "su", "passwd", "mount", "umount", "fdisk", "parted"],
    "allow": ["ls", "pwd", "whoami", "hostname", "uname", "date", "uptime", "df", "free", "ps", "cat", "head", "tail", "grep", "find", "du", "ip", "ifconfig", "ping", "curl", "wget", "git", "python", "python3", "node", "npm", "dmesg", "docker", "kubectl"]
  }
}
```

---

### Browser Control Capability

For browser automation support, the bot control capability uses the **Hermes Node Chrome Extension**:

**Repository:** `git@git.nexlab.net:lisa/hermes-node-chrome.git`

The extension enables DOM manipulation, screenshots, and click/type automation.

---

## Files

```
node-agent/
├── hermes_node_agent.py          # Main agent (cross-platform)
├── browser_controller.py         # Browser control capability
├── install.sh                    # Linux installer
├── install-windows.ps1           # Windows PowerShell installer (legacy)
├── hermes-node-agent.init.d      # SysV init script
├── hermes-node-agent.service     # service file (legacy artifact; SysV init is canonical)
├── requirements.txt              # Python dependencies
└── windows/                      # Windows-specific components
    ├── agent-manager.py          # System tray GUI
    ├── installer.iss             # Inno Setup script
    ├── build.py                  # Build automation
    └── README.md                 # Build instructions
```

---

## Documentation

- **DEPLOYMENT.md** — Full deployment guide
- **WINDOWS_DEPLOYMENT.md** — Windows-specific guide
- **PROTOCOL.md** — WebSocket protocol specification
- **windows/README.md** — Windows build instructions

---

## Related Repositories

- **Gateway Plugin:** `~/.hermes/plugins/hermes-node-gateway/` (loaded by Hermes Agent)
- **Node Agent:** `git@git.nexlab.net:lisa/hermes-node-agent.git`
- **Chrome Extension:** `git@git.nexlab.net:lisa/hermes-node-chrome.git`

---

## License

MIT License — See the [LICENSE](LICENSE) file in this repository.

---

## Support

For issues, check:
- Agent logs: `/var/log/hermes-node-agent.log` (Linux) or `C:\ProgramData\hermes-node\hermes-node-agent.log` (Windows)
- Gateway logs on gateway host
- Configuration files for token/URL mismatches

## Donate

If you find this project useful, consider supporting its continued development:

**Bitcoin (BTC)**: `bc1ql5klyv78t0a5g59y3tczv8ejy9l740x3zg0cge`  
**Ethereum (ETH)**: `0x3f707d3543A6C301B3Bf47eBc4B469e017a119B4`  
**Solana (SOL)**: `G7iZQ3iQ7k5t9E9g8Y7u6i5t4r3e2w1q0P9O8I7U6Y5`

---

*Copyright (c) 2026 Stefy (nextime) Lanza <stefy@nexlab.net>. All rights reserved.*
