<!-- 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. -->

# Windows Installer Build — PyInstaller + NSIS

## Overview

The Windows installer is built **on Linux** using Wine to run Windows Python + PyInstaller. The result is a single `.exe` installer that presents an interactive configuration dialog matching the Linux installer prompts.

## Prerequisites

On the Linux build host:
```bash
sudo apt-get install -y wine wine64 makensis
```

Download **NSSM** (Windows Service Manager):
```bash
# Place this in windows/nssm.exe
wget https://nssm.cc/release/nssm-2.24.zip
unzip -j nssm-2.24.zip "nssm-2.24/win64/nssm.exe" -d /path/to/project/windows/
```

## Build Process

### One-command build
```bash
cd /path/to/hermes-node-protocol/node-agent
./windows/build-all.sh
```

### What it does
1. **PyInstaller build** (via Wine Python)
   - `hermes_node_agent.py` → `dist/hermes-node-agent.exe` (console, ~45 MB)
   - `agent-manager.py` → `dist/hermes-node-manager.exe` (GUI, ~7 MB)
2. **NSIS installer** (`dist/installer.nsi`)
   - Includes both executables, `nssm.exe`
   - Custom config page with **same fields as Linux installer**:
     - Gateway URL
     - Node name
     - Gateway token
   - Writes `config.json` to `C:\ProgramData\HermesNode\`
   - Installs as Windows service (via NSSM)
   - Creates Start Menu + Desktop shortcuts

## Output

```
windows/dist/hermes-node-agent-installer.exe  (~51 MB)
```

This is a fully self-contained offline Windows installer.

## Installer User Flow

1. Run `.exe` (requires Administrator)
2. **Welcome page** → Next
3. **Install directory** (default: `C:\Program Files\HermesNode`) → Next
4. **Configuration page** (custom):
   - Gateway URL: e.g., `ws://gateway.example.com:8765`
   - Node name: e.g., `WORKSTATION-01`
   - Gateway token: (paste from gateway admin)
   → Next
5. **Installing** → finishes
6. Service `HermesNodeAgent` auto-starts with the provided config

## Config File Created

The installer writes to `C:\ProgramData\HermesNode\config.json`:
```json
{
  "gateway_url": "wss://gateway.example.com:8765",
  "node_name": "WORKSTATION-01",
  "token": "YOUR-SECRET-TOKEN",
  "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", "systemctl", "journalctl", "dmesg", "docker", "kubectl"]
  }
}
```

## Windows Build Notes

- PyInstaller 6.20.0 via Wine Python 3.13.1 (embeddable)
- NSIS 3.x for installer (Linux `makensis` package)
- NSSM v2.24 (bundled in installer) for Windows service management
- Both `.exe` files are **single-file bundles** — no external DLL dependencies except standard Windows system DLLs

## Troubleshooting

**PyInstaller build fails:**
- Ensure Wine Python has pip + PyInstaller: `wine python-win/python.exe -m pip install pyinstaller websockets`
- Check `wine` is set up: `wine --version`

**NSIS compile fails:**
- Ensure `makensis` installed: `which makensis`
- NSSM must be present in `windows/` before `build-all.sh`

**Installer doesn't create config:**
- Requires Administrator (elevated) for `C:\ProgramData` write
- If UAC blocks, right-click `.exe` → "Run as administrator"

## Alternative (Legacy) Approach

The `deploy/windows/build-installer.sh` script uses the **Python-embeddable** method (Python zip + wheel extraction + batch launchers). It still works but **does NOT use PyInstaller**. Prefer `build-all.sh` for single-file bundle approach.

---

Last updated: 2026-05-01 by Lisa (Hermes AI)
