fix: address security issues in documentation examples

- Replace hardcoded API key placeholders with env var references in config.yaml examples (part9)
- Standardize placeholder keys to use obvious non-secret patterns (<your-key-here>)
- Add security warning for unauthenticated LightRAG REST API (bind to 127.0.0.1)
- Add proper cryptographic secret generation for Telegram webhook secret
- Add chmod 600 guidance for .env files containing API keys
- Add curl-pipe-to-bash inspection tip for install command
- Replace realistic-looking Telegram bot token examples with safe placeholders

Co-Authored-By: Rob <onerobby@gmail.com>

Author: devin-ai-integration[bot]

README.md

@@ -109,6 +109,13 @@ One command. That's it.
 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```
 
+> **Security tip:** Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
+> less install.sh   # Review the script
+> bash install.sh
+> ```
+
 > **Windows users:** Native Windows is not supported. Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command from inside WSL. It works perfectly.
 
 ### What the Installer Does
@@ -185,8 +192,11 @@ This opens an interactive menu to add API keys for each provider. Keys are store
 
 > **Tip:** You can also set keys manually:
 > ```bash
-> echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.hermes/.env
+> echo "ANTHROPIC_API_KEY=<your-key-here>" >> ~/.hermes/.env
+> 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.
 
 ### 3. Configure Toolsets
 
@@ -621,18 +631,20 @@ Create `~/.hermes/lightrag/.env`:
 # LLM for entity extraction (during ingestion)
 LLM_BINDING=openai
 LLM_MODEL=kimi-2.5                    # What we actually use — great quality/cost ratio
-LLM_BINDING_API_KEY=***
+LLM_BINDING_API_KEY=<your-api-key>
 
 # Embedding model (for vector storage)
 EMBEDDING_BINDING=fireworks
 EMBEDDING_MODEL=accounts/fireworks/models/qwen3-embedding-8b
-EMBEDDING_API_KEY=***
+EMBEDDING_API_KEY=<your-fireworks-api-key>
 
 # Or use local Ollama (free, no API key needed):
 # EMBEDDING_BINDING=ollama
 # EMBEDDING_MODEL=nomic-embed-text
 ```
 
+> **Security tip:** Set restrictive permissions on this file: `chmod 600 ~/.hermes/lightrag/.env`
+
 ### Entity Extraction Model — What to Use
 
 This is the LLM that reads your documents and pulls out entities and relationships during ingestion. Quality here directly determines how good your knowledge graph is.
@@ -658,15 +670,17 @@ This is the LLM that reads your documents and pulls out entities and relationshi
 ```bash
 cd ~/.hermes/lightrag/LightRAG
 
-# Start the API server
-lightrag-server --port 9623
+# Start the API server (binds to localhost by default)
+lightrag-server --host 127.0.0.1 --port 9623
 ```
 
 The server starts on `http://localhost:9623` with:
 - **REST API** for ingestion and querying
 - **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.
+
 ### Run as a Background Service
 
 ```bash
@@ -1088,8 +1102,8 @@ Select **Telegram** when prompted. The wizard asks for your bot token and allowe
 Add the following to `~/.hermes/.env`:
 
 ```bash
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users
+TELEGRAM_BOT_TOKEN=<your-bot-token-from-botfather>
+TELEGRAM_ALLOWED_USERS=<your-numeric-user-id>    # Comma-separated for multiple users
 ```
 
 For groups, also add the group chat ID (negative number, like `-1001234567890`):
@@ -1173,9 +1187,19 @@ Add to `~/.hermes/.env`:
 
 ```bash
 TELEGRAM_WEBHOOK_URL=https://your-app.fly.dev
-TELEGRAM_WEBHOOK_SECRET=your-random-secret-here
+TELEGRAM_WEBHOOK_SECRET=<generate-with-command-below>
 ```
 
+Generate a strong secret — never use a guessable value:
+
+```bash
+openssl rand -hex 32
+```
+
+Copy the output and paste it as your `TELEGRAM_WEBHOOK_SECRET` value.
+
+> **Warning:** A weak or default webhook secret lets attackers forge Telegram webhook requests and inject messages into your agent. Always use a cryptographically random value.
+
 | | Polling (default) | Webhook |
 |---|---|---|
 | Direction | Gateway → Telegram | Telegram → Gateway |

part1-setup.md

@@ -14,6 +14,13 @@ One command. That's it.
 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```
 
+> **Security tip:** Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
+> less install.sh   # Review the script
+> bash install.sh
+> ```
+
 > **Windows users:** Native Windows is not supported. Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command from inside WSL. It works perfectly.
 
 ### What the Installer Does
@@ -74,8 +81,11 @@ This opens an interactive menu to add API keys for each provider. Keys are store
 
 > **Tip:** You can also set keys manually:
 > ```bash
-> echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.hermes/.env
+> echo "ANTHROPIC_API_KEY=<your-key-here>" >> ~/.hermes/.env
+> 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.
 
 ### 3. Configure Toolsets
 

part3-lightrag-setup.md

@@ -72,18 +72,20 @@ Create `~/.hermes/lightrag/.env`:
 # LLM for entity extraction (during ingestion)
 LLM_BINDING=openai
 LLM_MODEL=gpt-4.1-mini
