docs: harden secret-handling and service exposure guidance (#3)

Security-doc pass across setup, LightRAG, Telegram, custom models, and gateway recovery docs. Replaces shell-history-leaking secret setup examples with editor/hermes auth guidance, reinforces chmod 600 on .env files, strengthens LightRAG localhost-only warning, avoids printing full Telegram tokens, and clarifies localhost-only gateway health checks. Verified config.yaml \ expansion against Hermes config loader _expand_env_vars().

Author: OnlyTerp

README.md

@@ -367,13 +367,13 @@ hermes auth
 
 This opens an interactive menu to add API keys for each provider. Keys are stored in `~/.hermes/.env` — never committed to git.
 
-> **Tip:** You can also set keys manually:
+> **Tip:** You can also set keys manually using a text editor:
 > ```bash
-> echo "ANTHROPIC_API_KEY=<your-key-here>" >> ~/.hermes/.env
+> nano ~/.hermes/.env    # Add: ANTHROPIC_API_KEY=<your-key-here>
 > chmod 600 ~/.hermes/.env   # Restrict access to your user only
 > ```
 >
-> **Important:** Always run `chmod 600 ~/.hermes/.env` to prevent other users on the system from reading your API keys.
+> **Avoid using `echo` to append secrets** — the command (including the key) is saved in your shell history (`~/.bash_history`). Use an editor or `hermes auth` instead. Always run `chmod 600 ~/.hermes/.env` to prevent other users on the system from reading your API keys.
 
 ### 3. Configure Toolsets
 
@@ -524,6 +524,11 @@ Everything lives under `~/.hermes/`:
 
 > **Important:** `SOUL.md` is injected into every message. Keep it under 1 KB. Every byte costs latency and tokens.
 
+> **Security:** The `.env` file contains your API keys. Restrict its permissions so only you can read it:
+> ```bash
+> chmod 600 ~/.hermes/.env
+> ```
+
 ---
 
 ## Verify Your Setup
@@ -856,7 +861,7 @@ The server starts on `http://localhost:9623` with:
 - **Web UI** at `http://localhost:9623/webui` for browsing the knowledge graph
 - **Health check** at `http://localhost:9623/health`
 
-> **Security warning:** The LightRAG REST API has **no built-in authentication**. Always bind to `127.0.0.1` (localhost only) — never `0.0.0.0`. If you need remote access, put it behind a reverse proxy (nginx, Caddy) with authentication, or use SSH tunneling. Anyone who can reach this port can query, ingest, or delete your knowledge graph data.
+> **Security warning:** The LightRAG REST API has **no built-in authentication**. Always bind to `127.0.0.1` (localhost only) — never `0.0.0.0`. If you need remote access, put it behind a reverse proxy (nginx, Caddy) with authentication, or use SSH tunneling / Tailscale / WireGuard. Anyone who can reach this port can query, ingest, or delete your entire knowledge graph.
 
 ### Run as a Background Service
 
@@ -1402,7 +1407,7 @@ Each user gets their own conversation session. The bot tracks sessions per user
 
 ### Bot not responding
 
-1. Check the token is correct: `echo $TELEGRAM_BOT_TOKEN`
+1. Check the token is set (without printing it in full): `echo ${TELEGRAM_BOT_TOKEN:0:10}...`
 2. Verify the gateway is running: `hermes gateway status`
 3. Check logs: `hermes gateway logs`
 

part1-setup.md

@@ -82,13 +82,13 @@ hermes auth
 
 This opens an interactive menu to add API keys for each provider. Keys are stored in `~/.hermes/.env` — never committed to git.
 
-> **Tip:** You can also set keys manually:
+> **Tip:** You can also set keys manually using a text editor:
 > ```bash
-> echo "ANTHROPIC_API_KEY=<your-key-here>" >> ~/.hermes/.env
+> nano ~/.hermes/.env    # Add: ANTHROPIC_API_KEY=<your-key-here>
 > chmod 600 ~/.hermes/.env   # Restrict access to your user only
 > ```
 >
-> **Important:** Always run `chmod 600 ~/.hermes/.env` to prevent other users on the system from reading your API keys.
+> **Avoid using `echo` to append secrets** — the command (including the key) is saved in your shell history (`~/.bash_history`). Use an editor or `hermes auth` instead. Always run `chmod 600 ~/.hermes/.env` to prevent other users on the system from reading your API keys.
 
 ### 3. Configure Toolsets
 
@@ -168,6 +168,11 @@ Everything lives under `~/.hermes/`:
 
 > **Important:** `SOUL.md` is injected into every message. Keep it under 1 KB. Every byte costs latency and tokens.
 
+> **Security:** The `.env` file contains your API keys. Restrict its permissions so only you can read it:
+> ```bash
+> chmod 600 ~/.hermes/.env
+> ```
+
 ---
 
 ## Verify Your Setup

part11-gateway-recovery.md

@@ -180,7 +180,7 @@ if ! pgrep -f "hermes.*gateway" > /dev/null; then
     exit 1
 fi
 
-# Can we reach the API?
+# Can we reach the API? (gateway should only listen on localhost)
 if ! curl -s http://localhost:8642/health > /dev/null 2>&1; then
     echo "CRITICAL: Gateway not responding"
     exit 1

part3-lightrag-setup.md

@@ -110,7 +110,7 @@ The server starts on `http://localhost:9623` with:
 - **Web UI** at `http://localhost:9623/webui` for browsing the knowledge graph
 - **Health check** at `http://localhost:9623/health`
 
-> **Security warning:** The LightRAG REST API has **no built-in authentication**. Always bind to `127.0.0.1` (localhost only) — never `0.0.0.0`. If you need remote access, put it behind a reverse proxy (nginx, Caddy) with authentication, or use SSH tunneling. Anyone who can reach this port can query, ingest, or delete your knowledge graph data.
+> **Security warning:** The LightRAG REST API has **no built-in authentication**. Always bind to `127.0.0.1` (localhost only) — never `0.0.0.0`. If you need remote access, put it behind a reverse proxy (nginx, Caddy) with authentication, or use SSH tunneling / Tailscale / WireGuard. Anyone who can reach this port can query, ingest, or delete your entire knowledge graph.
 
 ### Run as a Background Service
 

part4-telegram-setup.md

@@ -254,7 +254,7 @@ Each user gets their own conversation session. The bot tracks sessions per user
 
 ### Bot not responding
 
-1. Check the token is correct: `echo $TELEGRAM_BOT_TOKEN`
+1. Check the token is set (without printing it in full): `echo ${TELEGRAM_BOT_TOKEN:0:10}...`
 2. Verify the gateway is running: `hermes gateway status`
 3. Check logs: `hermes gateway logs`
 

part9-custom-models.md

@@ -154,14 +154,20 @@ tts:
 
 Models are configured in `~/.hermes/config.yaml`:
 
-> **Security note:** Never put real API keys directly in `config.yaml`. Use environment variable references so keys stay in `~/.hermes/.env` (which should be `chmod 600` and never committed to git).
-
+> **Security note:** Never put real API keys directly in `config.yaml`. Use environment variable references so keys stay in `~/.hermes/.env` (which should be `chmod 600` and never committed to git). You can also use `hermes auth` to set them securely.
 ```yaml
 # Default model
 model: claude-sonnet-5
 provider: anthropic
 
 # Provider configurations
+# API keys are loaded from ~/.hermes/.env automatically.
+# Set them with: hermes auth
+# Or add to ~/.hermes/.env:
+#   ANTHROPIC_API_KEY=sk-ant-...
+#   OPENAI_API_KEY=sk-...
+#   CEREBRAS_API_KEY=csk-...
+#   FIREWORKS_API_KEY=fw_...
 providers:
   anthropic:
     api_key: ${ANTHROPIC_API_KEY}
@@ -226,6 +232,8 @@ providers:
 Any provider that implements the OpenAI chat completions API works:
 
 ```yaml
+# Add your API key to ~/.hermes/.env:
+#   MY_CUSTOM_API_KEY=your-key-here
 providers:
   my-custom:
     api_key: ${MY_CUSTOM_API_KEY}
@@ -312,6 +320,7 @@ Cerebras is fast but has quirks:
 Config:
 
 ```yaml
+# Set CEREBRAS_API_KEY in ~/.hermes/.env
 providers:
   cerebras:
     api_key: ${CEREBRAS_API_KEY}