mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-18 14:52:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

feat(docs): clarify platform support

Browse source
This commit is contained in:
ethernet 2026-06-26 14:05:15 -04:00
parent 699adc2ca5
commit 772cf847b0
11 changed files with 85 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

14
website/docs/getting-started/installation.md
View file

@ -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`.

35
website/docs/getting-started/nix-setup.md
View file

@ -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
View 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~! &lt;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 &lt;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.

2
website/docs/getting-started/termux.md
View file

@ -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.