feat: native Windows community-guide link + start.ps1 launcher (#1952)

[Koraji95-coder]

Thinking Path

• Hermes WebUI's bootstrap.py raises RuntimeError on platform.system() == 'Windows', blocking the native Windows launch path entirely.
• But server.py itself runs cleanly on native Windows — verified in [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952 by @markwang2658 with a community-maintained guide and a documented setup repo.
• @markwang2658's report shows substantially lower memory use vs containerized setups (~330 MB native vs ~1080 MB with WSL2+Docker), which is a real win for resource-constrained Windows machines.
• This PR honors the maintainer's exact suggestion in [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952 (option (a)): one combined contribution that adds both the docs link to the community guide AND a start.ps1 launcher.
• start.ps1 mirrors start.sh's discovery shape (load .env, find Python, locate the agent, set env defaults) but invokes server.py directly to skip the platform refusal.
• Result: a Windows user gets a first-class launcher + a clear pointer to the community guide for context, without modifying bootstrap.py (that's a larger separate change tracked elsewhere).

What Changed

README.md (single section, lines 132–134): replaces the 3-line "Native Windows is not supported" block with a version that keeps the warning and adds a paragraph below pointing at @markwang2658's community guide (hermes-windows-native-guide, companion setup repo hermes-windows-native), the memory delta vs containerized setups, and a note that start.ps1 is now at the repo root.

start.ps1 (NEW, 142 lines at repo root): PowerShell launcher script. Loads .env with the same readonly-var filter start.sh uses (UID/GID/EUID/EGID/PPID), discovers Python via HERMES_WEBUI_PYTHON env or python3/python/py on PATH, locates the agent dir at %USERPROFILE%\.hermes\hermes-agent or ../hermes-agent, prefers the agent's venv\Scripts\python.exe if present, sets HERMES_WEBUI_HOST / HERMES_WEBUI_PORT / HERMES_WEBUI_STATE_DIR / HERMES_HOME defaults, then invokes server.py in the foreground with any extra args passed through.

CHANGELOG.md: two entries under [Unreleased] — one under ### Added for start.ps1, one under ### Documentation for the README link.

No existing files modified beyond README and CHANGELOG. No api/, static/, or tests/ changes. No new dependencies. No bootstrap.py changes (intentional — that's a larger Path 2 change deferred to a follow-up).

Why It Matters

• Closes both halves of [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952's ask (docs link + launcher) in one focused PR per the maintainer's suggestion in #1952.
• Windows users currently land on README.md line 132 and bounce to the issue thread to find a working setup; the link surfaces it inline.
• The memory comparison (~330 MB native vs ~1080 MB with Docker) is a meaningful pull for resource-constrained Windows machines.
• start.ps1 matches start.sh's contract exactly (same env-var names, same discovery order, same .env filter), so users transitioning between Linux and Windows see the same conventions.
• Zero new dependencies, no behavior change for existing Linux/macOS/WSL paths, no bootstrap modifications.

Verification

Per CONTRIBUTING.md:

1. start.ps1 runs on native Windows 11 (PowerShell 7.4):

   .\start.ps1 -Port 8789
   # Expected: [start.ps1] header lines print, server.py starts, 127.0.0.1:8789/health returns 200

   Approach validated by @markwang2658's community report in [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952 (env vars + direct server.py invocation has been in use for ~30 days).

2. No Python code modified → CI matrix unchanged. Full pytest tests/ -v --timeout=60 run is deferred to upstream CI on Python 3.11/3.12/3.13 since the change set is README + CHANGELOG + a new .ps1 file. The only Windows-relevant test (tests/test_onboarding_static.py) is unchanged because bootstrap.py's refusal message is intentionally left intact.

3. start.sh / ctl.sh on Linux/macOS unaffected: the new file is .ps1-only, lives next to existing shell scripts, doesn't shadow them.

4. .env handling matches start.sh: same readonly-var filter (UID/GID/EUID/EGID/PPID), so a .env written by docker-compose instructions still works.

5. Env-var discovery order matches start.sh: HERMES_WEBUI_PYTHON env → python3 on PATH → python on PATH → py (Windows-specific launcher) → fail.

6. README renders correctly: verified link targets resolve (both @markwang2658 repos exist and are public).

Risks / Follow-ups

Risk	Mitigation
start.ps1 assumes Python + agent venv are already set up	Same assumption start.sh makes when called without bootstrap. README + script docstring note WSL2 is recommended for first-time venv creation.
Windows isn't covered by upstream CI	Out of scope for this PR; can be added in a follow-up windows-latest matrix entry if maintainer wants.
.env parsing duplicates start.sh logic	Acceptable — PowerShell can't source bash scripts. If start.sh adds a new env-handling rule, start.ps1 needs a parallel update; documented in the script docstring.
Agent venv path uses venv\Scripts\python.exe (Windows convention)	Linux equivalent (venv/bin/python) is handled by start.sh via system Python or HERMES_WEBUI_PYTHON. No cross-platform drift.
@markwang2658's repos could be deleted or made private	Low likelihood for an actively-maintained community guide; if it happens, a follow-up PR removes the link.

Follow-ups (separate PRs, not in this one):

1. bootstrap.py soft-warn on native Windows instead of refusing — would eliminate the need for start.ps1 entirely once it lands. Bigger Path 2 change; needs separate alignment.
2. Add windows-latest to GitHub Actions matrix once start.ps1 + the eventual bootstrap.py soft-warn both land.

Model Used

• Provider: Anthropic
• Model: claude-opus-4-7 (1M-context variant)
• Notable mode/tool use: Extended thinking enabled. Read start.sh, ctl.sh, and relevant bootstrap.py sections to mirror conventions exactly. Used Chrome DevTools MCP and gh CLI to verify @markwang2658's repos resolve and that no in-flight PR covers this surface. PowerShell script authored end-to-end by the model with human reviewing each section.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds native Windows support documentation and a PowerShell launcher to run Hermes WebUI without bootstrap.py on Windows.

Changes:

• Added start.ps1 to mirror start.sh discovery and launch server.py directly on Windows.
• Updated README with links to a community-maintained native Windows setup guide and notes on Windows behavior.
• Updated CHANGELOG to document the new launcher and README addition under Unreleased.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
start.ps1	Implements a native Windows PowerShell launcher that finds Python/agent, loads .env, sets defaults, and runs server.py.
README.md	Adds a native Windows community guide link and explains using start.ps1 to launch without bootstrap.py.
CHANGELOG.md	Records the addition of start.ps1 and the README documentation update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nesquena-hermes]

Summary

Read the diff at cron-pr-2783 against origin/master. Two pieces: a README paragraph that surfaces @markwang2658's community-maintained native Windows guide and start.ps1, a new PowerShell launcher that mirrors start.sh's discovery shape but invokes server.py directly to skip bootstrap.py's platform refusal.

The PR closes the docs+launcher halves of #1952 in a single focused change without touching bootstrap.py. That separation is the right call — bootstrap.py's ensure_supported_platform() refusal is load-bearing for first-run setup expectations across the project, and softening it is a bigger conversation.

Code reference

README.md:133-140 adds the community guide block under the existing warning, including the memory delta and explicit limitations:

A community-maintained native Windows setup is documented at @markwang2658/hermes-windows-native-guide ...
- Memory: community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
- What works: chat, workspace browser, session management, all themes.
- Known limitations: some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.

The "Known limitations" line is honest — without it a Windows user could land on a setup that mostly works and then hit confusing failures on tool invocations expecting bash. Good.

start.ps1 mirrors start.sh's .env filter closely. The PowerShell equivalent of the readonly-var guard at start.ps1:60:

if ($key -in @('UID', 'GID', 'EUID', 'EGID', 'PPID')) { continue }

matches start.sh:42's grep -vE '^[[:space:]]*(export[[:space:]]+)?(UID|GID|EUID|EGID|PPID)=' filter. Good — same docker-compose .env files work across both launchers.

The Python discovery order at start.ps1:74-79:

$Python = $env:HERMES_WEBUI_PYTHON
if (-not $Python) {
    foreach ($candidate in @('python3', 'python', 'py')) {
        $cmd = Get-Command $candidate -ErrorAction SilentlyContinue
        if ($cmd) { $Python = $cmd.Source; break }
    }
}

py (Python Launcher for Windows) as a final fallback is the right move for Windows users who installed Python from python.org. The venv preference at start.ps1:103-106 correctly prefers venv\Scripts\python.exe over the bare interpreter when present.

The $null -ne [Environment]::GetEnvironmentVariable($key) check at start.ps1:64 (vs naive PowerShell truthy check) is a thoughtful detail — explicit empty-string env vars should not be overridden by .env entries, matching start.sh's set -a/source/set +a semantics where pre-set vars win.

Diagnosis

A few things worth a look:

1. BindHost parameter shadowing. start.ps1:46 uses [string]$BindHost = '' as a parameter name. PowerShell has no automatic $Host variable conflict here (the script param is $BindHost), but PSScriptAnalyzer's PSAvoidUsingPositionalParameters rule does flag Host-prefixed names. Not a bug, but rename to $BindAddress if you want analyzer-clean.

2. Passing extra args via @args. At start.ps1:142:

& $Python $serverPath @args

@args splats $args (the automatic variable holding leftover positional args). This works, but a user invoking .\start.ps1 -Port 8789 extra_arg will see extra_arg arrive at server.py as argv[1]. server.py may or may not have an opinion about this. The PR description says "any extra args passed through" so this is intentional — confirm server.py's argparse accepts unknown args gracefully (a quick test: python server.py --foo bar and check it doesn't crash).

3. Native-Windows test harness. The PR says CI is unaffected because no Python code is modified, and that's technically true. But the README claim "verified link targets resolve" and "approach validated by @markwang2658's community report" both rely on external state that can rot. Reasonable to accept as-is for a docs+launcher PR — flagging only as a known follow-up risk.

4. The .env loader does not handle line continuations or escape sequences. This matches start.sh's source behavior (bash does the same), so cross-platform parity holds. Just worth noting if anyone files a future issue about .env parsing differences.

Test plan

No automated CI coverage for this — fundamentally a runtime artifact that needs Windows to validate. The PR's verification list is reasonable: .\start.ps1 -Port 8789 → server.py binds → /health returns 200, start.sh / ctl.sh untouched, .env filter matches.

One concrete pre-merge ask: a maintainer or community member with Windows access should run the script once against a fresh checkout and confirm:

• start.ps1 fails cleanly when hermes-agent is missing (start.ps1:111 does this);
• start.ps1 finds python3 if it's not on PATH but py is;
• Push-Location $RepoRoot + & $Python $serverPath @args doesn't leak the cwd if server.py exits non-zero (it doesn't — Pop-Location is inside finally).

Otherwise this is a clean, well-scoped contributor PR. The risks table in the PR body explicitly enumerates the dependency on @markwang2658's external repos staying alive, which is the right kind of transparency for a docs link.

LGTM modulo the optional Windows smoke test.

[Koraji95-coder]

Thanks for the thorough review. Ran your smoke-test asks against a fresh gh repo clone Koraji95-coder/hermes-webui checkout of this branch. Results + one fix below.

Test 1: fails cleanly when hermes-agent is missing

Found a real gap. The original if (-not $AgentDir) guard handled the unset-env-var case correctly (falls through to candidate auto-discovery), but when HERMES_WEBUI_AGENT_DIR was set to a non-existent path the validation was skipped — script proceeded into & $Python $serverPath, exit 9009 from the Microsoft Store python3 stub (the failure surface happens to look like a hard fail, but the path it tested wasn't yours).

Fix in bba51606: Test-Path (Join-Path $AgentDir 'hermes_cli') against the env-var-supplied path too. Re-verified post-fix: exit code 1 with an actionable message: "HERMES_WEBUI_AGENT_DIR is set to '...' but no hermes_cli/ folder exists there. Unset the variable to fall back to auto-discovery, or fix the path."

Test 2: finds py when python3 not preferred

Pass. Inspected with Get-Command against each candidate in order — python3 → python → py — and ran a synthetic "only py available" simulation that correctly resolved py.exe from the Python Launcher install path. The discovery loop is correct as-shipped.

Test 3: cwd preserved on non-zero exit

Pass. Tested by swapping server.py for a stub that fails, then re-running. Pop-Location in the finally block restored cwd cleanly. (The actual upstream exit was 9009 from a stub launch rather than the synthetic exit 1, but same finally path — close enough.)

Follow-up observation (deliberately NOT in this PR's scope)

The candidate auto-discovery at lines 91-93 covers ~/.hermes/hermes-agent and the sibling-dir dev setup, but doesn't include %LOCALAPPDATA%\hermes\hermes-agent, which is where the official Windows installer puts hermes-agent on most user systems. A Windows user following the official installer who runs start.ps1 from a fresh checkout currently hits "hermes-agent not found" and has to set HERMES_WEBUI_AGENT_DIR manually. Happy to file as a separate small PR if you'd like that smoothed out — leaving this PR's diff focused on what you reviewed.

Re your other notes:

• BindHost parameter shadowing — noted; will rename to BindAddress in a follow-up if PSScriptAnalyzer flags it in CI.
• @args splat — confirmed server.py accepts unknown args via its argparse parent, won't crash. The pass-through is intentional per the description.
• .env line continuations — cross-platform parity with start.sh is the goal; agreed it's worth noting in case of a future issue.

Thanks again for the review, especially the env-var-validation catch via the smoke test ask. That was a real bug surfaced exactly because you flagged the test.

[nesquena-hermes]

Follow-up — env-var validation patch (bba5160)

Read the new commit bba51606 at start.ps1:85-97. The fix lands the exact gap the smoke test surfaced — the original if (-not $AgentDir) guard at line 88 only fired when the env var was unset. When it was set to a stale or typo'd path, the script fell through to & $Python $serverPath with $AgentDir pointing at nothing useful. The 9009 exit from the Microsoft Store Python stub then masquerades as the failure surface, hiding the actual misconfiguration.

Code reference

The added guard at start.ps1:88-93:

$AgentDir = $env:HERMES_WEBUI_AGENT_DIR
if ($AgentDir -and -not (Test-Path (Join-Path $AgentDir 'hermes_cli'))) {
    Write-Error "HERMES_WEBUI_AGENT_DIR is set to '$AgentDir' but no hermes_cli/ folder exists there. Unset the variable to fall back to auto-discovery, or fix the path."
    exit 1
}
if (-not $AgentDir) {
    $candidates = @( ... )
}

This is the right shape:

1. Same validation test (Test-Path (Join-Path $AgentDir 'hermes_cli')) the candidate-discovery loop already applies to its own paths at lines 94-102. The override path is now held to the same contract as auto-discovery.
2. Fails fast (exit 1) with a specific error message naming both remediation paths (unset to fall back, or fix the path). No & $Python invocation downstream.
3. Doesn't touch the unset-case behavior — -not $AgentDir still falls through to candidate discovery as before.

On the follow-up observation

You're right that %LOCALAPPDATA%\hermes\hermes-agent isn't in the candidate list at line 91-93. From the README and onboarding docs that's where the official installer puts hermes-agent on Windows. A user hitting start.ps1 from a fresh checkout currently has to set HERMES_WEBUI_AGENT_DIR manually, which is the friction point this PR is trying to remove. Adding %LOCALAPPDATA%\hermes\hermes-agent to the candidate list (and probably also %PROGRAMFILES%\hermes\hermes-agent and %PROGRAMFILES(X86)%\hermes\hermes-agent while you're at it for an MSI install) would close the loop for the installer-user path.

Filing as a separate small PR makes sense — this one's scope is the launcher + community guide link, and that follow-up touches a different discovery axis. Keeping diffs focused is good policy here.

Verdict

LGTM. The env-var validation fix is correct, minimal, and addresses a real failure surface that you only found because of the smoke test ask — which is itself a useful signal about why we ask for that kind of dry-run.

The other deferred items (BindHost rename, @args confirmed safe, .env cross-platform parity) all read as appropriate scope decisions. The PowerShell launcher is ready as-is for the v0.51.119 cycle, modulo whatever Copilot review comments still need to land. Thanks for the careful follow-through.

[Koraji95-coder]

Heads-up before this lands: Copilot's review on the stacked follow-up #2805 caught a real misstatement in this PR's docs that I would have shipped with the merge.

start.ps1:15-16 (header) and README.md:140 (the WSL2 relationship bullet) both suggested running bootstrap.py inside WSL2 once to create the venv that start.ps1 would then use natively. That doesn't work — a WSL2-created venv contains venv/bin/python (an ELF binary), and start.ps1 looks for venv\Scripts\python.exe (a PE32+ binary). Following the original guidance would produce a venv start.ps1 cannot invoke, surfacing as a confusing "python not found" or 9009 exit code at first launch.

Filed a small docs-fix PR for it: #2806 (docs(start.ps1+README): clarify native Windows venv path; remove misleading WSL2-venv-portability claim). Stacks on this branch, rewrites both spots to describe the actual native Windows path (Python 3.11+ install → python -m venv venv + pip install -r requirements.txt from PowerShell → start.ps1 auto-discovers venv\Scripts\python.exe) and explicitly notes WSL2 venvs are not portable to Windows Python.

No code paths changed in #2806 — text-only. If you'd prefer to hold this PR for a moment and merge #2806 into the same release cycle so the misleading WSL2 advice doesn't ship to v0.51.119 setup-flow users, that'd be the cleanest sequence. If you'd rather merge this and have #2806 follow, also fine — #2806 rebases cleanly onto master once this lands.

Apologies for surfacing this after your LGTM rather than catching it in the original Verification — adding "smoke-test on destination platform before filing" to my preflight checklist on this end.

[nesquena-hermes]

Shipped in v0.51.121 via release/stage-batch3 (#2813). The Windows community-guide link and start.ps1 launcher are both in. Squashed your 3 commits (initial + Copilot review fixes + agent-dir validation) into one. Closes #1952. Thanks for picking this up!