-LLM_BINDING_API_KEY=sk-...
+LLM_BINDING_API_KEY=<your-openai-api-key>
 
 # Embedding model (for vector storage)
 EMBEDDING_BINDING=fireworks
 EMBEDDING_MODEL=accounts/fireworks/models/qwen3-embedding-8b
-EMBEDDING_API_KEY=fw_...
+EMBEDDING_API_KEY=<your-fireworks-api-key>
 
 # Or use local Ollama (free, no API key needed):
 # EMBEDDING_BINDING=ollama
 # EMBEDDING_MODEL=nomic-embed-text
 ```
 
+> **Security tip:** Set restrictive permissions on this file: `chmod 600 ~/.hermes/lightrag/.env`
+
 > **Tip:** Use `gpt-4.1-mini` or `claude-sonnet-4-20250514` for entity extraction. It doesn't need to be your smartest model — it just needs to reliably identify entities and relationships. Cheaper models save money on ingestion.
 
 > **Embedding quality matters.** If you have a GPU with 8GB+ VRAM, run `nomic-embed-text` locally via Ollama for free. If you want the best quality, use Fireworks' Qwen3-Embedding-8B (4096 dimensions) — the search accuracy difference is dramatic.
@@ -97,15 +99,17 @@ EMBEDDING_API_KEY=fw_...
 ```bash
 cd ~/.hermes/lightrag/LightRAG
 
-# Start the API server
-lightrag-server --port 9623
+# Start the API server (binds to localhost by default)
+lightrag-server --host 127.0.0.1 --port 9623
 ```
 
 The server starts on `http://localhost:9623` with:
 - **REST API** for ingestion and querying
 - **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.
+
 ### Run as a Background Service
 
 ```bash

part4-telegram-setup.md

@@ -109,10 +109,12 @@ Select **Telegram** when prompted. The wizard asks for your bot token and allowe
 Add the following to `~/.hermes/.env`:
 
 ```bash
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users
+TELEGRAM_BOT_TOKEN=<your-bot-token-from-botfather>
+TELEGRAM_ALLOWED_USERS=<your-numeric-user-id>    # Comma-separated for multiple users
 ```
 
+> **Security tip:** After editing, run `chmod 600 ~/.hermes/.env` to restrict file access to your user only.
+
 For groups, also add the group chat ID (negative number, like `-1001234567890`):
 
 ```bash
@@ -194,9 +196,19 @@ Add to `~/.hermes/.env`:
 
 ```bash
 TELEGRAM_WEBHOOK_URL=https://your-app.fly.dev
-TELEGRAM_WEBHOOK_SECRET=your-random-secret-here
+TELEGRAM_WEBHOOK_SECRET=<generate-with-command-below>
 ```
 
+Generate a strong secret — never use a guessable value:
+
+```bash
+openssl rand -hex 32
+```
+
+Copy the output and paste it as your `TELEGRAM_WEBHOOK_SECRET` value.
+
+> **Warning:** A weak or default webhook secret lets attackers forge Telegram webhook requests and inject messages into your agent. Always use a cryptographically random value.
+
 | | Polling (default) | Webhook |
 |---|---|---|
 | Direction | Gateway → Telegram | Telegram → Gateway |

part9-custom-models.md

@@ -8,6 +8,8 @@
 
 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).
+
 ```yaml
 # Default model
 model: claude-sonnet-4-20250514
@@ -16,22 +18,22 @@ provider: anthropic
 # Provider configurations
 providers:
   anthropic:
-    api_key: sk-ant-...
+    api_key: ${ANTHROPIC_API_KEY}
 
   openai:
-    api_key: sk-...
+    api_key: ${OPENAI_API_KEY}
 
   cerebras:
-    api_key: csk-...
+    api_key: ${CEREBRAS_API_KEY}
     base_url: https://api.cerebras.ai/v1
 
   fireworks:
-    api_key: fw_...
+    api_key: ${FIREWORKS_API_KEY}
     base_url: https://api.fireworks.ai/inference/v1
 
   local:
     base_url: http://localhost:11434/v1
-    api_key: ollama
+    api_key: ollama  # Ollama doesn't require a real key
 ```
 
 ## Adding a Custom Provider
@@ -41,10 +43,17 @@ Any provider that implements the OpenAI chat completions API works:
 ```yaml
 providers:
   my-custom:
-    api_key: your-key-here
+    api_key: ${MY_CUSTOM_API_KEY}
     base_url: https://api.your-provider.com/v1
 ```
 
+Add the actual key to your `.env` file:
+
+```bash
+echo "MY_CUSTOM_API_KEY=<your-key-here>" >> ~/.hermes/.env
+chmod 600 ~/.hermes/.env
+```
+
 Then use it:
 
 ```bash
@@ -102,7 +111,7 @@ Config:
 ```yaml
 providers:
   cerebras:
-    api_key: csk-your-key
+    api_key: ${CEREBRAS_API_KEY}
     base_url: https://api.cerebras.ai/v1
     # Models: llama-3.3-70b, llama-4-scout-17b-16e-instruct, qwen-3-32b
 ```