From 9de893e3b078e7ef51437af1ce6743d96a103c6d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Thu, 7 May 2026 16:31:40 -0700 Subject: [PATCH] =?UTF-8?q?feat(windows):=20close=20native-Windows=20insta?= =?UTF-8?q?ll=20gaps=20=E2=80=94=20crash-free=20startup,=20UTF-8=20stdio,?= =?UTF-8?q?=20tzdata=20dep,=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Native Windows (with Git for Windows installed) can now run the Hermes CLI and gateway end-to-end without crashing. install.ps1 already existed and the Git Bash terminal backend was already wired up — this PR fills the remaining gaps discovered by auditing every Windows-unsafe primitive (`signal.SIGKILL`, `os.kill(pid, 0)` probes, bare `fcntl`/`termios` imports) and by comparing hermes against how Claude Code, OpenCode, Codex, and Cline handle native Windows. ## What changed ### UTF-8 stdio (new module) - `hermes_cli/stdio.py` — single `configure_windows_stdio()` entry point. Flips the console code page to CP_UTF8 (65001), reconfigures `sys.stdout`/`stderr`/`stdin` to UTF-8, sets `PYTHONIOENCODING` + `PYTHONUTF8` for subprocesses. No-op on non-Windows. Opt out via `HERMES_DISABLE_WINDOWS_UTF8=1`. - Called early in `cli.py::main`, `hermes_cli/main.py::main`, and `gateway/run.py::main` so Unicode banners (box-drawing, geometric symbols, non-Latin chat text) don't `UnicodeEncodeError` on cp1252 consoles. ### Crash sites fixed - `hermes_cli/main.py:7970` (hermes update → stuck gateway sweep): raw `os.kill(pid, _signal.SIGKILL)` → `gateway.status.terminate_pid(pid, force=True)` which routes through `taskkill /T /F` on Windows. - `hermes_cli/profiles.py::_stop_gateway_process`: same fix — also converted SIGTERM path to `terminate_pid()` and widened OSError catch on the intermediate `os.kill(pid, 0)` probe. - `hermes_cli/kanban_db.py:2914, 3041`: raw `signal.SIGKILL` → `getattr(signal, "SIGKILL", signal.SIGTERM)` fallback (matches the pattern already used in `gateway/status.py`). ### OSError widening on `os.kill(pid, 0)` probes Windows raises `OSError` (WinError 87) for a gone PID instead of `ProcessLookupError`. Widened the catch at: - `gateway/run.py:15101` (`--replace` wait-for-exit loop — without this, the loop busy-spins the full 10s every Windows gateway start) - `hermes_cli/gateway.py:228, 460, 940` - `hermes_cli/profiles.py:777` - `tools/process_registry.py::_is_host_pid_alive` - `tools/browser_tool.py:1170, 1206` ### Dashboard PTY graceful degradation `hermes_cli/pty_bridge.py` depends on `fcntl`/`termios`/`ptyprocess`, none of which exist on native Windows. Previously a Windows dashboard would crash on `import hermes_cli.web_server` because of a top-level import. Now: - `hermes_cli/web_server.py` wraps the pty_bridge import in `try/except ImportError` and sets `_PTY_BRIDGE_AVAILABLE=False`. - The `/api/pty` WebSocket handler returns a friendly "use WSL2 for this tab" message instead of exploding. - Every other dashboard feature (sessions, jobs, metrics, config editor) runs natively on Windows. ### Dependency - `pyproject.toml`: add `tzdata>=2023.3; sys_platform == 'win32'` so Python's `zoneinfo` works on Windows (which has no IANA tzdata shipped with the OS). Credits @sprmn24 (PR #13182). ### Docs - README.md: removed "Native Windows is not supported"; added PowerShell one-liner and Git-for-Windows prerequisite note. - `website/docs/getting-started/installation.md`: new Windows section with capability matrix (everything native except the dashboard `/chat` PTY tab, which is WSL2-only). - `website/docs/user-guide/windows-wsl-quickstart.md`: reframed as "WSL2 as an alternative to native" rather than "the only way". - `website/docs/developer-guide/contributing.md`: updated cross-platform guidance with the `signal.SIGKILL` / `OSError` rules we enforce now. - `website/docs/user-guide/features/web-dashboard.md`: acknowledged native Windows works for everything except the embedded PTY pane. ## Why this shape Pulled from a survey of how other agent codebases handle native Windows (Claude Code, OpenCode, Codex, Cline): - All four treat Git Bash as the canonical shell on Windows, same as hermes already does in `tools/environments/local.py::_find_bash()`. - None of them force `SetConsoleOutputCP` — but they don't have to, Node/Rust write UTF-16 to the Win32 console API. Python does not get that for free, so we flip CP_UTF8 via ctypes. - None of them ship PowerShell-as-primary-shell (Claude Code exposes PS as a secondary tool; scope creep for this PR). - All of them use `taskkill /T /F` for force-kill on Windows, which is exactly what `gateway.status.terminate_pid(force=True)` does. ## Non-goals (deliberate scope limits) - No PowerShell-as-a-second-shell tool — worth designing separately. - No terminal routing rewrite (#12317, #15461, #19800 cluster) — that's the hardest design call and needs a separate doc. - No wholesale `open()` → `open(..., encoding="utf-8")` sweep (Tianworld cluster) — will do as follow-up if users hit actual breakage; most modern code already specifies it. ## Validation - 28 new tests in `tests/tools/test_windows_native_support.py` — all platform-mocked, pass on Linux CI. Cover: - `configure_windows_stdio` idempotency, opt-out, env-preservation - `terminate_pid` taskkill routing, failure → OSError, FileNotFoundError fallback - `getattr(signal, "SIGKILL", …)` fallback shape - `_is_host_pid_alive` OSError widening (Windows-gone-PID behavior) - Source-level checks that all entry points call `configure_windows_stdio` - pty_bridge import-guard present in `web_server.py` - README no longer says "not supported" - 12 pre-existing tests in `tests/tools/test_windows_compat.py` still pass. - `tests/hermes_cli/` ran fully (3909 passed, 9 failures — all confirmed pre-existing on main by stash-test). - `tests/gateway/` ran fully (5021 passed, 1 pre-existing failure). - `tests/tools/test_process_registry.py` + `test_browser_*` pass. - Manual smoke: `import hermes_cli.stdio; import gateway.run; import hermes_cli.web_server` — all clean, `_PTY_BRIDGE_AVAILABLE=True` on Linux (as expected). ## Files - New: `hermes_cli/stdio.py`, `tests/tools/test_windows_native_support.py` - Modified: `cli.py`, `gateway/run.py`, `hermes_cli/main.py`, `hermes_cli/profiles.py`, `hermes_cli/gateway.py`, `hermes_cli/kanban_db.py`, `hermes_cli/pty_bridge.py`, `hermes_cli/web_server.py`, `tools/browser_tool.py`, `tools/process_registry.py`, `pyproject.toml`, `README.md`, and 4 docs pages. Credits to everyone whose prior PR work informed these fixes — see the co-author trailers. All of the PRs listed in `~/.hermes/plans/windows-support-prs.md` fixing `os.kill` / `signal.SIGKILL` / UTF-8 stdio / tzdata / README patterns found the same issues; this PR consolidates them. Co-authored-by: Philip D'Souza <9472774+PhilipAD@users.noreply.github.com> Co-authored-by: Arecanon <42595053+ArecaNon@users.noreply.github.com> Co-authored-by: XiaoXiao0221 <263113677+XiaoXiao0221@users.noreply.github.com> Co-authored-by: Lars Hagen <1360677+lars-hagen@users.noreply.github.com> Co-authored-by: Luan Dias <65574834+luandiasrj@users.noreply.github.com> Co-authored-by: Ruzzgar Co-authored-by: sprmn24 Co-authored-by: adybag14-cyber <252811164+adybag14-cyber@users.noreply.github.com> Co-authored-by: Prasanna28Devadiga <54196612+Prasanna28Devadiga@users.noreply.github.com> --- README.md | 16 +- cli.py | 9 + gateway/run.py | 13 +- hermes_cli/gateway.py | 10 +- hermes_cli/kanban_db.py | 9 +- hermes_cli/main.py | 16 +- hermes_cli/profiles.py | 17 +- hermes_cli/pty_bridge.py | 13 +- hermes_cli/stdio.py | 134 ++++++ hermes_cli/web_server.py | 27 +- pyproject.toml | 6 + tests/tools/test_windows_native_support.py | 408 ++++++++++++++++++ tools/browser_tool.py | 9 + tools/process_registry.py | 6 +- website/docs/developer-guide/contributing.md | 12 +- website/docs/getting-started/installation.md | 29 +- .../docs/user-guide/features/web-dashboard.md | 2 +- .../docs/user-guide/windows-wsl-quickstart.md | 21 +- 18 files changed, 728 insertions(+), 29 deletions(-) create mode 100644 hermes_cli/stdio.py create mode 100644 tests/tools/test_windows_native_support.py diff --git a/README.md b/README.md index 0045858261..be9bccdcbd 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,27 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), [Open ## Quick Install +### Linux, macOS, WSL2, Termux + ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` -Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the platform-specific setup for you. +### Windows (native, PowerShell) + +Run this in PowerShell: + +```powershell +irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex +``` + +Native Windows requires **[Git for Windows](https://git-scm.com/download/win)** to be installed — Hermes uses its bundled Git Bash to run terminal commands, matching how Claude Code and other agents work on Windows. The installer handles everything else (uv, Python 3.11, Node.js, ripgrep, ffmpeg). + +The installer handles the platform-specific setup for you. > **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies. > -> **Windows:** Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command above. +> **Windows:** Native Windows is supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under `%LOCALAPPDATA%\hermes`; WSL2 installs under `~/.hermes` as on Linux. The only Hermes feature that currently needs WSL2 specifically is the browser-based dashboard chat pane (it uses a POSIX PTY — classic CLI and gateway both run natively). After installation: diff --git a/cli.py b/cli.py index ebc2909613..f089d5012b 100644 --- a/cli.py +++ b/cli.py @@ -12433,6 +12433,15 @@ def main( """ global _active_worktree + # Force UTF-8 stdio on Windows before any banner/print() runs — the + # Rich console prints Unicode box-drawing characters that would + # UnicodeEncodeError on cp1252. No-op on Linux/macOS. + try: + from hermes_cli.stdio import configure_windows_stdio + configure_windows_stdio() + except Exception: + pass + # Signal to terminal_tool that we're in interactive mode # This enables interactive sudo password prompts with timeout os.environ["HERMES_INTERACTIVE"] = "1" diff --git a/gateway/run.py b/gateway/run.py index 69c8793f22..1371f9cac3 100644 --- a/gateway/run.py +++ b/gateway/run.py @@ -15269,7 +15269,10 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool = try: os.kill(existing_pid, 0) time.sleep(0.5) - except (ProcessLookupError, PermissionError): + except (ProcessLookupError, PermissionError, OSError): + # OSError covers Windows' WinError 87 "invalid parameter" + # for an already-gone PID — without this the probe loop + # busy-spins for the full 10s on every --replace start. break # Process is gone else: # Still alive after 10s — force kill @@ -15554,6 +15557,14 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool = def main(): """CLI entry point for the gateway.""" + # Force UTF-8 stdio on Windows — gateway logs and startup banner would + # otherwise UnicodeEncodeError on cp1252 consoles. No-op on POSIX. + try: + from hermes_cli.stdio import configure_windows_stdio + configure_windows_stdio() + except Exception: + pass + import argparse parser = argparse.ArgumentParser(description="Hermes Gateway - Multi-platform messaging") diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py index 5f95d0c204..171ca6de38 100644 --- a/hermes_cli/gateway.py +++ b/hermes_cli/gateway.py @@ -232,6 +232,10 @@ def _graceful_restart_via_sigusr1(pid: int, drain_timeout: float) -> bool: # Process still exists but we can't signal it. Treat as alive # so the caller falls back. pass + except OSError: + # Windows raises OSError (WinError 87 "invalid parameter") for + # a gone PID — treat the same as ProcessLookupError. + return True _time.sleep(0.5) # Drain didn't finish in time. return False @@ -458,6 +462,9 @@ def launch_detached_profile_gateway_restart(profile: str, old_pid: int) -> bool: break except PermissionError: pass + except OSError: + # Windows: gone PID raises OSError (WinError 87). + break time.sleep(0.2) subprocess.Popen( cmd, @@ -935,7 +942,8 @@ def stop_profile_gateway() -> bool: try: os.kill(pid, 0) _time.sleep(0.5) - except (ProcessLookupError, PermissionError): + except (ProcessLookupError, PermissionError, OSError): + # OSError covers Windows' WinError 87 for gone PIDs. break if get_running_pid() is None: diff --git a/hermes_cli/kanban_db.py b/hermes_cli/kanban_db.py index f905dd89af..8ce5436df8 100644 --- a/hermes_cli/kanban_db.py +++ b/hermes_cli/kanban_db.py @@ -2911,7 +2911,10 @@ def _terminate_reclaimed_worker( if _pid_alive(pid): try: - kill(int(pid), signal.SIGKILL) + # signal.SIGKILL doesn't exist on Windows; fall back to SIGTERM + # (which maps to TerminateProcess via the stdlib shim). + _sigkill = getattr(signal, "SIGKILL", signal.SIGTERM) + kill(int(pid), _sigkill) info["sigkill"] = True except (ProcessLookupError, OSError): return info @@ -3035,7 +3038,9 @@ def enforce_max_runtime( time.sleep(0.5) if _pid_alive(pid): try: - kill(pid, signal.SIGKILL) + # signal.SIGKILL doesn't exist on Windows. + _sigkill = getattr(signal, "SIGKILL", signal.SIGTERM) + kill(pid, _sigkill) killed = True except (ProcessLookupError, OSError): pass diff --git a/hermes_cli/main.py b/hermes_cli/main.py index a35c53bb07..caa5d6eaef 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -7965,10 +7965,15 @@ def _cmd_update_impl(args, gateway_mode: bool): print( f" ⚠ {len(_stuck)} gateway process(es) ignored SIGTERM — force-killing" ) + from gateway.status import terminate_pid as _terminate_pid for pid in _stuck: try: - os.kill(pid, _signal.SIGKILL) - except (ProcessLookupError, PermissionError): + # Routes through taskkill /T /F on Windows, + # SIGKILL on POSIX — _signal.SIGKILL doesn't + # exist on Windows so the old raw os.kill call + # used to crash the entire update path. + _terminate_pid(pid, force=True) + except (ProcessLookupError, PermissionError, OSError): pass # Give the OS a beat to reap the processes so the # watchers see them exit and respawn. @@ -8774,6 +8779,13 @@ def _build_provider_choices() -> list[str]: def main(): """Main entry point for hermes CLI.""" + # Force UTF-8 stdio on Windows before anything prints. No-op elsewhere. + try: + from hermes_cli.stdio import configure_windows_stdio + configure_windows_stdio() + except Exception: + pass + from hermes_cli._parser import build_top_level_parser parser, subparsers, chat_parser = build_top_level_parser() diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py index 091d259344..e4a5b0093e 100644 --- a/hermes_cli/profiles.py +++ b/hermes_cli/profiles.py @@ -812,7 +812,6 @@ def _cleanup_gateway_service(name: str, profile_dir: Path) -> None: def _stop_gateway_process(profile_dir: Path) -> None: """Stop a running gateway process via its PID file.""" - import signal as _signal import time as _time pid_file = profile_dir / "gateway.pid" @@ -823,19 +822,27 @@ def _stop_gateway_process(profile_dir: Path) -> None: raw = pid_file.read_text().strip() data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)} pid = int(data["pid"]) - os.kill(pid, _signal.SIGTERM) + # Route through terminate_pid so Windows uses the appropriate + # primitive (taskkill / TerminateProcess) — raw os.kill with + # _signal.SIGKILL raises AttributeError at import time on Windows, + # and raw os.kill with SIGTERM doesn't cascade to child processes + # the same way taskkill /T does. + from gateway.status import terminate_pid as _terminate_pid + _terminate_pid(pid) # graceful first # Wait up to 10s for graceful shutdown for _ in range(20): _time.sleep(0.5) try: os.kill(pid, 0) - except ProcessLookupError: + except (ProcessLookupError, OSError): + # OSError covers Windows' WinError 87 "invalid parameter" + # returned for an invalid/gone PID probe. print(f"✓ Gateway stopped (PID {pid})") return # Force kill try: - os.kill(pid, _signal.SIGKILL) - except ProcessLookupError: + _terminate_pid(pid, force=True) + except (ProcessLookupError, OSError): pass print(f"✓ Gateway force-stopped (PID {pid})") except (ProcessLookupError, PermissionError): diff --git a/hermes_cli/pty_bridge.py b/hermes_cli/pty_bridge.py index 66fdb4ac72..fcb858356b 100644 --- a/hermes_cli/pty_bridge.py +++ b/hermes_cli/pty_bridge.py @@ -7,11 +7,14 @@ keystrokes can be fed back in. The only caller today is the Design constraints: -* **POSIX-only.** Hermes Agent supports Windows exclusively via WSL, which - exposes a native POSIX PTY via ``openpty(3)``. Native Windows Python - has no PTY; :class:`PtyUnavailableError` is raised with a user-readable - install/platform message so the dashboard can render a banner instead of - crashing. +* **POSIX-only.** This module depends on ``fcntl``, ``termios``, and + ``ptyprocess``, none of which exist on native Windows Python. Native + Windows ConPTY is a different API (Windows 10 build 17763+) and would + need a separate Windows implementation (``pywinpty``) — that's tracked + as a future enhancement. On native Windows, importing this module + raises :class:`ImportError` and the dashboard's ``/chat`` tab shows a + WSL-recommended banner instead of crashing. Every other feature in the + dashboard (sessions, jobs, metrics, config editor) works natively. * **Zero Node dependency on the server side.** We use :mod:`ptyprocess`, which is a pure-Python wrapper around the OS calls. The browser talks to the same ``hermes --tui`` binary it would launch from the CLI, so diff --git a/hermes_cli/stdio.py b/hermes_cli/stdio.py new file mode 100644 index 0000000000..cfa27e2cab --- /dev/null +++ b/hermes_cli/stdio.py @@ -0,0 +1,134 @@ +"""Windows-safe stdio configuration. + +On Windows, Python's ``sys.stdout``/``sys.stderr`` default to the console's +active code page (often ``cp1252``, sometimes ``cp437``, occasionally ``cp932`` +on Japanese locales, etc.). Hermes's banners, tool output feed, and slash +command listings all contain Unicode: box-drawing characters (``─┌┐└┘├┤``), +mathematical and geometric symbols (``◆ ◇ ◎ ▣ ⚔ ⚖ →``), and user-supplied +text in any language. Printing those to a cp1252 console raises +``UnicodeEncodeError: 'charmap' codec can't encode character…`` and kills the +whole CLI before the REPL even opens. + +The fix is to force UTF-8 on the Python side and also flip the console's +code page to UTF-8 (65001). Both matter: Python-level only helps when +Python's stdout is a real TTY; code-page flipping lets subprocesses and +child Python ``print()`` calls agree on encoding. + +This module is a no-op on every non-Windows platform, and idempotent. +Entry points (``cli.py`` ``main``, ``hermes_cli/main.py`` CLI dispatch, +``gateway/run.py`` startup) call :func:`configure_windows_stdio` exactly +once early in startup. + +Patterns cribbed from Claude Code (``src/utils/platform.ts``), OpenCode +(``packages/opencode/src/pty/index.ts`` env injection), and OpenAI Codex +(``codex-rs/core/src/unified_exec/process_manager.rs``). None of those +actually flip the console code page — they rely on their runtime (Node or +Rust) writing UTF-16 to the Win32 console API and letting the terminal +sort it out. Python doesn't get that luxury. +""" + +from __future__ import annotations + +import os +import sys + +__all__ = ["configure_windows_stdio", "is_windows"] + + +_CONFIGURED = False + + +def is_windows() -> bool: + """Return True iff running on native Windows (not WSL).""" + return sys.platform == "win32" + + +def _flip_console_code_page_to_utf8() -> None: + """Set the attached console's input and output code pages to UTF-8. + + Uses ``SetConsoleCP`` / ``SetConsoleOutputCP`` via ``ctypes``. Failure + is silent — if there's no attached console (e.g. Hermes is running + behind a redirected stdout, under a service, or inside a PTY-less CI + runner) these calls simply return 0 and we move on. + + CP_UTF8 is 65001. + """ + try: + import ctypes + + kernel32 = ctypes.windll.kernel32 # type: ignore[attr-defined] + # Best-effort; if there's no console attached these just fail silently. + kernel32.SetConsoleCP(65001) + kernel32.SetConsoleOutputCP(65001) + except Exception: + # ctypes import, missing kernel32, or non-Windows — any failure here + # is non-fatal. We've still reconfigured Python's own streams below. + pass + + +def _reconfigure_stream(stream, *, encoding: str = "utf-8", errors: str = "replace") -> None: + """Reconfigure a text stream to UTF-8 in place. + + Uses ``TextIOWrapper.reconfigure`` (Python 3.7+). If the stream isn't + a ``TextIOWrapper`` (e.g. it's been redirected to an ``io.StringIO`` + during tests), we skip rather than blow up. + """ + try: + reconfigure = getattr(stream, "reconfigure", None) + if reconfigure is None: + return + reconfigure(encoding=encoding, errors=errors) + except Exception: + pass + + +def configure_windows_stdio() -> bool: + """Force UTF-8 stdio on Windows. No-op elsewhere. + + Idempotent — safe to call multiple times from different entry points. + + Returns ``True`` if anything was actually changed, ``False`` on + non-Windows or on a repeat call. + + Set ``HERMES_DISABLE_WINDOWS_UTF8=1`` in the environment to opt out + (for diagnosing encoding-related bugs by forcing the old cp1252 path). + """ + global _CONFIGURED + + if _CONFIGURED: + return False + if not is_windows(): + # Mark configured so repeated calls on POSIX are true no-ops. + _CONFIGURED = True + return False + + if os.environ.get("HERMES_DISABLE_WINDOWS_UTF8") in ("1", "true", "True", "yes"): + _CONFIGURED = True + return False + + # Encourage every child Python process spawned by the agent to also use + # UTF-8 for its stdio. PYTHONIOENCODING wins over the locale-based + # default in subprocesses. Don't override an explicit user setting. + os.environ.setdefault("PYTHONIOENCODING", "utf-8") + # PYTHONUTF8 = 1 enables UTF-8 Mode globally for any Python subprocess + # (PEP 540). Again, don't override an explicit setting. + os.environ.setdefault("PYTHONUTF8", "1") + + # Flip the console code page first so that any subprocess that + # inherits the console (e.g. a launched shell) also sees CP_UTF8. + _flip_console_code_page_to_utf8() + + # Reconfigure Python's own stdio wrappers so ``print()`` calls from + # this process round-trip emoji / box-drawing / non-Latin text. + # ``errors="replace"`` means a genuinely unencodable byte sequence + # gets a ``?`` rather than crashing the interpreter — we prefer + # degraded output over a stack trace. + _reconfigure_stream(sys.stdout) + _reconfigure_stream(sys.stderr) + # stdin is re-configured for completeness; Hermes's interactive + # input path uses prompt_toolkit which manages its own encoding, + # but batch/pipe input benefits from UTF-8 decoding on stdin too. + _reconfigure_stream(sys.stdin) + + _CONFIGURED = True + return True diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py index 46786455ce..b3a4209b33 100644 --- a/hermes_cli/web_server.py +++ b/hermes_cli/web_server.py @@ -2979,7 +2979,20 @@ async def get_models_analytics(days: int = 30): import re import asyncio -from hermes_cli.pty_bridge import PtyBridge, PtyUnavailableError +# PTY bridge is POSIX-only (depends on fcntl/termios/ptyprocess). On native +# Windows the import raises; catch and leave PtyBridge=None so the rest of +# the dashboard (sessions, jobs, metrics, config editor) still loads and the +# /api/pty endpoint cleanly refuses with a WSL-suggested message. +try: + from hermes_cli.pty_bridge import PtyBridge, PtyUnavailableError + _PTY_BRIDGE_AVAILABLE = True +except ImportError as _pty_import_err: # pragma: no cover - Windows-only path + PtyBridge = None # type: ignore[assignment] + _PTY_BRIDGE_AVAILABLE = False + + class PtyUnavailableError(RuntimeError): # type: ignore[no-redef] + """Stub on platforms where pty_bridge can't be imported.""" + pass _RESIZE_RE = re.compile(rb"\x1b\[RESIZE:(\d+);(\d+)\]") _PTY_READ_CHUNK_TIMEOUT = 0.2 @@ -3113,6 +3126,18 @@ async def pty_ws(ws: WebSocket) -> None: await ws.accept() + # On native Windows, the POSIX PTY bridge can't be imported. Tell the + # client and close cleanly rather than pretending the feature works. + if not _PTY_BRIDGE_AVAILABLE: + await ws.send_text( + "\r\n\x1b[31mChat unavailable: the embedded terminal requires a " + "POSIX PTY, which native Windows Python doesn't provide.\x1b[0m\r\n" + "\x1b[33mInstall Hermes inside WSL2 to use the dashboard's /chat " + "tab — the rest of the dashboard works here.\x1b[0m\r\n" + ) + await ws.close(code=1011) + return + # --- spawn PTY ------------------------------------------------------ resume = ws.query_params.get("resume") or None channel = _channel_or_close_code(ws) diff --git a/pyproject.toml b/pyproject.toml index 55297554cf..8b5c4c156e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,6 +36,12 @@ dependencies = [ "edge-tts>=7.2.7,<8", # Skills Hub (GitHub App JWT auth — optional, only needed for bot identity) "PyJWT[crypto]>=2.12.0,<3", # CVE-2026-32597 + # Windows has no IANA tzdata shipped with the OS, so Python's ``zoneinfo`` + # (PEP 615) raises ``ZoneInfoNotFoundError`` for every non-UTC timezone + # out of the box. ``tzdata`` ships the Olson database as a data package + # Python resolves automatically. No-op on Linux/macOS (which have + # /usr/share/zoneinfo). Credits: PR #13182 (@sprmn24). + "tzdata>=2023.3; sys_platform == 'win32'", ] [project.optional-dependencies] diff --git a/tests/tools/test_windows_native_support.py b/tests/tools/test_windows_native_support.py new file mode 100644 index 0000000000..1503bf1124 --- /dev/null +++ b/tests/tools/test_windows_native_support.py @@ -0,0 +1,408 @@ +"""Behavioral tests for Windows-specific compatibility fixes. + +Complements ``tests/tools/test_windows_compat.py`` (which does source-level +pattern linting) with cross-platform-mocked tests that exercise the actual +code paths Hermes takes on native Windows. + +Runs on Linux CI — every test mocks ``sys.platform``, ``subprocess.run``, +and ``os.kill`` as needed to simulate Windows behavior without requiring a +Windows runner. +""" + +from __future__ import annotations + +import importlib +import os +import signal +import subprocess +import sys +from pathlib import Path +from unittest.mock import MagicMock, patch + +import pytest + + +# --------------------------------------------------------------------------- +# configure_windows_stdio +# --------------------------------------------------------------------------- + + +class TestConfigureWindowsStdio: + """``hermes_cli.stdio.configure_windows_stdio`` wiring. + + The function must: + - be a no-op on non-Windows + - only configure once per process (idempotent) + - set PYTHONIOENCODING / PYTHONUTF8 without overriding explicit user settings + - reconfigure sys.stdout/stderr/stdin to UTF-8 on Windows + - flip the console code page to CP_UTF8 (65001) via ctypes + - respect HERMES_DISABLE_WINDOWS_UTF8 opt-out + """ + + @pytest.fixture(autouse=True) + def _reset_configured(self, monkeypatch): + """Reload the module before each test so the _CONFIGURED flag resets.""" + # Remove from sys.modules so import triggers a fresh load + sys.modules.pop("hermes_cli.stdio", None) + # Fresh import now; tests import from hermes_cli.stdio themselves, + # but this guarantees the module they get is a brand-new copy. + import hermes_cli.stdio as _s + _s._CONFIGURED = False + yield + sys.modules.pop("hermes_cli.stdio", None) + + def test_no_op_on_posix(self): + from hermes_cli import stdio + + assert stdio.is_windows() is False + result = stdio.configure_windows_stdio() + assert result is False + + def test_idempotent(self): + from hermes_cli import stdio + + stdio.configure_windows_stdio() + # Second call returns False because _CONFIGURED is set + assert stdio.configure_windows_stdio() is False + + def test_windows_path_sets_env_and_reconfigures_streams(self, monkeypatch): + from hermes_cli import stdio + + monkeypatch.setattr(stdio, "is_windows", lambda: True) + # Pretend the user has no prior setting + monkeypatch.delenv("PYTHONIOENCODING", raising=False) + monkeypatch.delenv("PYTHONUTF8", raising=False) + monkeypatch.delenv("HERMES_DISABLE_WINDOWS_UTF8", raising=False) + + reconfigure_calls = [] + + def fake_reconfigure(stream, *, encoding="utf-8", errors="replace"): + reconfigure_calls.append((stream, encoding, errors)) + + cp_calls = [] + + def fake_flip(): + cp_calls.append(True) + + monkeypatch.setattr(stdio, "_reconfigure_stream", fake_reconfigure) + monkeypatch.setattr(stdio, "_flip_console_code_page_to_utf8", fake_flip) + + result = stdio.configure_windows_stdio() + assert result is True + assert os.environ.get("PYTHONIOENCODING") == "utf-8" + assert os.environ.get("PYTHONUTF8") == "1" + assert len(cp_calls) == 1 # SetConsoleOutputCP path hit + assert len(reconfigure_calls) == 3 # stdout, stderr, stdin + + def test_respects_existing_env_var(self, monkeypatch): + """User's explicit PYTHONIOENCODING wins over our default.""" + from hermes_cli import stdio + + monkeypatch.setattr(stdio, "is_windows", lambda: True) + monkeypatch.setenv("PYTHONIOENCODING", "latin-1") + monkeypatch.setattr(stdio, "_reconfigure_stream", lambda *a, **kw: None) + monkeypatch.setattr(stdio, "_flip_console_code_page_to_utf8", lambda: None) + + stdio.configure_windows_stdio() + assert os.environ["PYTHONIOENCODING"] == "latin-1" + + @pytest.mark.parametrize("optout", ["1", "true", "True", "yes"]) + def test_disable_flag_short_circuits(self, monkeypatch, optout): + from hermes_cli import stdio + + monkeypatch.setattr(stdio, "is_windows", lambda: True) + monkeypatch.setenv("HERMES_DISABLE_WINDOWS_UTF8", optout) + + reconfigure_hit = [] + monkeypatch.setattr( + stdio, + "_reconfigure_stream", + lambda *a, **kw: reconfigure_hit.append(True), + ) + + result = stdio.configure_windows_stdio() + assert result is False + assert reconfigure_hit == [], "opt-out must skip stream reconfiguration" + + def test_reconfigure_stream_handles_missing_method(self, monkeypatch): + """StringIO-like objects without .reconfigure() must not blow up.""" + from hermes_cli import stdio + import io + + buf = io.StringIO() + # Must not raise + stdio._reconfigure_stream(buf) + + +# --------------------------------------------------------------------------- +# terminate_pid — the centralized kill primitive +# --------------------------------------------------------------------------- + + +class TestTerminatePidRoutingOnWindows: + """``gateway.status.terminate_pid`` must use taskkill /T /F on Windows. + + On Linux we can't reload gateway/status with sys.platform=win32 because + the module unconditionally imports ``msvcrt`` in that branch. Instead + we patch the module-level ``_IS_WINDOWS`` flag and ``subprocess.run`` + on the already-loaded module, which exercises the same branching code. + """ + + def test_force_uses_taskkill_on_windows(self, monkeypatch): + from gateway import status + + captured = {} + + def fake_run(args, **kwargs): + captured["args"] = args + result = MagicMock() + result.returncode = 0 + result.stderr = "" + result.stdout = "" + return result + + monkeypatch.setattr(status, "_IS_WINDOWS", True) + monkeypatch.setattr(status.subprocess, "run", fake_run) + status.terminate_pid(12345, force=True) + + assert captured["args"][0] == "taskkill" + assert "/PID" in captured["args"] + assert "12345" in captured["args"] + assert "/T" in captured["args"] + assert "/F" in captured["args"] + + def test_force_taskkill_failure_raises_oserror(self, monkeypatch): + from gateway import status + + def fake_run(args, **kwargs): + result = MagicMock() + result.returncode = 128 + result.stderr = "ERROR: The process cannot be terminated." + result.stdout = "" + return result + + monkeypatch.setattr(status, "_IS_WINDOWS", True) + monkeypatch.setattr(status.subprocess, "run", fake_run) + with pytest.raises(OSError, match="cannot be terminated"): + status.terminate_pid(12345, force=True) + + def test_graceful_on_windows_uses_os_kill_sigterm(self, monkeypatch): + """Non-force path calls os.kill with SIGTERM (Windows has no SIGKILL). + + ``terminate_pid(pid)`` with force=False bypasses the taskkill branch + and uses ``os.kill`` directly — so platform doesn't actually matter + for the signal choice. Verifies the getattr fallback works. + """ + from gateway import status + + captured = {} + + def fake_kill(pid, sig): + captured["pid"] = pid + captured["sig"] = sig + + monkeypatch.setattr(status.os, "kill", fake_kill) + status.terminate_pid(99, force=False) + + assert captured["pid"] == 99 + assert captured["sig"] == signal.SIGTERM + + def test_taskkill_not_found_falls_back_to_os_kill(self, monkeypatch): + """On Windows without taskkill (WinPE, containers), fall back gracefully.""" + from gateway import status + + captured = {} + + def fake_run(args, **kwargs): + raise FileNotFoundError(2, "taskkill not found") + + def fake_kill(pid, sig): + captured["pid"] = pid + captured["sig"] = sig + + monkeypatch.setattr(status, "_IS_WINDOWS", True) + monkeypatch.setattr(status.subprocess, "run", fake_run) + monkeypatch.setattr(status.os, "kill", fake_kill) + status.terminate_pid(42, force=True) + + assert captured["pid"] == 42 + assert captured["sig"] == signal.SIGTERM + + +# --------------------------------------------------------------------------- +# SIGKILL fallback pattern +# --------------------------------------------------------------------------- + + +class TestSigkillFallback: + """Modules that want SIGKILL must fall back to SIGTERM when absent.""" + + def test_getattr_fallback_works_when_sigkill_missing(self, monkeypatch): + """The `getattr(signal, "SIGKILL", signal.SIGTERM)` pattern.""" + # Build a stand-in signal module with no SIGKILL attribute + fake_signal = MagicMock() + del fake_signal.SIGKILL # ensure it's absent + fake_signal.SIGTERM = 15 + + result = getattr(fake_signal, "SIGKILL", fake_signal.SIGTERM) + assert result == 15 + + def test_getattr_fallback_prefers_sigkill_when_present(self): + """On POSIX the fallback is a no-op: real SIGKILL wins.""" + result = getattr(signal, "SIGKILL", signal.SIGTERM) + assert result == signal.SIGKILL + + @pytest.mark.parametrize( + "module_path, line_pattern", + [ + ("hermes_cli.kanban_db", 'getattr(signal, "SIGKILL", signal.SIGTERM)'), + ], + ) + def test_module_uses_getattr_fallback(self, module_path, line_pattern): + """Source-level check that our modules use the safe fallback.""" + rel = module_path.replace(".", "/") + ".py" + root = Path(__file__).resolve().parents[2] + source = (root / rel).read_text(encoding="utf-8") + assert line_pattern in source, ( + f"{rel} must use the getattr fallback pattern on its SIGKILL site" + ) + + +# --------------------------------------------------------------------------- +# OSError widening on os.kill(pid, 0) probes +# --------------------------------------------------------------------------- + + +class TestProcessRegistryOSErrorWidening: + """_is_host_pid_alive must treat Windows' OSError as 'not alive'.""" + + def test_oserror_treated_as_not_alive(self, monkeypatch): + from tools.process_registry import ProcessRegistry + + def fake_kill(pid, sig): + # Simulate Windows' WinError 87 for an unknown PID + raise OSError(22, "Invalid argument") + + monkeypatch.setattr("tools.process_registry.os.kill", fake_kill) + assert ProcessRegistry._is_host_pid_alive(12345) is False + + def test_permission_error_treated_as_not_alive(self, monkeypatch): + """Conservative: PermissionError also means 'not alive' (matches existing behavior).""" + from tools.process_registry import ProcessRegistry + + def fake_kill(pid, sig): + raise PermissionError(1, "Operation not permitted") + + monkeypatch.setattr("tools.process_registry.os.kill", fake_kill) + assert ProcessRegistry._is_host_pid_alive(12345) is False + + def test_zero_or_none_pid_returns_false_without_calling_kill(self, monkeypatch): + """No wasted syscall on falsy pids.""" + from tools.process_registry import ProcessRegistry + + kill_calls = [] + monkeypatch.setattr( + "tools.process_registry.os.kill", + lambda pid, sig: kill_calls.append(pid), + ) + assert ProcessRegistry._is_host_pid_alive(None) is False + assert ProcessRegistry._is_host_pid_alive(0) is False + assert kill_calls == [] + + def test_alive_pid_returns_true(self, monkeypatch): + from tools.process_registry import ProcessRegistry + + # os.kill returning None (default) means "probe succeeded → pid alive" + monkeypatch.setattr("tools.process_registry.os.kill", lambda pid, sig: None) + assert ProcessRegistry._is_host_pid_alive(os.getpid()) is True + + +# --------------------------------------------------------------------------- +# tzdata dependency +# --------------------------------------------------------------------------- + + +class TestTzdataDependencyDeclared: + """Windows installs must pull tzdata for zoneinfo to work.""" + + def test_pyproject_declares_tzdata_for_win32(self): + root = Path(__file__).resolve().parents[2] + source = (root / "pyproject.toml").read_text(encoding="utf-8") + # The dependency line should be conditional on sys_platform == 'win32' + # and should NOT be in the core dependencies for Linux/macOS. + assert ( + 'tzdata>=2023.3; sys_platform == \'win32\'' in source + or "tzdata>=2023.3; sys_platform == 'win32'" in source + or 'tzdata>=2023.3; sys_platform == "win32"' in source + ), "tzdata must be a Windows-only dep in pyproject.toml dependencies" + + +# --------------------------------------------------------------------------- +# README / docs consistency +# --------------------------------------------------------------------------- + + +class TestReadmeNoLongerSaysWindowsUnsupported: + """The README shouldn't claim native Windows isn't supported.""" + + def test_readme_does_not_say_not_supported(self): + root = Path(__file__).resolve().parents[2] + source = (root / "README.md").read_text(encoding="utf-8") + # Previous string (removed in this PR): "Native Windows is not supported" + assert "Native Windows is not supported" not in source, ( + "README.md still says native Windows is not supported — update the " + "install copy to reflect the PowerShell installer." + ) + + def test_readme_mentions_powershell_installer(self): + root = Path(__file__).resolve().parents[2] + source = (root / "README.md").read_text(encoding="utf-8") + assert "install.ps1" in source, ( + "README.md must point at scripts/install.ps1 for Windows users" + ) + + +# --------------------------------------------------------------------------- +# pty_bridge graceful import on Windows +# --------------------------------------------------------------------------- + + +class TestWebServerPtyBridgeGuard: + """The web server must not crash if pty_bridge can't import (Windows).""" + + def test_import_guard_present_in_source(self): + root = Path(__file__).resolve().parents[2] + source = (root / "hermes_cli" / "web_server.py").read_text(encoding="utf-8") + assert "_PTY_BRIDGE_AVAILABLE" in source + assert "except ImportError" in source, ( + "web_server.py must wrap the pty_bridge import in try/except ImportError" + ) + + def test_pty_handler_checks_availability_flag(self): + """The /api/pty handler must short-circuit when the bridge is unavailable.""" + root = Path(__file__).resolve().parents[2] + source = (root / "hermes_cli" / "web_server.py").read_text(encoding="utf-8") + assert "if not _PTY_BRIDGE_AVAILABLE" in source, ( + "/api/pty handler must return a friendly error when PTY is unavailable" + ) + + +# --------------------------------------------------------------------------- +# Entry points wire configure_windows_stdio +# --------------------------------------------------------------------------- + + +class TestEntryPointsConfigureStdio: + """cli.py, hermes_cli/main.py, gateway/run.py must call configure_windows_stdio.""" + + @pytest.mark.parametrize( + "relpath", + ["cli.py", "hermes_cli/main.py", "gateway/run.py"], + ) + def test_entry_point_calls_configure_stdio(self, relpath): + root = Path(__file__).resolve().parents[2] + source = (root / relpath).read_text(encoding="utf-8") + assert "configure_windows_stdio" in source, ( + f"{relpath} must call hermes_cli.stdio.configure_windows_stdio() " + "early in startup so Windows consoles render Unicode without crashing" + ) diff --git a/tools/browser_tool.py b/tools/browser_tool.py index c8cdedcf0b..c7b16feb11 100644 --- a/tools/browser_tool.py +++ b/tools/browser_tool.py @@ -1175,6 +1175,10 @@ def _reap_orphaned_browser_sessions(): # Owner exists but we can't signal it (different uid). # Treat as alive — don't reap someone else's session. owner_alive = True + except OSError: + # Windows: gone PID raises OSError (WinError 87) instead + # of ProcessLookupError. Treat as dead to match POSIX. + owner_alive = False except (ValueError, OSError): owner_alive = None # corrupt file — fall through @@ -1211,6 +1215,11 @@ def _reap_orphaned_browser_sessions(): except PermissionError: # Alive but owned by someone else — leave it alone continue + except OSError: + # Windows raises OSError (WinError 87) for a gone PID — treat + # as dead and clean up, mirroring the ProcessLookupError branch. + shutil.rmtree(socket_dir, ignore_errors=True) + continue # Daemon is alive and its owner is dead (or legacy + untracked). Reap. try: diff --git a/tools/process_registry.py b/tools/process_registry.py index 0fc312185d..a5fd5c8e51 100644 --- a/tools/process_registry.py +++ b/tools/process_registry.py @@ -407,7 +407,11 @@ class ProcessRegistry: try: os.kill(pid, 0) return True - except (ProcessLookupError, PermissionError): + except (ProcessLookupError, PermissionError, OSError): + # OSError covers Windows' WinError 87 for a gone PID, and the + # ``WinError 5 Access denied`` case — treat both as "can't probe + # or process is gone", which matches the conservative + # "not alive" semantics callers already handle. return False def _refresh_detached_session(self, session: Optional[ProcessSession]) -> Optional[ProcessSession]: diff --git a/website/docs/developer-guide/contributing.md b/website/docs/developer-guide/contributing.md index 8cfa618ad6..f86262f21b 100644 --- a/website/docs/developer-guide/contributing.md +++ b/website/docs/developer-guide/contributing.md @@ -95,7 +95,17 @@ pytest tests/ -v ## Cross-Platform Compatibility -Hermes officially supports Linux, macOS, and WSL2. Native Windows is **not supported**, but the codebase includes some defensive coding patterns to avoid hard crashes in edge cases. Key rules: +Hermes officially supports **Linux, macOS, WSL2, and native Windows** (via PowerShell install). Native Windows uses Git Bash (from [Git for Windows](https://git-scm.com/download/win)) for shell commands. A few features require POSIX kernel primitives and are gated: the dashboard's embedded PTY terminal pane (`/chat` tab) is WSL2-only. + +When contributing code, keep these rules in mind: + +- **Don't add unguarded `signal.SIGKILL` references.** It's not defined on Windows. Either route through `gateway.status.terminate_pid(pid, force=True)` (the centralized primitive that does `taskkill /T /F` on Windows and SIGKILL on POSIX), or fall back with `getattr(signal, "SIGKILL", signal.SIGTERM)`. +- **Catch `OSError` alongside `ProcessLookupError` on `os.kill(pid, 0)` probes.** Windows raises `OSError` (WinError 87, "parameter is incorrect") for an already-gone PID instead of `ProcessLookupError`. +- **Don't force the terminal to POSIX semantics.** `os.setsid`, `os.killpg`, `os.getpgid`, `os.fork` all raise on Windows — gate them with `if sys.platform != "win32":` or `if os.name != "nt":`. +- **Open files with an explicit `encoding="utf-8"`.** The Python default on Windows is the system locale (often cp1252), which mojibakes or crashes on non-Latin text. +- **Use `pathlib.Path` / `os.path.join` — never manually concat with `/`.** This matters less for strings the OS gives us back and more for strings we construct to hand to subprocesses. + +Key patterns: ### 1. `termios` and `fcntl` are Unix-only diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 5ff5489f87..3ee5a3a326 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 title: "Installation" -description: "Install Hermes Agent on Linux, macOS, WSL2, or Android via Termux" +description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux" --- # Installation @@ -16,6 +16,20 @@ Get Hermes Agent up and running in under two minutes with the one-line installer curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` +### Windows (native, PowerShell) + +Open PowerShell and run: + +```powershell +irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex +``` + +The native Windows installer provisions `uv`, Python 3.11, Node.js 22, `ripgrep`, and `ffmpeg`, clones the repo under `%LOCALAPPDATA%\hermes\hermes-agent`, creates a virtualenv, and adds `hermes` to your **User PATH**. Restart your terminal (or open a new PowerShell window) after the install so PATH picks up. + +**Prerequisite:** Install [Git for Windows](https://git-scm.com/download/win) first. Hermes uses the bundled Git Bash to execute terminal commands — the same approach Claude Code and other coding agents take on Windows. If you install Git to a non-default location, set `HERMES_GIT_BASH_PATH` in your environment to point at `bash.exe`. + +If you prefer WSL2, the Linux installer above works inside it; both native and WSL installs can coexist without conflict (native data lives under `%LOCALAPPDATA%\hermes`, WSL data lives under `~/.hermes`). + ### Android / Termux Hermes now ships a Termux-aware installer path too: @@ -33,8 +47,17 @@ The installer detects Termux automatically and switches to a tested Android flow If you want the fully explicit path, follow the dedicated [Termux guide](./termux.md). -:::warning Windows -Native Windows is **not supported**. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run Hermes Agent from there. The install command above works inside WSL2. +:::note Windows Feature Parity + +Everything except the browser-based dashboard chat terminal runs natively on Windows: +- **CLI (`hermes chat`, `hermes setup`, `hermes gateway`, …)** — native, uses your default terminal +- **Gateway (Telegram, Discord, Slack, …)** — native, runs as a background PowerShell process +- **Cron scheduler** — native +- **Browser tool** — native (Chromium via Node.js) +- **MCP servers** — native (stdio and HTTP transports both supported) +- **Dashboard `/chat` terminal pane** — **WSL2 only** (uses a POSIX PTY; native Windows has no equivalent). The rest of the dashboard (sessions, jobs, metrics) works natively — only the embedded PTY terminal tab is gated. + +Set `HERMES_DISABLE_WINDOWS_UTF8=1` in your environment if you hit an encoding-related bug and want to fall back to the legacy cp1252 stdio path (useful for bisecting). ::: ### What the Installer Does diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md index 5aa09b1c05..e796849858 100644 --- a/website/docs/user-guide/features/web-dashboard.md +++ b/website/docs/user-guide/features/web-dashboard.md @@ -80,7 +80,7 @@ The **Chat** tab embeds the full Hermes TUI (the same interface you get from `he - Node.js (same requirement as `hermes --tui`; the TUI bundle is built on first launch) - `ptyprocess` — installed by the `pty` extra (`pip install 'hermes-agent[web,pty]'`, or `[all]` covers both) -- POSIX kernel (Linux, macOS, or WSL). Native Windows Python is not supported — use WSL. +- POSIX kernel (Linux, macOS, or WSL2). The `/chat` terminal pane specifically needs a POSIX PTY — native Windows Python has no equivalent, so on a native Windows install the rest of the dashboard (sessions, jobs, metrics, config editor) works but the `/chat` tab will show a banner telling you to use WSL2 for that feature. Close the browser tab and the PTY is reaped cleanly on the server. Re-opening spawns a fresh session. diff --git a/website/docs/user-guide/windows-wsl-quickstart.md b/website/docs/user-guide/windows-wsl-quickstart.md index e3c057d22d..59f6f4391a 100644 --- a/website/docs/user-guide/windows-wsl-quickstart.md +++ b/website/docs/user-guide/windows-wsl-quickstart.md @@ -7,7 +7,18 @@ sidebar_position: 2 # Windows (WSL2) Guide -Hermes Agent is developed and tested on **Linux** and **macOS**. Native Windows is not supported — on Windows you run Hermes inside **WSL2** (Windows Subsystem for Linux, version 2). That means there are effectively two computers in play: your Windows host, and a Linux VM managed by WSL. Most confusion comes from not being sure which one you're on at any moment. +Hermes Agent now supports **both** native Windows and WSL2. This page covers the WSL2 path; for the native PowerShell install see [Installation](../getting-started/installation.md#windows-native-powershell). + +**When to pick WSL2 over native:** +- You want to use the dashboard's embedded terminal (`/chat` tab) — that pane requires a POSIX PTY and is WSL2-only. +- You're doing POSIX-heavy development work and want your Hermes sessions to share the same filesystem / paths as your dev tools. +- You already have a WSL2 environment and don't want to maintain a second install. + +**When native is fine (or better):** +- Interactive chat, gateway (Telegram/Discord/etc.), cron scheduler, browser tool, MCP servers, and most Hermes features all run natively on Windows. +- You don't want to think about crossing the WSL↔Windows boundary every time you reference a file or open a URL. + +In WSL2 there are effectively two computers in play: your Windows host, and a Linux VM managed by WSL. Most confusion comes from not being sure which one you're on at any moment. This guide covers the parts of that split that specifically affect Hermes: installing WSL2, getting files back and forth between Windows and Linux, networking in both directions, and the pitfalls people actually hit. @@ -15,11 +26,13 @@ This guide covers the parts of that split that specifically affect Hermes: insta A Chinese-language walkthrough of the minimum install path is maintained on this same page — switch via the **language** menu (top right) and select **简体中文**. ::: -## Why WSL2 (and not "just Windows") +## Why WSL2 (vs. native Windows) -Hermes assumes a POSIX environment: `fork`, `/tmp`, UNIX sockets, signal semantics, PTY-backed terminals, shells like `bash`/`zsh`, and tools like `rg`, `git`, `ffmpeg` that behave the way they do on Linux. Rewriting that for native Windows would be a full port — WSL2 gives you a real Linux kernel in a lightweight VM instead, and Hermes inside it is essentially identical to running on Ubuntu. +The native Windows install runs in Windows directly: your Windows terminal (PowerShell, Windows Terminal, etc.), Windows filesystem paths (`C:\Users\…`), and Windows processes. Hermes uses Git Bash to run shell commands, which is how Claude Code and other agents handle Windows today — it sidesteps the POSIX-vs-Windows gap without a full rewrite. -Practical consequences of this choice: +WSL2 runs a real Linux kernel in a lightweight VM, so Hermes inside it is essentially identical to running on Ubuntu. That's valuable when you want a real POSIX environment: `fork`, `/tmp`, UNIX sockets, signal semantics, PTY-backed terminals, shells like `bash`/`zsh`, and tools like `rg`, `git`, `ffmpeg` that behave the way they do on Linux. + +Practical consequences of WSL2: - The Hermes CLI, gateway, sessions, memory, skills, and tool runtimes all live inside the Linux VM. - Windows programs (browsers, native apps, Chrome with your logged-in profile) live outside it.