From 772cf847b0cf0913edbf84a53bfc08fcfc1c6347 Mon Sep 17 00:00:00 2001 From: ethernet Date: Fri, 26 Jun 2026 14:05:15 -0400 Subject: [PATCH] feat(docs): clarify platform support --- website/docs/developer-guide/contributing.md | 2 +- website/docs/getting-started/installation.md | 14 ++++-- website/docs/getting-started/nix-setup.md | 35 ++++++------- .../docs/getting-started/platform-support.md | 50 +++++++++++++++++++ website/docs/getting-started/termux.md | 2 +- website/docs/index.mdx | 4 +- website/docs/reference/cli-commands.md | 2 +- website/docs/reference/faq.md | 31 +----------- website/docs/reference/tools-reference.md | 2 +- website/docs/reference/toolsets-reference.md | 2 +- website/sidebars.ts | 1 + 11 files changed, 85 insertions(+), 60 deletions(-) create mode 100644 website/docs/getting-started/platform-support.md diff --git a/website/docs/developer-guide/contributing.md b/website/docs/developer-guide/contributing.md index 8d0ec52d725..d290fb20846 100644 --- a/website/docs/developer-guide/contributing.md +++ b/website/docs/developer-guide/contributing.md @@ -132,7 +132,7 @@ scripts/run_tests.sh ## 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. If you're doing Windows-heavy dev, run the Windows-footgun lint (`scripts/check-windows-footguns.py`) before pushing. +See **[Platform Support](../getting-started/platform-support.md)**. 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) needs a POSIX PTY (Linux, macOS, or WSL2). If you're doing Windows-heavy dev, run the Windows-footgun lint (`scripts/check-windows-footguns.py`) before pushing. 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 fbfee0c10db..9cece1c20c2 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -8,6 +8,11 @@ description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or And Get Hermes Agent up and running in under two minutes! +:::tip Platform Support +For the full platform support matrix (which OSes, distribution methods, and +platform-gated features are supported), see **[Platform Support](./platform-support.md)**. +::: + ## Quick Install ### With the Hermes Desktop installer on macOS or Windows (recommended) To easily install the command-line and desktop applications, [download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/) from our website and run it. @@ -40,11 +45,10 @@ The installer handles everything automatically — all dependencies (Python, Nod Where the installer puts things depends on whether you're installing as a normal user or as root: -| Installer | Code lives at | `hermes` binary | Data directory | -|---|---|---|---| -| pip install | Python site-packages | `~/.local/bin/hermes` (console_scripts) | `~/.hermes/` | -| Per-user (git installer) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` | -| Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes` | `/root/.hermes/` (or `$HERMES_HOME`) | +| Installer | Code lives at | `hermes` binary | Data directory | +| -------------------------------------- | ------------------------------ | --------------------------------------- | ------------------------------------ | +| Per-user (git installer) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` | +| Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes` | `/root/.hermes/` (or `$HERMES_HOME`) | The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`. diff --git a/website/docs/getting-started/nix-setup.md b/website/docs/getting-started/nix-setup.md index b89fa9c05da..fc4b44a2ed6 100644 --- a/website/docs/getting-started/nix-setup.md +++ b/website/docs/getting-started/nix-setup.md @@ -10,7 +10,7 @@ description: "Install and deploy Hermes Agent with Nix — from quick `nix run` Nix and NixOS are **no longer an explicitly supported install path** for Hermes Agent. The flake and NixOS module documented here may lag behind `main` and are maintained on a best-effort basis. For a supported setup, use the standard [installation](./installation.md) path (`curl | bash` installer, Docker, or Windows). This page is kept for users already running on Nix. ::: -Hermes Agent ships a Nix flake with three levels of integration: +Hermes Agent ships a Nix flake, but it's a [Tier 2 platform](./platform-support.md#tier-2) and can break at any time. | Level | Who it's for | What you get | |-------|-------------|--------------| @@ -38,42 +38,39 @@ The `curl | bash` installer manages Python, Node, and dependencies itself. The N No clone needed. Nix fetches, builds, and runs everything: ```bash -# Run directly (builds on first use, cached after) -nix run github:NousResearch/hermes-agent -- setup -nix run github:NousResearch/hermes-agent -- chat +# Run the desktop app +nix run github:NousResearch/hermes-agent#desktop # Or install persistently +nix profile install github:NousResearch/hermes-agent#desktop + +# run the tui +nix run github:NousResearch/hermes-agent -- setup +nix run github:NousResearch/hermes-agent -- --tui + +# or install it in your profile nix profile install github:NousResearch/hermes-agent hermes setup -hermes chat +hermes --tui ``` After `nix profile install`, `hermes`, `hermes-agent`, and `hermes-acp` are on your PATH. From here, the workflow is identical to the [standard installation](./installation.md) — `hermes setup` walks you through provider selection, `hermes gateway install` sets up a launchd (macOS) or systemd user service, and config lives in `~/.hermes/`. :::warning Messaging platforms (Discord, Telegram, Slack) -The default package doesn't include messaging platform libraries — they were moved to on-demand installation, which can't work in Nix's read-only environment. If you plan to connect the agent to Discord, Telegram, or Slack, install the `messaging` variant: +The default package includes ALL libraries hermes-agent might need. if you want a smaller variant, check the other flake outputs. -```bash -nix profile install github:NousResearch/hermes-agent#messaging -``` +The `default` package adds ~700 MB to the closure. If you only need messaging platforms, `#messaging` adds just ~33 MB. -For all optional extras (voice, all providers, all platforms): - -```bash -nix profile install github:NousResearch/hermes-agent#full -``` - -The `full` variant adds ~700 MB to the closure. If you only need messaging platforms, `#messaging` adds just ~33 MB. :::
-Building from a local clone +Running from a local clone ```bash git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent -nix build -./result/bin/hermes setup +nix develop +hermes setup ```
diff --git a/website/docs/getting-started/platform-support.md b/website/docs/getting-started/platform-support.md new file mode 100644 index 00000000000..d0df354e592 --- /dev/null +++ b/website/docs/getting-started/platform-support.md @@ -0,0 +1,50 @@ +--- +sidebar_position: 2.5 +title: "Platform Support" +description: "Which operating systems, distribution methods, and features Hermes Agent supports." +--- + +# Platform Support + +Hermes Agent maintains support for many platforms and distribution methods, but we can't support every possible install method. + +--- + +## Tier 1 + +We strive to never break installations and updates for these. Issues & regressions in Tier 1 are our first priority and take precedence over other platforms. + +| OS / Architecture | Installation methods | Notes | +| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **macOS** (Apple Silicon) | [Hermes Desktop](https://hermes-agent.nousresearch.com/), [`install.sh`](./installation.md#linux--macos--wsl2--android-termux) | +| [**Windows 10 / 11**](../user-guide/windows-native.md) (x86_64, aarch64) | [Hermes Desktop](https://hermes-agent.nousresearch.com/), [`install.ps1`](./installation.md#windows-native) | A few features are [not available](../user-guide/windows-native.md#feature-matrix). | +| **Linux / [WSL2](../user-guide/windows-wsl-quickstart.md)** (x86_64, aarch64) | [`install.sh`](./installation.md#linux--macos--wsl2--android-termux) | We test on the latest Ubuntu and WSL2. If your distro has glibc, systemd, and follows the Filesystem Hierarchy Standard, it's likely to work pretty well. | +| [**Docker Container**](../user-guide/docker.md#quick-start) (x86_64, aarch64) | [`docker pull`](../user-guide/docker.md#quick-start) | Docker installs do not support `hermes update`. Updating is done by running a new image. | + +--- + +## Tier 2 + +These platforms are maintained in-tree only as a best effort. +Releases may break them, and we can't promise we'll fix them promptly when they break. + +PRs will be accepted to fix issues with them, but they will take precedence below fixing issues with Tier 1 platforms. + +| OS / Architecture | Installation methods | Notes | +| ------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| **Android (Termux)** (aarch64) | [`install.sh`](./installation.md#linux--macos--wsl2--android-termux) | A few features are [not available](./termux.md#known-limitations-on-phones). | +| **Nix** (MacOS, Linux, NixOS) | [`install.sh`](./nix-setup.md) | Breaks often due to node.js packaging woes. Best of luck~! <3 | + +## Unsupported + +These platforms and distribution methods are **not** supported. +We suggest that you migrate to a supported distribution method or platform. +They may be broken right now, they may break more in the future. +PRs to fix them will _not_ be accepted, and any code that keeps compatibility with them may be removed at any point. + +- installs via the AUR (we might upstream patches if it helps out <3) +- macOS on x86 (Intel) processors +- installs via `pypi` (e.g. `uv tool install hermes-agent`, `pip install hermse-agent`, etc.) +- installs via `brew` (`brew install hermes-agent`) + +If you are using an unsupported distribution method, please read the [the installation guide](./installation.md) to learn how to switch to a supported one. diff --git a/website/docs/getting-started/termux.md b/website/docs/getting-started/termux.md index 80aae287ae9..84e43874e8e 100644 --- a/website/docs/getting-started/termux.md +++ b/website/docs/getting-started/termux.md @@ -6,7 +6,7 @@ description: "Run Hermes Agent directly on an Android phone with Termux" # Hermes on Android with Termux -This is the tested path for running Hermes Agent directly on an Android phone through [Termux](https://termux.dev/). +Hermes Agent can run directly on an Android phone through [Termux](https://termux.dev/), but it's a [Tier 2 platform](./platform-support.md#tier-2) and can break at any time. It gives you a working local CLI on the phone, plus the core extras that are currently known to install cleanly on Android. diff --git a/website/docs/index.mdx b/website/docs/index.mdx index ea4499f91e6..f7a943cba9f 100644 --- a/website/docs/index.mdx +++ b/website/docs/index.mdx @@ -85,7 +85,7 @@ Run in powershell: iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` -See the full **[Installation Guide](/getting-started/installation)** for what the installer does, the per-user vs root layout, and Windows-specific notes. +See the full **[Installation Guide](/getting-started/installation)** for what the installer does, the per-user vs root layout, and Windows-specific notes. For the complete platform support matrix, see **[Platform Support](/getting-started/platform-support)**. :::tip Fastest path to a working agent After installing, run `hermes setup --portal` — one OAuth covers a model plus all four Tool Gateway tools (web search, image generation, TTS, browser). See [Nous Portal](/integrations/nous-portal). @@ -99,7 +99,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl | | | | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | -| 🚀 **[Installation](/getting-started/installation)** | Install in 60 seconds on Linux, macOS, WSL2, or native Windows | +| 🚀 **[Installation](/getting-started/installation)** | Install in 60 seconds on Linux, macOS, WSL2, native Windows, or Android | | 📖 **[Quickstart Tutorial](/getting-started/quickstart)** | Your first conversation and key features to try | | 🗺️ **[Learning Path](/getting-started/learning-path)** | Find the right docs for your experience level | | ⚙️ **[Configuration](/user-guide/configuration)** | Config file, providers, models, and options | diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 908f077e20c..9224844076e 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -1283,7 +1283,7 @@ Subcommands: | Subcommand | Description | |------------|-------------| -| `install` | Run the upstream cua-driver installer (macOS only). | +| `install` | Run the upstream cua-driver installer (macOS, Windows, and Linux). | | `install --upgrade` | Re-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade. | | `status` | Print whether `cua-driver` is on `$PATH` and which version is installed. | diff --git a/website/docs/reference/faq.md b/website/docs/reference/faq.md index 5c4531719cd..bddaf8b2ad4 100644 --- a/website/docs/reference/faq.md +++ b/website/docs/reference/faq.md @@ -28,21 +28,8 @@ Hermes Agent works with any OpenAI-compatible API. Supported providers include: Set your provider with `hermes model` or by editing `~/.hermes/.env`. See the [Environment Variables](./environment-variables.md) reference for all provider keys. -### Does it work on Windows? - -**Yes, natively.** Hermes supports native Windows via the PowerShell installer — no WSL required. Run in PowerShell: - -```powershell -iex (irm https://hermes-agent.nousresearch.com/install.ps1) -``` - -The installer provisions a PortableGit that backs the terminal tool's shell. See the [Windows (Native) Guide](../user-guide/windows-native.md) for details. - -WSL2 remains a fully supported alternative. To run Hermes inside WSL2, install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and use the standard install command: - -```bash -curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -``` +### Does it work on Windows/Android/Termux/my plataform?? +See **[Platform Support](../getting-started/platform-support.md)** for the full platform availability matrix. ### I run Hermes in WSL2. What's the best way to control my normal Windows Chrome? @@ -62,20 +49,6 @@ See: - [Use MCP with Hermes](../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome) - [Browser Automation](../user-guide/features/browser.md#wsl2--windows-chrome-prefer-mcp-over-browser-connect) -### Does it work on Android / Termux? - -Yes — Hermes now has a tested Termux install path for Android phones. - -Quick install: - -```bash -curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -``` - -For the fully explicit manual steps, supported extras, and current limitations, see the [Termux guide](../getting-started/termux.md). - -Important caveat: the full `.[all]` extra is not currently available on Android because the `voice` extra depends on `faster-whisper` → `ctranslate2`, and `ctranslate2` does not publish Android wheels. Use the tested `.[termux]` extra instead. - ### Is my data sent anywhere? API calls go **only to the LLM provider you configure** (e.g., OpenRouter, your local Ollama instance). Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`. diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md index 26e472fb39e..3572058586b 100644 --- a/website/docs/reference/tools-reference.md +++ b/website/docs/reference/tools-reference.md @@ -103,7 +103,7 @@ Scoped to the Feishu document-comment handler. Drives comment read/write operati | Tool | Description | Requires environment | |------|-------------|----------------------| -| `computer_use` | Background macOS desktop control via cua-driver — screenshots (SOM / vision / AX), click / drag / scroll / type / key / wait, list_apps, focus_app. Does NOT steal the user's cursor or keyboard focus. Works with any tool-capable model. macOS only. | `cua-driver` on `$PATH` (install via `hermes tools`). | +| `computer_use` | Background desktop control via cua-driver — screenshots (SOM / vision / AX), click / drag / scroll / type / key / wait, list_apps, focus_app. Does NOT steal the user's cursor or keyboard focus. Works with any tool-capable model. macOS, Windows, and Linux. | `cua-driver` on `$PATH` (install via `hermes tools`). | :::note diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md index 5f11de3511e..68fa525f0a1 100644 --- a/website/docs/reference/toolsets-reference.md +++ b/website/docs/reference/toolsets-reference.md @@ -64,7 +64,7 @@ Or in-session: | `feishu_drive` | `feishu_drive_add_comment`, `feishu_drive_list_comments`, `feishu_drive_list_comment_replies`, `feishu_drive_reply_comment` | Feishu/Lark drive comment operations. Scoped to the comment agent; not exposed on `hermes-cli` or other messaging toolsets. | | `file` | `patch`, `read_file`, `search_files`, `write_file` | File reading, writing, searching, and editing. | | `homeassistant` | `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services` | Smart home control via Home Assistant. Only available when `HASS_TOKEN` is set. | -| `computer_use` | `computer_use` | Background macOS desktop control via cua-driver — does not steal cursor/focus. Works with any tool-capable model. macOS only; requires `cua-driver` on `$PATH`. | +| `computer_use` | `computer_use` | Background desktop control via cua-driver — does not steal cursor/focus. Works with any tool-capable model. macOS, Windows, and Linux; requires `cua-driver` on `$PATH`. | | `context_engine` | (varies) | Runtime tools exposed by the active context-engine plugin (empty until a plugin populates it). | | `image_gen` | `image_generate` | Text-to-image generation via FAL.ai (with opt-in OpenAI / xAI backends). | | `video_gen` | `video_generate` | Text-to-video and image-to-video via plugin-registered backends (xAI Grok-Imagine, FAL.ai Veo 3.1 / Pixverse v6 / Kling O3). Pass `image_url` to animate an image; omit it for text-to-video. | diff --git a/website/sidebars.ts b/website/sidebars.ts index 2dbf96e2ed3..025afed7dc2 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -10,6 +10,7 @@ const sidebars: SidebarsConfig = { items: [ 'getting-started/quickstart', 'getting-started/installation', + 'getting-started/platform-support', 'getting-started/termux', 'getting-started/nix-setup', 'getting-started/updating',