better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/web-search-provider-plugin.md

@@ -0,0 +1,260 @@
+---
+sidebar_position: 12
+title: "Web Search Provider Plugins"
+description: "How to build a web-search/extract/crawl backend plugin for Hermes Agent"
+---
+
+# Building a Web Search Provider Plugin
+
+Web-search provider plugins register a backend that services `web_search`, `web_extract`, and (optionally) deep-crawl tool calls. Built-in providers — Firecrawl, SearXNG, Tavily, Perplexity, Exa, Parallel, Keenable, Brave Search (free tier), xAI, and DDGS — all ship as plugins under `plugins/web/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
+
+:::tip
+Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin), [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin), [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
+:::
+
+## How discovery works
+
+Hermes scans for web-search backends in three places:
+
+1. **Bundled** — `<repo>/plugins/web/<name>/` (auto-loaded with `kind: backend`, always available)
+2. **User** — `~/.hermes/plugins/web/<name>/` (opt-in via `plugins.enabled` or `hermes plugins enable <name>`)
+3. **Pip** — packages declaring a `hermes_agent.plugins` entry point
+
+Each plugin's `register(ctx)` function calls `ctx.register_web_search_provider(...)` — that puts the instance into the registry in `agent/web_search_registry.py`. The active provider for each capability is picked by config:
+
+| Capability | Config key | Falls back to |
+|---|---|---|
+| `web_search` | `web.search_backend` | `web.backend` |
+| `web_extract` | `web.extract_backend` | `web.backend` |
+| Deep crawl modes inside `web_extract` | `web.extract_backend` | `web.backend` |
+
+When neither key is set, Hermes auto-detects the backend from whichever API key/URL is present in the environment. `hermes tools` walks users through selection.
+
+## Directory structure
+
+```
+plugins/web/my-backend/
+├── __init__.py     # register() entry point
+├── provider.py     # WebSearchProvider subclass
+└── plugin.yaml     # Manifest with kind: backend and provides_web_providers
+```
+
+`brave_free/` and `ddgs/` are the smallest in-tree references — `brave_free` for an API-key-gated search-only provider, `ddgs` for a no-key provider that lazy-installs its SDK.
+
+## The WebSearchProvider ABC
+
+Subclass `agent.web_search_provider.WebSearchProvider`. The only required members are `name`, `is_available()`, and whichever of `search()` / `extract()` you implement. (Deep crawling is not a separate method — it's a mode of `extract()`.)
+
+```python
+# plugins/web/my-backend/provider.py
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List
+
+from agent.web_search_provider import WebSearchProvider
+
+
+class MyBackendWebSearchProvider(WebSearchProvider):
+    """Minimal search-only provider against the My Backend HTTP API."""
+
+    @property
+    def name(self) -> str:
+        # Stable id used in web.search_backend / web.extract_backend / web.backend
+        # config keys. Lowercase, no spaces; hyphens permitted.
+        return "my-backend"
+
+    @property
+    def display_name(self) -> str:
+        # Human label shown in `hermes tools`. Defaults to `name`.
+        return "My Backend"
+
+    def is_available(self) -> bool:
+        # Cheap check — env var present, optional dep importable, etc.
+        # MUST NOT make network calls (runs on every `hermes tools` paint).
+        return bool(os.getenv("MY_BACKEND_API_KEY", "").strip())
+
+    def supports_search(self) -> bool:
+        return True
+
+    def supports_extract(self) -> bool:
+        return False
+
+    def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
+        import httpx
+
+        api_key = os.environ["MY_BACKEND_API_KEY"]
+        try:
+            resp = httpx.get(
+                "https://api.example.com/search",
+                params={"q": query, "count": max(1, min(int(limit), 20))},
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=15,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except httpx.HTTPError as exc:
+            return {"success": False, "error": str(exc)}
+
+        # Response shape is fixed — see "Response shape" below.
+        return {
+            "success": True,
+            "data": {
+                "web": [
+                    {
+                        "title": item.get("title", ""),
+                        "url": item.get("url", ""),
+                        "description": item.get("snippet", ""),
+                        "position": idx + 1,
+                    }
+                    for idx, item in enumerate(data.get("results", []))
+                ],
+            },
+        }
+```
+
+```python
+# plugins/web/my-backend/__init__.py
+from plugins.web.my_backend.provider import MyBackendWebSearchProvider
+
+
+def register(ctx) -> None:
+    """Plugin entry point — called once at load time."""
+    ctx.register_web_search_provider(MyBackendWebSearchProvider())
+```
+
+## plugin.yaml
+
+```yaml
+name: web-my-backend
+version: 1.0.0
+description: "My Backend web search — Bearer-auth REST API"
+author: Your Name
+kind: backend
+provides_web_providers:
+  - my-backend
+requires_env:
+  - MY_BACKEND_API_KEY
+```
+
+| Key | Purpose |
+|---|---|
+| `kind: backend` | Routes the plugin through the backend-loading path |
+| `provides_web_providers` | List of provider `name`s this plugin registers — used by the loader to advertise the plugin in `hermes tools` even before `register()` runs |
+| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](/developer-guide/plugins#gate-on-environment-variables) for the rich format) |
+
+## ABC reference
+
+Full contract in `agent/web_search_provider.py`. Methods you may override:
+
+| Member | Required | Default | Purpose |
+|---|---|---|---|
+| `name` | ✅ | — | Stable id used in `web.*_backend` config |
+| `display_name` | — | `name` | Label shown in `hermes tools` |
+| `is_available()` | ✅ | — | Cheap availability gate — env vars, optional deps |
+| `supports_search()` | — | `True` | Capability flag for `web_search` routing |
+| `supports_extract()` | — | `False` | Capability flag for `web_extract` routing |
+| `search(query, limit)` | conditional | raises | Required when `supports_search()` returns `True` |
+| `extract(urls, **kwargs)` | conditional | raises | Required when `supports_extract()` returns `True` |
+
+Providers can advertise multiple capabilities from a single class — Firecrawl, Tavily, Perplexity, Keenable, Exa, and Parallel all implement both search and extract. Brave Search and DDGS are search-only; SearXNG is search-only with a documented "pair me with an extract provider" workflow.
+
+## Response shape
+
+The tool wrapper expects a fixed envelope so it doesn't have to translate between backends.
+
+**Search success:**
+
+```python
+{
+    "success": True,
+    "data": {
+        "web": [
+            {"title": str, "url": str, "description": str, "position": int},
+            ...
+        ],
+    },
+}
+```
+
+**Extract success:**
+
+```python
+{
+    "success": True,
+    "data": [
+        {
+            "url": str,
+            "title": str,
+            "content": str,
+            "raw_content": str,
+            "metadata": dict,    # optional
+            "error": str,        # optional, only on per-URL failure
+        },
+        ...
+    ],
+}
+```
+
+**Either capability, on failure:**
+
+```python
+{"success": False, "error": "human-readable message"}
+```
+
+Both `search()` and `extract()` may be `async def` — the dispatcher detects coroutine functions via `inspect.iscoroutinefunction` and awaits accordingly. Sync implementations that do blocking I/O (HTTP, SDK calls) are fine for small backends; the dispatcher handles threading.
+
+## Capability flags
+
+Hermes routes calls to the right provider based on the `supports_*` flags. A common multi-provider setup:
+
+```yaml
+# ~/.hermes/config.yaml
+web:
+  search_backend: "brave-free"     # search-only, fast, free 2k/mo
+  extract_backend: "firecrawl"     # extract + crawl, paid quota
+```
+
+When `web.search_backend` or `web.extract_backend` aren't set, both fall through to `web.backend`. When that's also unset, Hermes picks the first available provider that supports the requested capability based on env-var presence.
+
+If your provider only supports one capability, leave the other flags at their default (`False`) and the registry will skip it for that tool — users won't see misleading "provider X failed" errors when they're using X only for search and asking the agent to extract.
+
+## How Hermes wires it into the tools
+
+The `web_search` and `web_extract` tools live in `tools/web_tools.py`. At call time they:
+
+1. Read the relevant config key (`web.search_backend` for `web_search`, `web.extract_backend` for `web_extract`)
+2. Ask the registry for the provider with that `name`
+3. Check `is_available()` and the matching `supports_*()` flag
+4. Dispatch to `search()` / `extract()` (deep crawl runs as a mode inside `extract()`), awaiting if the method is a coroutine
+5. JSON-serialize the response envelope and hand it back to the LLM
+
+Errors surface as the tool result; the LLM decides how to explain them. If no provider is registered (or every available one fails the capability gate), the tool returns a helpful error pointing at `hermes tools`.
+
+## Lazy-installing optional dependencies
+
+If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](/developer-guide/plugins#lazy-install-optional-python-dependencies) for the security model.
+
+## Reference implementations
+
+- **`plugins/web/brave_free/`** — small, API-key-gated, search-only HTTP provider. Good starting template.
+- **`plugins/web/ddgs/`** — no-key provider that lazy-installs its SDK. Useful pattern for backends that wrap a Python package.
+- **`plugins/web/firecrawl/`** — full multi-capability provider (search + extract + crawl) with multiple format modes.
+- **`plugins/web/searxng/`** — self-hosted, URL-configured backend with no auth.
+- **`plugins/web/xai/`** — LLM-backed search via Grok's server-side `web_search` tool. Shows how to reuse an existing OAuth/env-var credential surface (`tools/xai_http.py`) without adding new env vars, and how to write a cheap `is_available()` that honors the no-network contract.
+
+## Distribute via pip
+
+```toml
+# pyproject.toml
+[project.entry-points."hermes_agent.plugins"]
+my-backend-web = "my_backend_web_package"
+```
+
+`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
+
+## Related pages
+
+- [Web Search](/user-guide/features/web-search) — user-facing feature documentation and per-backend configuration
+- [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
+- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/worktree-ui-dev.md

@@ -0,0 +1,168 @@
+---
+sidebar_position: 5
+title: "TUI & Desktop from Worktrees"
+description: "Run the Ink TUI and Electron desktop app from a git worktree without a full npm install per checkout"
+---
+
+# TUI & Desktop from Worktrees
+
+The Python core runs fine from any [git worktree](../user-guide/git-worktrees.md) — `cd` in and `hermes` just works. The two TypeScript surfaces do not: `ui-tui/` and `apps/desktop/` each need a populated `node_modules`, and a fresh `npm ci` per worktree is slow and duplicates gigabytes across every branch you have checked out.
+
+`htui` and `hgui` are two shell helpers that close that gap. Each launches its surface **from the current worktree** while borrowing `node_modules` from one canonical checkout — so a throwaway branch costs a symlink, not an install.
+
+They're developer conveniences, not shipped commands. Drop them in `~/.zshrc`; adapt paths to taste.
+
+## The deps-sharing model
+
+One checkout is the **deps checkout** — the one place you actually run `npm install`. Every other worktree links against it, and only re-installs locally when its lockfile diverges (a branch that bumps a dependency must not silently run against stale packages).
+
+```mermaid
+flowchart TD
+    A[htui / hgui in a worktree] --> B{package-lock.json<br/>matches deps checkout?}
+    B -- yes --> C[symlink node_modules<br/>from deps checkout]
+    B -- no --> D[local npm ci<br/>in this worktree]
+    C --> E[launch surface]
+    D --> E
+```
+
+Two env vars name the canonical checkout:
+
+| Variable | Meaning |
+|----------|---------|
+| `HERMES_MAIN_CHECKOUT` | The deps checkout — where `node_modules` really lives, and whose `.venv/bin/python` runs the backend. |
+| `HERMES_GUI_DEPS_CHECKOUT` | Where the desktop deps (`apps/desktop/node_modules`) live. Defaults to `HERMES_MAIN_CHECKOUT`; override only if you keep desktop deps elsewhere. |
+
+Neither is read by Hermes itself — they're private to these helpers. The variables Hermes *does* read are covered in [Environment Variables](../reference/environment-variables.md).
+
+## `htui` — TUI from the worktree
+
+The Ink TUI has a dev path already: `hermes --tui --dev` runs the TypeScript sources via `tsx` instead of the prebuilt bundle. `htui` is a one-liner over it that also points the run at the current worktree's `ui-tui/`:
+
+```bash
+htui() {
+  local root
+  root="$(_hermes_root)" || { echo "htui: not in a Hermes checkout" >&2; return 1; }
+  ( cd "$root" && PYTHONPATH="$root" \
+      "$HERMES_MAIN_CHECKOUT/.venv/bin/python" -m hermes_cli.main --tui --dev "$@" )
+}
+```
+
+`--dev` compiles from source, so it links `ui-tui/node_modules` from `HERMES_MAIN_CHECKOUT` when the root lockfile matches and installs locally otherwise (see [`_hermes_root` / linking helpers](#shared-helpers)).
+
+:::warning `--dev` and `HERMES_TUI_DIR` are mutually exclusive
+`HERMES_TUI_DIR` points Hermes at a *prebuilt* bundle (Nix, system packages), which has no source to hot-reload. If it's set in your shell, `hermes --tui --dev` exits with an error. Run `unset HERMES_TUI_DIR` before `htui`.
+:::
+
+## `hgui` — desktop app from the worktree
+
+The desktop app needs dependencies at both the repo root and `apps/desktop/`, a Vite server, and a Python backend. The stock `npm run dev` pins Vite to `5174`; Electron also defaults to CDP port `9222` and takes a single-instance lock on its user-data directory. Changing only the Vite port is not enough to run two desktops.
+
+This **zsh** example gives each launch an explicit slot (`HGUI_SLOT`, default `0`). Use a different slot in each terminal. It uses the [shared helpers](#shared-helpers) below and requires `lsof`:
+
+```bash
+hgui() (
+  local root deps desktop slot="${HGUI_SLOT:-0}" vite_port cdp_port port
+  [[ "$slot" == [0-9] ]] || { print -u2 'hgui: HGUI_SLOT must be 0-9'; return 1; }
+  vite_port=$((5174 + slot))
+  cdp_port=$((9222 + slot))
+  for port in "$vite_port" "$cdp_port"; do
+    if lsof -nP -t -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
+      print -u2 "hgui: port $port is busy; choose another HGUI_SLOT"
+      return 1
+    fi
+  done
+
+  root="$(_hermes_root)" || { print -u2 'hgui: not in a Hermes checkout'; return 1; }
+  deps="${HERMES_GUI_DEPS_CHECKOUT:-$HERMES_MAIN_CHECKOUT}"
+  desktop="$root/apps/desktop"
+
+  if cmp -s "$root/package-lock.json" "$deps/package-lock.json"; then
+    _hermes_link_deps "$desktop" "$deps/apps/desktop" || return 1
+    _hermes_link_deps "$root" "$deps" || return 1
+  else
+    ( cd "$root" && npm ci ) || return 1
+  fi
+
+  cd "$desktop" || return 1
+  export PATH="$desktop/node_modules/.bin:$root/node_modules/.bin:$PATH"
+  export HERMES_DESKTOP_HERMES_ROOT="$root"
+  export HERMES_DESKTOP_PYTHON="$HERMES_MAIN_CHECKOUT/.venv/bin/python"
+  export HERMES_DESKTOP_CWD="$root"
+  export HERMES_DESKTOP_DEV_SERVER="http://127.0.0.1:$vite_port"
+  export HERMES_DESKTOP_CDP_PORT="$cdp_port"
+  export HERMES_DESKTOP_USER_DATA_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/hermes-hgui/slot-$slot"
+  # A userData override would otherwise also relocate the agent's home.
+  export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+  export XCURSOR_SIZE=24
+
+  # Mirror the dev scripts, replacing their fixed ports. No repo edits needed.
+  concurrently -k -n "vite,electron" \
+    "node scripts/assert-root-install.mjs && npm run clean:renderer && vite --host 127.0.0.1 --port $vite_port --strictPort" \
+    "tsc --build tsconfig.electron.json && wait-on http://127.0.0.1:$vite_port && node scripts/bundle-electron-main.mjs --dev && electron ."
+)
+```
+
+For example, after setting `HERMES_MAIN_CHECKOUT` and sourcing the helpers:
+
+```bash
+# Terminal 1: main checkout
+cd "$HERMES_MAIN_CHECKOUT"
+HGUI_SLOT=0 hgui
+
+# Terminal 2: an existing worktree
+cd /path/to/hermes-worktree
+HGUI_SLOT=1 hgui
+```
+
+Slot `0` uses ports `5174`/`9222`; slot `1` uses `5175`/`9223`. Slots are caller-assigned, not atomically reserved: always use distinct slots for simultaneous starts. Busy ports are rejected, never evicted. Use separate checkouts for separate builds because launches in the same checkout still share build outputs.
+
+| Variable | Role in `hgui` |
+|----------|----------------|
+| `HGUI_SLOT` | Helper-only slot number, `0`–`9`; not a Hermes setting. |
+| `HERMES_DESKTOP_HERMES_ROOT` | Runs the backend from this worktree, not the packaged/PATH runtime. |
+| `HERMES_DESKTOP_PYTHON` | Reuses the main checkout's Python environment. Adjust for an installation that uses `venv` rather than `.venv`. |
+| `HERMES_DESKTOP_CWD` | Roots new desktop work in the worktree. |
+| `HERMES_DESKTOP_DEV_SERVER` | Points Electron at this instance's Vite server. |
+| `HERMES_DESKTOP_CDP_PORT` | Gives each instance its own renderer debugging port. |
+| `HERMES_DESKTOP_USER_DATA_DIR` | Separates Electron's single-instance lock, browser storage, and desktop preferences. |
+| `HERMES_HOME` | Explicitly preserves the agent home despite the Electron user-data override. |
+
+Each slot starts with fresh desktop preferences and remembers them on later launches. This example does not copy browser storage, saved navigation, or backend ownership from a running app.
+
+:::warning Separate desktops are not separate agent data
+The default `HERMES_HOME` is shared: sessions, configuration, credentials, and profiles remain the same. Avoid editing the same conversation from both instances. For destructive tests or incompatible database migrations, pass a separate temporary `HERMES_HOME` and configure that sandbox independently.
+:::
+
+Quit the app normally or press Ctrl-C in its launching terminal. `concurrently -k` manages its own child commands, and Electron owns its backend shutdown. Do not add a global `killport`, `pkill electron`, or a sweep of all `serve`/`dashboard --port 0` processes: those can terminate another instance. Remove the old `_hermes_gui_cleanup` trap if replacing an earlier version of this helper.
+
+## Shared helpers
+
+Both functions resolve the enclosing checkout and link deps the same way:
+
+```bash
+# The enclosing worktree, verified as a real Hermes checkout.
+_hermes_root() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 1
+  [[ -f "$root/hermes_cli/main.py" && -d "$root/ui-tui" ]] && print -r "$root"
+}
+
+# Symlink node_modules from the deps checkout — never over an existing tree.
+_hermes_link_deps() {
+  local target="${1%/}" source="${2%/}"
+  [[ -d "$source/node_modules" ]] || return 1
+  [[ -e "$target/node_modules" ]] || ln -s "$source/node_modules" "$target/node_modules"
+}
+```
+
+:::info Why link only when locks match
+A symlink to a divergent `node_modules` is worse than no install — the worktree would build against packages its own lockfile never declared. Byte-comparing `package-lock.json` is the cheap, exact guard: same lock ⇒ safe to borrow; different lock ⇒ `npm ci` locally. Vite realpaths symlinks before enforcing `server.fs.allow`, which is why `apps/desktop/vite.config.ts` whitelists the real `node_modules` location.
+:::
+
+## See also
+
+- [Git Worktrees](../user-guide/git-worktrees.md) — the isolation model these helpers build on
+- [TUI](../user-guide/tui.md) — `hermes --tui --dev` and the `HERMES_TUI_DIR` prebuild path
+- [Desktop App](../user-guide/desktop.md) — building from source and the backend resolution ladder
+- [`apps/desktop/README.md`](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/README.md) — dev server, sandbox script, and packaging
+- [Environment Variables](../reference/environment-variables.md) — every `HERMES_*` variable Hermes reads

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting Started",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Get up and running with Hermes Agent in minutes."
+  }
+}

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/getting-started/installation.md

@@ -0,0 +1,200 @@
+---
+sidebar_position: 2
+title: "Installation"
+description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux"
+---
+
+# Installation
+
+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.
+
+:::note
+The macOS installer is **Apple Silicon only**. macOS on x86 (Intel) processors is [not a supported platform](./platform-support.md#unsupported).
+:::
+
+### Without Hermes Desktop:
+For a command-line only install without Hermes Desktop, run:
+
+#### Linux / macOS / WSL2 / Android (Termux)
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+#### Windows (native)
+
+Run in powershell:
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1) 
+```
+
+If you want to install & run Hermes Desktop after a command-line only install, simply run
+```bash
+hermes desktop
+```
+
+### What the Installer Does
+
+The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat.
+
+#### Install Layout
+
+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                       |
+| -------------------------------------- | ------------------------------ | --------------------------------------- | ------------------------------------ |
+| 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`.
+
+### After Installation
+
+Reload your shell and start chatting:
+
+```bash
+source ~/.bashrc   # or: source ~/.zshrc
+hermes             # Start chatting!
+```
+
+To reconfigure individual settings later, use the dedicated commands:
+
+```bash
+hermes model          # Choose your LLM provider and model
+hermes tools          # Configure which tools are enabled
+hermes gateway setup  # Set up messaging platforms
+hermes config set     # Set individual config values
+hermes config get     # Inspect individual config values
+hermes setup          # Or run the full setup wizard to configure everything at once
+```
+
+:::tip Fastest path: Nous Portal
+One subscription covers 300+ models plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:
+
+```bash
+hermes setup --portal
+```
+
+That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
+:::
+
+:::tip Already running Hermes on another machine?
+You don't need to rebuild your setup from scratch. Restore a full backup with `hermes import` (see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine)), or bring over a single agent with `hermes profile import` (see [Moving a single profile to another machine](/reference/faq#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export) explains which to use.
+:::
+
+---
+
+## Prerequisites
+
+**Installer:** On non-Windows platforms, the only prerequisite is **Git**. On Linux, also make sure `curl` and `xz-utils` are available (the installer downloads Node.js as a `.tar.xz` archive). The desktop app additionally requires `g++` (or `build-essential` on Debian/Ubuntu) to compile native modules. The installer automatically handles everything else:
+
+- **uv** (fast Python package manager)
+- **Python 3.11** (via uv, no sudo needed)
+- **Node.js v26** (for browser automation and WhatsApp bridge; existing system Node 22.22+, 24.11+, or 26+ is used as-is)
+- **ripgrep** (fast file search)
+- **ffmpeg** (audio format conversion for TTS)
+
+:::info
+You do **not** need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure `git` is available (`git --version`). On Linux, ensure `curl` and `xz-utils` are installed (`sudo apt install curl xz-utils` on Debian/Ubuntu). For the desktop app, also install `build-essential` (`sudo apt install build-essential`).
+:::
+
+:::tip Nix users
+Nix is **no longer an explicitly supported install path** (best-effort only). If you already use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the **[Nix & NixOS Setup](./nix-setup.md)** guide.
+:::
+
+---
+
+## Manual / Developer Installation
+
+If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the [Development Setup](../developer-guide/contributing.md#development-setup) section in the Contributing guide.
+
+---
+
+## Non-Sudo / System Service User Installs
+
+Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service account, or any user without `sudo` access) is supported. The only thing on the install path that genuinely needs root is Playwright's `--with-deps` step, which `apt`-installs shared libraries (`libnss3`, `libxkbcommon`, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately.
+
+**Recommended split (Debian/Ubuntu):**
+
+1. **One time, as an admin user with sudo**, install the system libraries Chromium needs:
+   ```bash
+   sudo npx playwright install-deps chromium
+   ```
+   (You can run this from anywhere — `npx` will fetch Playwright on the fly.)
+
+2. **As the unprivileged service user**, run the regular installer. It will detect the missing sudo, skip `--with-deps`, and install Chromium into the user's local Playwright cache:
+   ```bash
+   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+   ```
+
+   If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass `--skip-browser`:
+   ```bash
+   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
+   ```
+
+   The installer also pre-installs [`cua-driver`](../user-guide/features/computer-use.md) so the Computer Use toolset works the moment you enable it; pass `--skip-computer-use` to opt out (it will then install on demand when you enable the tool).
+
+3. **Make `hermes` available to the service user's shells.** The installer writes the launcher to `~/.local/bin/hermes`. System service accounts often have a minimal PATH that doesn't include `~/.local/bin`. Either add it to the user's environment, or symlink the launcher into a system location:
+   ```bash
+   # Option A — add to the service user's profile
+   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+
+   # Option B — symlink system-wide (run as an admin)
+   sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes
+   ```
+
+4. **Verify:** `hermes doctor` should now run cleanly. If you get `ModuleNotFoundError: No module named 'dotenv'`, you're invoking the repo source `hermes` file (`~/.hermes/hermes-agent/hermes`) with system Python instead of the venv launcher (`~/.hermes/hermes-agent/venv/bin/hermes`) — fix step 3.
+
+5. **Running the messaging gateway from this account?** A user-level service stops at logout and does not start at boot until you enable lingering for the service user:
+
+   ```bash
+   sudo loginctl enable-linger <service-user>
+   ```
+
+   See [Messaging Gateway](/user-guide/messaging/) for the service setup itself.
+
+The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
+| `API key not set` | Run `hermes model` to configure your provider, or `hermes config set OPENROUTER_API_KEY your_key` |
+| Missing config after update | Run `hermes config check` then `hermes config migrate` |
+
+For more diagnostics, run `hermes doctor` — it will tell you exactly what's missing and how to fix it.
+
+### Symlinked home directories and external storage
+
+Hermes supports a symlinked `HERMES_HOME` and symlinked home subdirectories,
+including `hooks`, `skills`, `sessions`, and `logs`. During home initialization,
+existing directory links are preserved, and permissions on linked directories
+(and descendants such as `logs/curator`) are left to their owner.
+
+If a link target is missing, inaccessible, or not a directory, initialization
+stops with a storage error naming the path and link target. Hermes does **not**
+replace the link or create its missing target: doing so could write data onto
+the local disk while an external or NAS volume is unmounted. Check the reported
+link, restore the mount or correct its target, and verify access permissions
+before retrying. For a deliberately new dotfiles target, create it yourself only
+after confirming the intended storage is available.
+
+`hermes doctor` reports these failures as storage problems, not invalid YAML.
+Keep your existing `config.yaml`; running `hermes setup` is not the repair for an
+unavailable directory. This is a directory-availability check, not a mount monitor:
+an existing directory cannot establish that the intended volume is mounted.
+
+## Install method auto-detection
+
+Hermes auto-detects whether it was installed via the git installer, Docker, or NixOS, and `hermes update` prints the matching update command for that path. There's no env var to set — the detection is based on the install layout (`~/.hermes/hermes-agent/` checkout, Docker image stamp, or Nix store path). `hermes doctor` also surfaces the detected method under its environment summary.