From 7a4d5c123a29e60dec647977572116bad2036a13 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Fri, 8 May 2026 15:54:05 -0700 Subject: [PATCH] docs(windows): label native Windows support as early beta (#22115) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds early-beta framing to every user-facing surface where native Windows is introduced — landing page install block, Installation page, Windows (Native) guide, contributor notes, and README. Sets expectations that the path installs and runs but hasn't been road-tested as broadly as POSIX, and points users who want maximum stability at WSL2 instead. Follow-up to #21561 (native Windows support) and #22089 (Windows docs). --- README.md | 6 ++++-- website/docs/developer-guide/contributing.md | 2 +- website/docs/getting-started/installation.md | 12 ++++++++---- website/docs/index.md | 4 ++-- website/docs/user-guide/windows-native.md | 14 +++++++++----- 5 files changed, 24 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ead2e44917..8b8a078b25 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,9 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), [Open curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` -### Windows (native, PowerShell) +### Windows (native, PowerShell) — Early Beta + +> **Heads up:** Native Windows support is **early beta**. It installs and runs, but hasn't been road-tested as broadly as our Linux/macOS/WSL2 paths. Please [file issues](https://github.com/NousResearch/hermes-agent/issues) when you hit rough edges. For the most battle-tested Windows setup today, run the Linux/macOS one-liner above inside **WSL2**. Run this in PowerShell: @@ -50,7 +52,7 @@ If you already have Git installed, the installer detects it and uses that instea > **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 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). +> **Windows:** Native Windows is supported as an **early beta** — the PowerShell one-liner above installs everything, but expect rough edges and please file issues when you hit them. If you'd rather use WSL2 (our most battle-tested Windows path), 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/website/docs/developer-guide/contributing.md b/website/docs/developer-guide/contributing.md index f86262f21b..9b2cc9b303 100644 --- a/website/docs/developer-guide/contributing.md +++ b/website/docs/developer-guide/contributing.md @@ -95,7 +95,7 @@ pytest tests/ -v ## Cross-Platform Compatibility -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. +Hermes officially supports **Linux, macOS, WSL2, and native Windows (early beta — 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. The native-Windows path is new and moves fast — if you're doing Windows-heavy dev, expect to hit and fix rough edges. When contributing code, keep these rules in mind: diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 6c56a4d889..a3353cb3e1 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, native Windows, or Android via Termux" +description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows (early beta), or Android via Termux" --- # Installation @@ -16,7 +16,11 @@ 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) +### Windows (native, PowerShell) — Early Beta + +:::warning Early BETA +Native Windows support is **early beta**. It installs and works for the common paths, but hasn't been road-tested as broadly as our POSIX installers. Please [file issues](https://github.com/NousResearch/hermes-agent/issues) when you hit rough edges. For the most battle-tested setup on Windows today, use the Linux/macOS one-liner above inside **WSL2** instead. +::: Open PowerShell and run: @@ -53,9 +57,9 @@ 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). -:::note Windows Feature Parity +:::note Windows Feature Parity (Early Beta) -Everything except the browser-based dashboard chat terminal runs natively on Windows: +Native Windows is in **early beta**. 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 diff --git a/website/docs/index.md b/website/docs/index.md index a4f9878c38..86abf44403 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -24,7 +24,7 @@ The self-improving AI agent built by [Nous Research](https://nousresearch.com). curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` -**Windows (native, PowerShell)** +**Windows (native, PowerShell)** — *early beta, [details →](/docs/user-guide/windows-native)* ```powershell irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex @@ -42,7 +42,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl | | | |---|---| -| 🚀 **[Installation](/docs/getting-started/installation)** | Install in 60 seconds on Linux, macOS, WSL2, or native Windows | +| 🚀 **[Installation](/docs/getting-started/installation)** | Install in 60 seconds on Linux, macOS, WSL2, or native Windows (early beta) | | 📖 **[Quickstart Tutorial](/docs/getting-started/quickstart)** | Your first conversation and key features to try | | 🗺️ **[Learning Path](/docs/getting-started/learning-path)** | Find the right docs for your experience level | | ⚙️ **[Configuration](/docs/user-guide/configuration)** | Config file, providers, models, and options | diff --git a/website/docs/user-guide/windows-native.md b/website/docs/user-guide/windows-native.md index 5425d46acc..e117ae4f9f 100644 --- a/website/docs/user-guide/windows-native.md +++ b/website/docs/user-guide/windows-native.md @@ -1,15 +1,19 @@ --- -title: "Windows (Native) Guide" -description: "Run Hermes Agent natively on Windows 10 / 11 — install, feature matrix, UTF-8 console, Git Bash, gateway as a Scheduled Task, editor handling, PATH, uninstall, and common pitfalls" -sidebar_label: "Windows (Native)" +title: "Windows (Native) Guide — Early Beta" +description: "Early BETA: run Hermes Agent natively on Windows 10 / 11 — install, feature matrix, UTF-8 console, Git Bash, gateway as a Scheduled Task, editor handling, PATH, uninstall, and common pitfalls" +sidebar_label: "Windows (Native) — Beta" sidebar_position: 3 --- -# Windows (Native) Guide +# Windows (Native) Guide — Early Beta + +:::warning Early BETA +Native Windows support is **early beta**. It installs, runs, and passes our Windows-footgun lint, but it hasn't been road-tested at the scale our Linux/macOS/WSL2 paths have. Expect rough edges — especially around subprocess handling, path quirks, and non-ASCII console output. Please [file issues](https://github.com/NousResearch/hermes-agent/issues) with repro steps when you hit something. If you want a battle-tested setup today, use the [Linux/macOS installer under WSL2](./windows-wsl-quickstart.md) instead. +::: Hermes runs natively on Windows 10 and Windows 11 — no WSL, no Cygwin, no Docker. This page is the deep dive: what works natively, what's WSL-only, what the installer actually does, and the Windows-specific knobs you might need to touch. -If you just want to install, the one-liner on the [landing page](/) or [Installation page](../getting-started/installation#windows-native-powershell) is all you need. Come back here when something surprises you. +If you just want to install, the one-liner on the [landing page](/) or [Installation page](../getting-started/installation#windows-native-powershell--early-beta) is all you need. Come back here when something surprises you. :::tip Want WSL instead? If you prefer a real POSIX environment (for the dashboard's embedded terminal, `fork` semantics, Linux-style file watchers, etc.), see the **[Windows (WSL2) Guide](./windows-wsl-quickstart.md)**. Both coexist cleanly: native data lives under `%LOCALAPPDATA%\hermes`, WSL data lives under `~/.hermes`.