# Hermes Agent Hermes Agent installation, tutorials, configs. # Hermes Agent on Debian 13 in a Proxmox VM ## Hermes Agent on Debian 13 in a Proxmox VM ### Verified scope This guide installs **Hermes Agent by Nous Research**, not Hermes mail server, Hermes JS engine, or any other “Hermes” project. Hermes Agent is documented as an open-source autonomous agent that runs on Linux/macOS/WSL2/Termux and is installed with the upstream installer command from the official documentation ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). The target OS is **Debian 13 “trixie”** inside a Proxmox VM. Debian 13.0 was initially released on August 9, 2025, Debian 13.4 was current as of March 14, 2026, and amd64 is a supported architecture, which is the normal choice for a Proxmox VM on x86\_64 hardware ([Debian trixie release information](https://www.debian.org/releases/trixie/)). The recommended installation mode here is: - A dedicated non-root Linux user named `hermes`. - Upstream Hermes installer, run as that non-root user. - Optional Docker terminal backend for safer agent command execution. - Optional Hermes gateway as a systemd user service or boot-time system service. - Optional Caddy reverse proxy only for the API server, not for normal CLI/gateway bot usage. ### Architecture Hermes Agent stores its normal user configuration under `~/.hermes/config.yaml`, secrets under `~/.hermes/.env`, OAuth credentials under `~/.hermes/auth.json`, logs under `~/.hermes/logs/`, sessions under `~/.hermes/sessions/`, memories under `~/.hermes/memories/`, skills under `~/.hermes/skills/`, and cron jobs under `~/.hermes/cron/` ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). The upstream installer’s documented prerequisite is Git, and the installer handles uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, the repository clone, virtual environment, global `hermes` command setup, and LLM provider configuration ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). On Debian 13, the distro `python3` package tracks Python 3.13, while Hermes’ installer manages Python 3.11 through uv, so do not force Hermes to use Debian’s default Python unless you have a development reason to do so ([Debian python3 package](https://packages.debian.org/trixie/python3), [Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). On Debian 13, the distro `nodejs` package is Node.js 20.19.2, while Hermes’ installer downloads Node.js v22 into the Hermes user environment for browser automation and WhatsApp bridge needs, so the guide avoids installing Debian’s `nodejs` as the primary Hermes runtime ([Debian nodejs package](https://packages.debian.org/trixie/nodejs), [Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). Hermes requires at least one inference provider, and the official provider setup path is `hermes model` from the terminal, not `/model` inside an existing chat session ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). Hermes Agent requires a model with at least **64,000 tokens** of context according to the official quickstart, and local/self-hosted model users must configure the model server with enough context rather than only setting a client-side value ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)). ### Proxmox VM sizing Use this as a practical baseline:
PurposevCPURAMDiskNotes
CLI only, hosted LLM provider24 GB32 GBGood for OpenRouter, Nous Portal, Anthropic, Gemini, Copilot, etc.
Gateway service plus Docker backend48 GB64 GBBetter for always-on bot usage and isolated terminal backend.
Local model in same VM8+32 GB+150 GB+Only if you attach GPU/large RAM; otherwise run Ollama/vLLM elsewhere.
These are operational recommendations, not upstream minimums. Hermes’ official docs describe the installer and runtime providers, while actual VM sizing depends on whether the LLM runs remotely or inside the VM ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). Recommended Proxmox VM hardware: - BIOS: OVMF/UEFI or SeaBIOS; either is fine for Debian 13. - Machine: q35. - CPU type: `host` if migration compatibility is not required; otherwise use your cluster baseline. - Disk bus: SCSI with VirtIO SCSI. - Network: VirtIO NIC on the correct bridge, usually `vmbr0`. - Guest agent: enable in Proxmox and install `qemu-guest-agent` inside Debian. - Backups: enable Proxmox backups after the guest agent works. - Snapshot: take a clean snapshot before running the Hermes installer. The QEMU guest agent is used by Proxmox for better guest shutdown and filesystem freeze/thaw during backup/snapshot operations, so it is worth installing before treating the VM as production ([Proxmox QEMU Guest Agent](https://pve.proxmox.com/wiki/Qemu-guest-agent)). #### 1. Create the Debian 13 VM 1. Download the current Debian 13 amd64 netinst ISO from Debian’s official download path. 2. In Proxmox, create a VM with the sizing above. 3. Select Debian/Linux as the guest OS type. 4. Use VirtIO network and SCSI/VirtIO disk. 5. Install only the SSH server and standard system utilities unless you need a desktop. 6. Set timezone to `Europe/Athens` if this VM is for your local environment. 7. Reboot into the installed system. After first boot, SSH into the VM as your administrative user. ```bash ssh your_admin_user@VM_IP ``` Verify Debian release: ```bash cat /etc/os-release uname -a ``` Expected result: - `PRETTY_NAME` should show Debian GNU/Linux 13 or trixie. - Kernel and architecture should be normal for your Proxmox environment. #### 2. Update Debian and install base packages Run: ```bash sudo apt update sudo apt full-upgrade -y sudo apt install -y \ ca-certificates \ curl \ git \ gnupg \ lsb-release \ qemu-guest-agent \ sudo \ tmux \ unzip \ vim \ wget sudo systemctl enable --now qemu-guest-agent sudo reboot ``` The upstream Hermes documentation says Git is the only prerequisite, but this guide installs common server tools and `qemu-guest-agent` so the VM behaves correctly under Proxmox ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [Proxmox QEMU Guest Agent](https://pve.proxmox.com/wiki/Qemu-guest-agent)). After the reboot, verify the guest agent from the Proxmox host: ```bash qm agent VMID ping ``` Proxmox documents `qm agent ping` as the test command for QEMU guest-agent communication ([Proxmox QEMU Guest Agent](https://pve.proxmox.com/wiki/Qemu-guest-agent)). #### 3. Enable guest agent in Proxmox If you did not enable it in the GUI, run this on the Proxmox host: ```bash qm set VMID --agent 1 ``` Replace `VMID` with the VM ID. Proxmox documents `qm set VMID --agent 1` as the host-side enable command for QEMU guest-agent communication ([Proxmox QEMU Guest Agent](https://pve.proxmox.com/wiki/Qemu-guest-agent)). #### 4. Create a dedicated Hermes user Create a non-root user: ```bash sudo adduser hermes sudo usermod -aG sudo hermes ``` For a hardened always-on gateway, remove passwordless sudo if your template added it and use sudo only when you intentionally administer the system. Hermes’ own security docs explicitly recommend running the gateway as non-root ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). Switch to the Hermes user: ```bash sudo -iu hermes ``` Verify: ```bash whoami pwd ``` Expected: ```text hermes /home/hermes ``` #### 5. Install Hermes Agent Run the official upstream installer as the `hermes` user: ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` This is the official Linux/macOS/WSL2/Termux install command in the Hermes Agent installation docs ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). Reload the shell: ```bash source ~/.bashrc ``` Verify the command exists: ```bash command -v hermes hermes --help ``` The official post-install instruction is to reload the shell and start Hermes with `hermes` ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). #### 6. Verify installer layout Run: ```bash ls -la ~/.hermes ls -la ~/.hermes/hermes-agent ls -la ~/.local/bin/hermes ``` For non-root installs, the upstream installer defaults to code under `~/.hermes/hermes-agent` and links the `hermes` command under `~/.local/bin`; this behavior is visible in the official installer script ([Hermes install.sh on GitHub](https://github.com/NousResearch/hermes-agent/blob/main/scripts/install.sh)). Expected important files: ```text ~/.hermes/config.yaml ~/.hermes/.env ~/.hermes/logs/ ~/.hermes/sessions/ ~/.hermes/memories/ ~/.hermes/skills/ ``` These paths match the official Hermes configuration directory structure ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). Secure the secrets file: ```bash chmod 600 ~/.hermes/.env ``` Hermes’ security documentation explicitly recommends `chmod 600 ~/.hermes/.env` for API keys and secrets ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). #### 7. Run diagnostics Run: ```bash hermes doctor hermes config check ``` `hermes doctor` is the official diagnostic command, and `hermes config check` checks for missing options after installs or updates ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation), [Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). If config migration is requested: ```bash hermes config migrate ``` `hermes config migrate` is the official command to add missing configuration options after updates ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). #### 8. Configure the model provider Run the provider setup wizard from the terminal: ```bash hermes model ``` The official provider docs say `hermes model` is the full setup wizard for OAuth, API keys, provider selection, and custom endpoints, while `/model` inside a chat only switches among already configured providers ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). Recommended choices:
ScenarioProvider path
Easiest hosted setupNous Portal or OpenRouter
You already use ClaudeAnthropic / Claude Code auth
You already use GitHub CopilotGitHub Copilot
You want local/private inferenceCustom endpoint to Ollama, vLLM, SGLang, llama.cpp, or LiteLLM
You want provider routingOpenRouter
Hermes supports providers including Nous Portal, OpenAI Codex, GitHub Copilot, Anthropic, OpenRouter, Google/Gemini, DeepSeek, Hugging Face, Ollama Cloud, AWS Bedrock, and custom OpenAI-compatible endpoints ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). ##### OpenRouter example Use the wizard: ```bash hermes model ``` Or set the key directly: ```bash hermes config set OPENROUTER_API_KEY sk-or-v1-REPLACE_ME hermes model ``` The official docs show API provider keys stored in `~/.hermes/.env`, and `hermes config set OPENROUTER_API_KEY ...` saves the secret in the right place ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). ##### Local Ollama example If Ollama runs on the same VM: ```bash ollama pull qwen2.5-coder:32b OLLAMA_CONTEXT_LENGTH=65536 ollama serve ``` Then configure Hermes: ```bash hermes model # Select: Custom endpoint (self-hosted / VLLM / etc.) # URL: http://localhost:11434/v1 # API key: leave empty or use ollama # Model: qwen2.5-coder:32b # Context length: 65536 ``` The official provider docs describe local Ollama as an OpenAI-compatible custom endpoint at `http://localhost:11434/v1` and warn that context must be configured server-side for Ollama ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). Verify Ollama context: ```bash ollama ps ``` The official provider docs say to check the `CONTEXT` column in `ollama ps` to verify the effective context length ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). Important: Hermes’ quickstart says models below 64,000 tokens of context are rejected at startup, while the providers page also explains practical local-agent context issues around smaller context windows; for Hermes Agent on a server, target 64K context unless you have verified a newer upstream behavior in your installed version ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart), [Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). #### 9. First chat test Run: ```bash hermes ``` Send: ```text Reply with exactly: HERMES_OK ``` Success criteria: - Hermes starts without a Python, Node, or provider error. - The banner shows the selected provider/model. - The response contains `HERMES_OK`. The official quickstart says success looks like a banner showing the chosen model/provider, a normal reply, and successful multi-turn operation ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)). Exit, then test session persistence: ```bash hermes --continue ``` `hermes --continue` and `hermes -c` are the official commands to resume the most recent session ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)). #### 10. Configure safer terminal execution For a Proxmox server, use Docker backend unless you explicitly want Hermes to run commands directly on the VM. Hermes’ security docs state that local backend has no isolation, while Docker, Singularity, Modal, and Daytona provide isolation boundaries for terminal execution ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). Install Docker from Debian: ```bash exit sudo apt update sudo apt install -y docker.io sudo systemctl enable --now docker sudo usermod -aG docker hermes sudo -iu hermes newgrp docker docker run --rm hello-world ``` Debian documents `docker.io` as Debian’s Docker package, and Debian 13 provides `docker.io` for trixie ([Debian Docker wiki](https://wiki.debian.org/Docker), [Debian docker.io package](https://packages.debian.org/trixie/docker.io)). Set Hermes terminal backend: ```bash hermes config set terminal.backend docker ``` The Hermes configuration docs show `hermes config set terminal.backend docker` as the command to switch the terminal backend to Docker ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). Review Docker resource defaults: ```bash hermes config edit ``` Recommended Docker block: ```yaml terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20" docker_forward_env: [] container_cpu: 2 container_memory: 5120 container_disk: 51200 container_persistent: true ``` Hermes’ security docs recommend Docker, Modal, or Daytona for production gateway deployments and show `docker_forward_env: []` to keep secrets out of the container unless explicitly allowed ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). Run a tool-capable chat test: ```bash hermes ``` Ask: ```text Use the terminal to run: pwd && whoami && python --version ``` Expected: - The command runs in the configured terminal backend. - If Docker backend is active, the execution environment is containerized. - Dangerous commands still require attention depending on backend and approval settings. #### 11. Configure command approval behavior Open config: ```bash hermes config edit ``` Recommended: ```yaml approvals: mode: manual timeout: 60 ``` `approvals.mode` supports `manual`, `smart`, and `off`, and the default manual mode prompts for dangerous commands while timeout denial fails closed ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). Do not use this on a server unless you fully understand the risk: ```yaml approvals: mode: off ``` Hermes documents `approvals.mode: off`, `hermes --yolo`, `/yolo`, and `HERMES_YOLO_MODE=1` as ways to bypass dangerous command approvals, and warns that disabling approval checks is equivalent to running with `--yolo` ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). #### 12. Optional gateway setup The gateway is the always-on background process that connects Hermes to messaging platforms, handles sessions, runs cron jobs, and delivers voice messages ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). Configure platforms: ```bash hermes gateway setup ``` Start in foreground first: ```bash hermes gateway ``` The official gateway docs list `hermes gateway setup` for interactive platform configuration and `hermes gateway` for foreground execution ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). In another SSH session: ```bash sudo -iu hermes hermes gateway status tail -f ~/.hermes/logs/gateway.log ``` The official docs list `hermes gateway status` and gateway log paths for checking the service ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). #### 13. Gateway allowlists Edit secrets: ```bash nano ~/.hermes/.env ``` Set only the platforms you use: ```bash # Telegram example TELEGRAM_BOT_TOKEN=REPLACE_ME TELEGRAM_ALLOWED_USERS=123456789 # Discord example DISCORD_TOKEN=REPLACE_ME DISCORD_ALLOWED_USERS=111222333444555666 # Global allowlist fallback GATEWAY_ALLOWED_USERS=123456789 ``` Hermes’ gateway docs recommend restricting access to specific users and show platform-specific allowlist variables such as `TELEGRAM_ALLOWED_USERS`, `DISCORD_ALLOWED_USERS`, and `GATEWAY_ALLOWED_USERS` ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). Do not use this in production: ```bash GATEWAY_ALLOW_ALL_USERS=true ``` Hermes explicitly marks `GATEWAY_ALLOW_ALL_USERS=true` as not recommended for bots with terminal access, and the security docs state the default behavior denies users who are neither allowlisted nor paired ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/), [Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)). Secure `.env` again: ```bash chmod 600 ~/.hermes/.env ``` #### 14. Install gateway as a service ##### Option A: systemd user service Run as `hermes`: ```bash hermes gateway install hermes gateway start hermes gateway status journalctl --user -u hermes-gateway -f ``` The official gateway docs list `hermes gateway install`, `start`, `status`, and `journalctl --user -u hermes-gateway -f` for a Linux user service ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). Keep the user service running after logout: ```bash exit sudo loginctl enable-linger hermes ``` The official gateway docs recommend `sudo loginctl enable-linger $USER` to keep a user service running after logout ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). ##### Option B: boot-time system service Run from the `hermes` account if it has sudo: ```bash sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f ``` The official gateway docs list `sudo hermes gateway install --system`, `start --system`, `status --system`, and `journalctl -u hermes-gateway -f` for a Linux boot-time system service ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). #### 15. Optional API server Only enable the API server if you need Hermes exposed as an OpenAI-compatible HTTP backend for another frontend. The Hermes API server exposes the agent as an OpenAI-compatible endpoint and gives access to the agent’s full toolset, including terminal commands, so treat it as sensitive ([Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). Edit: ```bash nano ~/.hermes/.env ``` Add: ```bash API_SERVER_ENABLED=true API_SERVER_HOST=127.0.0.1 API_SERVER_PORT=8642 API_SERVER_KEY=replace-with-a-long-random-token ``` The API server docs show `API_SERVER_ENABLED`, `API_SERVER_HOST`, `API_SERVER_PORT`, and `API_SERVER_KEY`, with default host `127.0.0.1` and default port `8642` ([Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). Restart gateway: ```bash hermes gateway restart || { hermes gateway stop hermes gateway start } ``` Test locally: ```bash curl http://localhost:8642/v1/chat/completions \ -H "Authorization: Bearer replace-with-a-long-random-token" \ -H "Content-Type: application/json" \ -d '{"model":"hermes-agent","messages":[{"role":"user","content":"Reply with API_OK"}]}' ``` The official API server docs show the same `/v1/chat/completions` test pattern with Bearer-token authorization ([Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). #### 16. Optional Caddy reverse proxy Keep the Hermes API bound to `127.0.0.1` and let Caddy handle TLS. This avoids binding Hermes directly to the network while still allowing HTTPS access through Caddy. Example Caddyfile: ```caddyfile hermes.example.com { reverse_proxy 127.0.0.1:8642 } ``` Do **not** expose the API server without a strong `API_SERVER_KEY`, because Hermes’ API server docs state that Bearer-token auth is required when binding to non-loopback addresses and that the endpoint exposes the full toolset including terminal commands ([Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). If a browser app calls the API directly, set CORS explicitly: ```bash API_SERVER_CORS_ORIGINS=https://your-frontend.example.com ``` The API server docs describe `API_SERVER_CORS_ORIGINS` as the comma-separated allowlist for browser origins ([Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). #### 17. Firewall rules For normal Telegram/Discord/Slack/etc. gateway use, the VM usually needs outbound Internet access only, because bot adapters typically connect outward to platform APIs. Minimum inbound firewall: ```bash sudo apt install -y nftables sudo systemctl enable --now nftables ``` Example `/etc/nftables.conf`: ```nft #!/usr/sbin/nft -f flush ruleset table inet filter { chain input { type filter hook input priority 0; policy drop; iif "lo" accept ct state established,related accept tcp dport 22 accept # Optional: only if Caddy is installed on this VM tcp dport {80, 443} accept icmp type echo-request accept ip6 nexthdr ipv6-icmp accept } chain forward { type filter hook forward priority 0; policy drop; } chain output { type filter hook output priority 0; policy accept; } } ``` Apply: ```bash sudo nft -f /etc/nftables.conf sudo nft list ruleset ``` This firewall section is an operational baseline for the VM; Hermes-specific exposure decisions are governed by the gateway and API server configuration described in the official docs ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/), [Hermes Agent API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)). #### 18. Backups Back up at least: ```text /home/hermes/.hermes/ ``` That directory contains config, secrets, OAuth credentials, sessions, memories, skills, cron jobs, and logs according to the official directory layout ([Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). Suggested local backup script: ```bash sudo install -d -m 700 -o hermes -g hermes /home/hermes/backups sudo -iu hermes bash -lc ' set -euo pipefail ts="$(date -u +%Y%m%d-%H%M%S)" tar --exclude="$HOME/.hermes/hermes-agent/.git" \ -czf "$HOME/backups/hermes-home-$ts.tar.gz" \ -C "$HOME" .hermes ls -lh "$HOME/backups/hermes-home-$ts.tar.gz" ' ``` For Proxmox backups, make sure QEMU guest agent works before relying on snapshot consistency, because Proxmox uses the guest agent to freeze and thaw guest filesystems during backup/snapshot operations ([Proxmox QEMU Guest Agent](https://pve.proxmox.com/wiki/Qemu-guest-agent)). #### 19. Update procedure Run as `hermes`: ```bash hermes update hermes config check hermes config migrate hermes doctor ``` `hermes update` is listed in the official quick reference, and `hermes config check` plus `hermes config migrate` are the documented post-update configuration checks ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart), [Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)). If the gateway runs as a service: ```bash hermes gateway restart hermes gateway status ``` The gateway docs include start/stop/status service management commands, and restart is listed in Hermes gateway command references in the docs ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). #### 20. Rollback procedure Before major changes: 1. Stop the gateway. 2. Take a Proxmox snapshot. 3. Back up `/home/hermes/.hermes/`. 4. Run updates. 5. Verify with `hermes doctor`, a CLI chat, and gateway status. Stop service: ```bash sudo -iu hermes hermes gateway stop || true ``` Restore local Hermes state: ```bash sudo -iu hermes mv ~/.hermes ~/.hermes.broken.$(date -u +%Y%m%d-%H%M%S) tar -xzf ~/backups/hermes-home-YYYYMMDD-HHMMSS.tar.gz -C ~ chmod 600 ~/.hermes/.env hermes doctor ``` If the VM itself is broken, restore the Proxmox snapshot or backup. #### 21. Verification checklist Run these in order: ```bash cat /etc/os-release git --version command -v hermes hermes --help hermes doctor hermes config check hermes config show ``` Expected: - Debian reports version 13/trixie. - Git exists. - `hermes` resolves from `/home/hermes/.local/bin/hermes`. - `hermes doctor` does not report blocking errors. - `hermes config check` does not require unresolved migrations. Provider test: ```bash hermes chat -q "Reply with exactly PROVIDER_OK" ``` Gateway test: ```bash hermes gateway status journalctl --user -u hermes-gateway -n 100 --no-pager ``` API server test if enabled: ```bash curl -fsS http://localhost:8642/v1/models \ -H "Authorization: Bearer replace-with-a-long-random-token" ``` Docker backend test if enabled: ```bash docker info >/dev/null hermes config show | grep -i 'backend' ``` ### 22. Troubleshooting #### `hermes: command not found` Run: ```bash source ~/.bashrc echo "$PATH" ls -la ~/.local/bin/hermes ``` The official installation troubleshooting says to reload the shell or check PATH when `hermes: command not found` appears ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). #### API key not set Run: ```bash hermes model ``` Or set the key: ```bash hermes config set OPENROUTER_API_KEY sk-or-v1-REPLACE_ME ``` The official installation troubleshooting says `API key not set` is fixed by running `hermes model` or setting the provider key through config ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). #### Missing config after update Run: ```bash hermes config check hermes config migrate ``` The official installation troubleshooting lists this exact fix for missing config after update ([Hermes Agent Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)). #### Gateway starts but nobody can message it Run: ```bash hermes gateway setup hermes gateway status grep -E 'ALLOWED_USERS|ALLOW_ALL|TOKEN' ~/.hermes/.env ``` The official quickstart says gateway message failures are usually caused by bot token, allowlist, or incomplete platform setup, and recommends re-running `hermes gateway setup` plus checking `hermes gateway status` ([Hermes Agent Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)). #### Local model “works” but Hermes fails or gives bad tool output Verify: ```bash curl http://localhost:11434/v1/models ollama ps hermes model ``` The provider docs warn that wrong base URL, model name, endpoint compatibility, or context configuration can break custom endpoints, and they give `curl http://localhost:11434/v1/models` and `ollama ps` as verification steps ([Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)). #### Context length errors Check the startup line or run `/usage` inside a session, then set an explicit context length: ```yaml model: context_length: 65536 ``` The FAQ says the CLI shows detected context length, `/usage` shows usage during a session, and `model.context_length` can override the detected model context ([Hermes Agent FAQ](https://hermes-agent.nousresearch.com/docs/reference/faq)). #### Docker permission denied Run: ```bash sudo usermod -aG docker hermes sudo -iu hermes newgrp docker docker run --rm hello-world ``` The Hermes FAQ lists `docker info`, adding the user to the `docker` group, `newgrp docker`, and `docker run hello-world` as Docker troubleshooting commands ([Hermes Agent FAQ](https://hermes-agent.nousresearch.com/docs/reference/faq)). #### Gateway logs User service: ```bash journalctl --user -u hermes-gateway -f ``` System service: ```bash journalctl -u hermes-gateway -f ``` Hermes’ gateway docs list these exact journalctl commands for user and system services ([Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)). ### Final hardening checklist - The VM has Proxmox QEMU guest agent installed, enabled, and pingable. - The `hermes` Linux user owns `/home/hermes/.hermes`. - `~/.hermes/.env` is mode `600`. - `GATEWAY_ALLOW_ALL_USERS=true` is not set. - Platform-specific or global allowed-user lists are set for every messaging platform. - `terminal.backend` is `docker` for always-on gateway use. - Docker resource limits are configured. - `approvals.mode` is `manual` unless running inside a deliberately disposable sandbox. - API server is disabled unless needed. - API server stays bound to `127.0.0.1` unless there is a strong Bearer token and firewall/reverse-proxy policy. - Proxmox backups include the VM and Hermes state. - A manual backup of `/home/hermes/.hermes/` exists before upgrades. This hardening checklist follows Hermes’ own production gateway recommendations: explicit allowlists, container backend, resource limits, secure secrets, DM pairing when useful, command allowlist review, safe working directory, non-root gateway, log monitoring, and regular updates ([Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)).