{"repo":"NousResearch/hermes-agent","public_id":"4222","display_label":"Signal-cli installation docs updates and fixes","summary":"These items address corrections and updates to Signal-cli installation instructions, including a snap-based install guide and fixes to inaccurate documentation. A broader docs salvage PR is also included covering related setup and configuration guides.","subsystem":"docs","counts":{"members":3,"open_issues":0,"open_issues_distinct":0,"open_prs":0,"closed_issues":1,"merged_prs":1,"attempt_prs":1},"landed_fix":{"status":"merged_to_main","basis":"structural","pr":5727,"merged_at":"2026-04-07T04:26:04+00:00"},"resolution":{"state":"unresolved","by":null},"freshness":{"state":"stale","last_verified_at":"2026-04-07T04:26:04+00:00","is_stale":true},"grouping":{"backbone":"STRUCTURAL_SPANNING","link_density":0.6666666666666666},"fix_edges":[{"issue_number":4222,"pr_number":5727,"tier":"verified","basis":"superseded_ref","confidence":0.9,"recoverable_from_timeline":false,"pr_merged_at":"2026-04-07T04:26:04+00:00"}],"members":[{"kind":"issue","number":4222,"title":"[Docs] Signal docs instructions wrong","url":null,"state":"closed"},{"kind":"pr","number":4225,"title":"docs: Update signal-cli installation instructions to use snap","url":null,"state":"closed","close_reason":{"refs":[{"kind":"pr","value":"#5727","number":5727}],"category":"superseded_by_pr","implication":"superseded"},"merged":false},{"kind":"pr","number":5727,"title":"docs: salvage 4 docs PRs — docker setup, post-update validation, local LLM guide, signal-cli install","url":null,"state":"merged","close_reason":{"category":"merged"},"merged":true,"is_fix_pr":true,"fix_tier":"verified","files_changed":["hermes_cli/gateway.py","website/docs/getting-started/updating.md","website/docs/guides/local-llm-on-mac.md","website/docs/user-guide/docker.md","website/docs/user-guide/messaging/signal.md"],"fix_hunks":[{"file":"hermes_cli/gateway.py","hunks":["@@ -1803,8 +1803,7 @@ def _setup_signal():\n         print_warning(\"signal-cli not found on PATH.\")\n         print_info(\"  Signal requires signal-cli running as an HTTP daemon.\")\n         print_info(\"  Install options:\")\n-        print_info(\"    Linux:  sudo apt install signal-cli\")\n-        print_info(\"            or download from https://github.com/AsamK/signal-cli\")\n+        print_info(\"    Linux:  download from https://github.com/AsamK/signal-cli/releases\")\n         print_info(\"    macOS:  brew install signal-cli\")\n         print_info(\"    Docker: bbernhard/signal-cli-rest-api\")\n         print()"]},{"file":"website/docs/getting-started/updating.md","hunks":["@@ -45,6 +45,20 @@ Already up to date.  (or: Updating abc1234..def5678)\n ✅ Hermes Agent updated successfully!\n ```\n \n+### Recommended Post-Update Validation\n+\n+`hermes update` handles the main update path, but a quick validation confirms everything landed cleanly:\n+\n+1. `git status --short` — if the tree is unexpectedly dirty, inspect before continuing\n+2. `hermes doctor` — checks config, dependencies, and service health\n+3. `hermes --version` — confirm the version bumped as expected\n+4. If you use the gateway: `hermes gateway status`\n+5. If `doctor` reports npm audit issues: run `npm audit fix` in the flagged directory\n+\n+:::warning Dirty working tree after update\n+If `git status --short` shows unexpected changes after `hermes update`, stop and inspect them before continuing. This usually means local modifications were reapplied on top of the updated code, or a dependency step refreshed lockfiles.\n+:::\n+\n ### Checking your current version\n \n ```bash"]},{"file":"website/docs/guides/local-llm-on-mac.md","hunks":["@@ -0,0 +1,219 @@\n+---\n+sidebar_position: 8\n+title: \"Run Local LLMs on Mac\"\n+description: \"Set up a local OpenAI-compatible LLM server on macOS with llama.cpp or MLX, including model selection, memory optimization, and real benchmarks on Apple Silicon\"\n+---\n+\n+# Run Local LLMs on Mac\n+\n+This guide walks you through running a local LLM server on macOS with an OpenAI-compatible API. You get full privacy, zero API costs, and surprisingly good performance on Apple Silicon.\n+\n+We cover two backends:\n+\n+| Backend | Install | Best at | Format |\n+|---------|---------|---------|--------|\n+| **llama.cpp** | `brew install llama.cpp` | Fastest time-to-first-token, quantized KV cache for low memory | GGUF |\n+| **omlx** | [omlx.ai](https://omlx.ai) | Fastest token generation, native Metal optimization | MLX (safetensors) |\n+\n+Both expose an OpenAI-compatible `/v1/chat/completions` endpoint. Hermes works with either one — just point it at `http://localhost:8080` or `http://localhost:8000`.\n+\n+:::info Apple Silicon only\n+This guide targets Macs with Apple Silicon (M1 and later). Intel Macs will work with llama.cpp but without GPU acceleration — expect significantly slower performance.\n+:::\n+\n+---\n+\n+## Choosing a model\n+\n+For getting started, we recommend **Qwen3.5-9B** — it's a strong reasoning model that fits comfortably in 8GB+ of unified memory with quantization.\n+\n+| Variant | Size on disk | RAM needed (128K context) | Backend |\n+|---------|-------------|---------------------------|---------|\n+| Qwen3.5-9B-Q4_K_M (GGUF) | 5.3 GB | ~10 GB with quantized KV cache | llama.cpp |\n+| Qwen3.5-9B-mlx-lm-mxfp4 (MLX) | ~5 GB | ~12 GB | omlx |\n+\n+**Memory rule of thumb:** model size + KV cache. A 9B Q4 model is ~5 GB. The KV cache at 128K context with Q4 quantization adds ~4-5 GB. With default (f16) KV cache, that balloons to ~16 GB. The quantized KV cache flags in llama.cpp are the key trick for memory-constrained systems.\n+\n+For larger models (27B, 35B), you'll need 32 GB+ of unified memory. The 9B is the sweet spot for 8-16 GB machines.\n+\n+---\n+\n+## Option A: llama.cpp\n+\n+llama.cpp is the most portable local LLM runtime. On macOS it uses Metal for GPU acceleration out of the box.\n+\n+### Install\n+\n+```bash\n+brew install llama.cpp\n+```\n+\n+This gives you the `llama-server` command globally.\n+\n+### Download the model\n+\n+You need a GGUF-format model. The easiest source is Hugging Face via the `huggingface-cli`:\n+\n+```bash\n+brew install huggingface-cli\n+```\n+\n+Then download:\n+\n+```bash\n+huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models\n+```\n+\n+:::tip Gated models\n+Some models on Hugging Face require authentication. Run `huggingface-cli login` first if you get a 401 or 404 error.\n+:::\n+\n+### Start the server\n+\n+```bash\n+llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \\\n+  -ngl 99 \\\n+  -c 131072 \\\n+  -np 1 \\\n+  -fa on \\\n+  --cache-type-k q4_0 \\\n+  --cache-type-v q4_0 \\\n+  --host 0.0.0.0\n+```\n+\n+Here's what each flag does:\n+\n+| Flag | Purpose |\n+|------|---------|\n+| `-ngl 99` | Offload all layers to GPU (Metal). Use a high number to ensure nothing stays on CPU. |\n+| `-c 131072` | Context window size (128K tokens). Reduce this if you're low on memory. |\n+| `-np 1` | Number of parallel slots. Keep at 1 for single-user use — more slots split your memory budget. |\n+| `-fa on` | Flash attention. Reduces memory usage and speeds up long-context inference. |\n+| `--cache-type-k q4_0` | Quantize the key cache to 4-bit. **This is the big memory saver.** |\n+| `--cache-type-v q4_0` | Quantize the value cache to 4-bit. Together with the above, this cuts KV cache memory by ~75% vs f16. |\n+| `--host 0.0.0.0` | Listen on all interfaces. Use `127.0.0.1` if you don't need network access. |\n+\n+The server is ready when you see:\n+\n+```\n+main: server is listening on http://0.0.0.0:8080\n+srv  update_slots: all slots are idle\n+```\n+\n+### Memory optimization for constrained systems\n+\n+The `--cache-type-k q4_0 --cache-type-v q4_0` flags are the most important optimization for systems with limited memory. Here's the impact at 128K context:\n+\n+| KV cache type | KV cache memory (128K ctx, 9B model) |\n+|---------------|--------------------------------------|\n+| f16 (default) | ~16 GB |\n+| q8_0 | ~8 GB |\n+| **q4_0** | **~4 GB** |\n+\n+On an 8 GB Mac, use `q4_0` KV cache and reduce context to `-c 32768` (32K). On 16 GB, you can comfortably do 128K context. On 32 GB+, you can run larger models or multiple parallel slots.\n+\n+If you're still running out of memory, reduce context size first (`-c`), then try a smaller quantization (Q3_K_M instead of Q4_K_M).\n+\n+### Test it\n+\n+```bash\n+curl -s http://localhost:8080/v1/chat/completions \\\n+  -H \"Content-Type: application/json\" \\\n+  -d '{\n+    \"model\": \"Qwen3.5-9B-Q4_K_M.gguf\",\n+    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n+    \"max_tokens\": 50\n+  }' | jq .choices[0].message.content\n+```\n+\n+### Get the model name\n+\n+If you forget the model name, query the models endpoint:\n+\n+```bash\n+curl -s http://localhost:8080/v1/models | jq '.data[].id'\n+```\n+\n+---\n+\n+## Option B: MLX via omlx\n+\n+[omlx](https://omlx.ai) is a macOS-native app that manages and serves MLX models. MLX is Apple's own machine learning framework, optimized specifically for Apple Silicon's unified memory architecture.\n+\n+### Install\n+\n+Download and install from [omlx.ai](https://omlx.ai). It provides a GUI for model management and a built-in server.\n+\n+### Download the model\n+\n+Use the omlx app to browse and download models. Search for `Qwen3.5-9B-mlx-lm-mxfp4` and download it. Models are stored locally (typically in `~/.omlx/models/`).\n+\n+### Start the server\n+\n+omlx serves models on `http://127.0.0.1:8000` by default. Start serving from the app UI, or use the CLI if available.\n+\n+### Test it\n+\n+```bash\n+curl -s http://127.0.0.1:8000/v1/chat/completions \\\n+  -H \"Content-Type: application/json\" \\\n+  -d '{\n+    \"model\": \"Qwen3.5-9B-mlx-lm-mxfp4\",\n+    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n+    \"max_tokens\": 50\n+  }' | jq .choices[0].message.content\n+```\n+\n+### List available models\n+\n+omlx can serve multiple models simultaneously:\n+\n+```bash\n+curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'\n+```\n+\n+---\n+\n+## Benchmarks: llama.cpp vs MLX\n+\n+Both backends tested on the same machine (Apple M5 Max, 128 GB unified memory) running the same model (Qwen3.5-9B) at comparable quantization levels (Q4_K_M for GGUF, mxfp4 for MLX). Five diverse prompts, three runs each, backends tested sequentially to avoid resource contention.\n+\n+### Results\n+\n+| Metric | llama.cpp (Q4_K_M) | MLX (mxfp4) | Winner |\n+|--------|-------------------|-------------|--------|\n+| **TTFT (avg)** | **67 ms** | 289 ms | llama.cpp (4.3x faster) |\n+| **TTFT (p50)** | **66 ms** | 286 ms | llama.cpp (4.3x faster) |\n+| **Generation (avg)** | 70 tok/s | **96 tok/s** | MLX (37% faster) |\n+| **Generation (p50)** | 70 tok/s | **96 tok/s** | MLX (37% faster) |\n+| **Total time (512 tokens)** | 7.3s | **5.5s** | MLX (25% faster) |\n+\n+### What this means\n+\n+- **llama.cpp** excels at prompt processing — its flash attention + quantized KV cache pipeline gets you the first token in ~66ms. If you're building interactive applications where perceived responsiveness matters (chatbots, autocomplete), this is a meaningful advantage.\n+\n+- **MLX** generates tokens ~37% faster once it gets going. For batch workloads, long-form generation, or any task where total completion time matters more than initial latency, MLX finishes sooner.\n+\n+- Both backends are **extremely consistent** — variance across runs was negligible. You can rely on these numbers.\n+\n+### Which one should you pick?\n+\n+| Use case | Recommendation |\n+|----------|---------------|\n+| Interactive chat, low-latency tools | llama.cpp |\n+| Long-form generation, bulk processing | MLX (omlx) |\n+| Memory-constrained (8-16 GB) | llama.cpp (quantized KV cache is unmatched) |\n+| Serving multiple models simultaneously | omlx (built-in multi-model support) |\n+| Maximum compatibility (Linux too) | llama.cpp |\n+\n+---\n+\n+## Connect to Hermes\n+\n+Once your local server is running:\n+\n+```bash\n+hermes model\n+```\n+\n+Select **Custom endpoint** and follow the prompts. It will ask for the base URL and model name — use the values from whichever backend you set up above."]},{"file":"website/docs/user-guide/docker.md","hunks":["@@ -21,7 +21,7 @@ If this is your first time running Hermes Agent, create a data directory on the\n mkdir -p ~/.hermes\n docker run -it --rm \\\n   -v ~/.hermes:/opt/data \\\n-  nousresearch/hermes-agent\n+  nousresearch/hermes-agent setup\n ```\n \n This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point."]},{"file":"website/docs/user-guide/messaging/signal.md","hunks":["@@ -25,17 +25,21 @@ The Signal adapter uses `httpx` (already a core Hermes dependency) for all commu\n ### Installing signal-cli\n \n ```bash\n-# Linux (Debian/Ubuntu)\n-sudo apt install signal-cli\n-\n # macOS\n brew install signal-cli\n \n-# Manual install (any platform)\n-# Download from https://github.com/AsamK/signal-cli/releases\n-# Extract and add to PATH\n+# Linux (download latest release)\n+VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \\\n+  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\\/v//')\n+curl -L -O \"https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz\"\n+sudo tar xf \"signal-cli-${VERSION}.tar.gz\" -C /opt\n+sudo ln -sf \"/opt/signal-cli-${VERSION}/bin/signal-cli\" /usr/local/bin/\n ```\n \n+:::caution\n+signal-cli is **not** in apt or snap repositories. The Linux install above downloads directly from [GitHub releases](https://github.com/AsamK/signal-cli/releases).\n+:::\n+\n ---\n \n ## Step 1: Link Your Signal Account\n"]}]}],"trust":{"default_tier":"verified","includes_suggested":false}}