127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
# Windows / WSL auto-start
|
|
|
|
Hermes WebUI runs well under WSL2, but native Windows login does not automatically start Linux user processes. This guide covers two supported options:
|
|
|
|
1. **WSL session startup** — simple and low-risk. WebUI starts the next time you open a WSL shell.
|
|
2. **Windows Task Scheduler** — true Windows logon startup. Windows invokes `wsl.exe`, which runs the WSL launch script.
|
|
|
|
Both paths use the same WSL launch script:
|
|
|
|
```text
|
|
scripts/wsl/hermes_webui_autostart.sh
|
|
```
|
|
|
|
The script is safe to call repeatedly. It uses a lock file, checks the `/health` endpoint, checks a pid file, and writes logs before starting `start.sh --foreground` in the background. It does not hardcode a user path; by default it derives the repository root from its own location.
|
|
|
|
## Script settings
|
|
|
|
The WSL launcher supports these environment variables:
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `HERMES_WEBUI_REPO` | repo containing the script | WebUI checkout to start |
|
|
| `HERMES_WEBUI_LOG_DIR` | `$HOME/.hermes/webui/logs` | Autostart and WebUI logs |
|
|
| `HERMES_WEBUI_HOST` | `127.0.0.1` | Host passed through to `start.sh` / `bootstrap.py` |
|
|
| `HERMES_WEBUI_PORT` | `8787` | WebUI port and health-check port |
|
|
| `HERMES_WEBUI_HEALTH_URL` | `http://127.0.0.1:$HERMES_WEBUI_PORT/health` | URL used to decide whether WebUI is already running |
|
|
| `HERMES_WEBUI_PID_FILE` | `$HERMES_WEBUI_LOG_DIR/hermes-webui.pid` | pid file used for duplicate prevention |
|
|
| `HERMES_WEBUI_REQUIRE_AGENT_PROCESS` | `0` | Optional: set to `1` only if your local setup requires a separate Hermes process before WebUI starts |
|
|
|
|
Make the script executable once inside WSL:
|
|
|
|
```bash
|
|
cd /path/to/hermes-webui
|
|
chmod +x scripts/wsl/hermes_webui_autostart.sh
|
|
```
|
|
|
|
Run it manually to verify your paths and logs:
|
|
|
|
```bash
|
|
scripts/wsl/hermes_webui_autostart.sh
|
|
curl -fsS http://127.0.0.1:8787/health
|
|
```
|
|
|
|
Logs are written to:
|
|
|
|
```text
|
|
$HOME/.hermes/webui/logs/webui_autostart.log
|
|
$HOME/.hermes/webui/logs/hermes_webui.log
|
|
```
|
|
|
|
## Option 1: WSL session startup
|
|
|
|
This starts WebUI when your WSL login shell starts. It is the easiest option if you already open WSL during your day.
|
|
|
|
Add this to `~/.profile` or `~/.bashrc` inside WSL, adjusting the repo path:
|
|
|
|
```bash
|
|
if [ -x "$HOME/hermes-webui/scripts/wsl/hermes_webui_autostart.sh" ]; then
|
|
HERMES_WEBUI_REPO="$HOME/hermes-webui" \
|
|
"$HOME/hermes-webui/scripts/wsl/hermes_webui_autostart.sh" >/dev/null 2>&1 &
|
|
fi
|
|
```
|
|
|
|
Open a new WSL terminal and check:
|
|
|
|
```bash
|
|
curl -fsS http://127.0.0.1:8787/health
|
|
```
|
|
|
|
If you open several WSL terminals, the launcher should still start only one WebUI process because the lock, health check, and pid file all converge on "already running".
|
|
|
|
## Option 2: Windows Task Scheduler startup
|
|
|
|
Use this if you want WebUI to start automatically at Windows logon even before you open a WSL terminal.
|
|
|
|
The helper PowerShell script is:
|
|
|
|
```text
|
|
scripts/windows/setup_webui_autostart.ps1
|
|
```
|
|
|
|
From Windows PowerShell, run it with the WSL path to the launch script:
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
|
.\scripts\windows\setup_webui_autostart.ps1 `
|
|
-WslScriptPath "/home/your-user/hermes-webui/scripts/wsl/hermes_webui_autostart.sh" `
|
|
-Distro "Ubuntu"
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `-Distro` is optional. Omit it to use your default WSL distro.
|
|
- The default task name is `HermesWebUIAutoStart`; pass `-TaskName` if you need a different name.
|
|
- The script is idempotent: rerunning it updates the existing scheduled task instead of creating duplicates.
|
|
- The task runs as the current Windows user at logon with least privilege.
|
|
- Add `-WhatIf` to preview the scheduled task registration.
|
|
- Add `-RunNow` to start the task immediately after registration.
|
|
- Add `-SkipValidation` only if you need to register the task before the WSL path exists.
|
|
|
|
To inspect or remove the task later:
|
|
|
|
```powershell
|
|
Get-ScheduledTask -TaskName HermesWebUIAutoStart
|
|
Unregister-ScheduledTask -TaskName HermesWebUIAutoStart -Confirm:$false
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
Check the WSL logs first:
|
|
|
|
```bash
|
|
tail -n 80 "$HOME/.hermes/webui/logs/webui_autostart.log"
|
|
tail -n 80 "$HOME/.hermes/webui/logs/hermes_webui.log"
|
|
```
|
|
|
|
Common causes:
|
|
|
|
| Symptom | Likely cause | Fix |
|
|
|---|---|---|
|
|
| Task exists but WebUI is not reachable | WSL script path is wrong for the selected distro | Re-run the PowerShell setup with the correct `-WslScriptPath` and `-Distro` |
|
|
| WebUI starts only after opening WSL | You used the WSL session startup option, not Task Scheduler | Install the Windows scheduled task |
|
|
| Multiple login events happen quickly | Normal Windows startup behavior | The WSL script should log `already running` and avoid duplicate processes |
|
|
| Health check fails but pid exists | WebUI is still booting or the port differs | Check `HERMES_WEBUI_PORT` and `hermes_webui.log` |
|
|
|
|
If you want WSL2 systemd integration instead, see `docs/supervisor.md` for foreground process-supervisor guidance and adapt the Linux `systemd --user` pattern to your distro.
|