mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-01 12:02:05 +00:00
feat(docs): clarify platform support
This commit is contained in:
ethernet
parent
699adc2ca5
commit
772cf847b0
11 changed files with 85 additions and 60 deletions
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
:::
|
||||
|
||||
<details>
|
||||
<summary><strong>Building from a local clone</strong></summary>
|
||||
<summary><strong>Running from a local clone</strong></summary>
|
||||
|
||||
```bash
|
||||
git clone https://github.com/NousResearch/hermes-agent.git
|
||||
cd hermes-agent
|
||||
nix build
|
||||
./result/bin/hermes setup
|
||||
nix develop
|
||||
hermes setup
|
||||
```
|
||||
|
||||
</details>
|
||||
|
|
|
|||
50
website/docs/getting-started/platform-support.md
Normal file
50
website/docs/getting-started/platform-support.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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. |
|
||||
|
||||
|
|
|
|||
|
|
@ -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/`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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. |
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue