Skip to content

How-to Guides

Deployment, configuration, CLI usage, security setup, and troubleshooting for Hermes Agent.

Installation

Works on Linux, macOS, WSL2, and Android via Termux:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Install via pip / uv

pip install git+https://github.com/NousResearch/hermes-agent.git
# or
uv pip install git+https://github.com/NousResearch/hermes-agent.git

From Source

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

Docker

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

Docker API key injection

Override .env file values by passing API keys directly with -e flags. Useful for CI/CD pipelines and secrets-manager integrations so that keys are not stored on disk.

Configuration

Setup Wizard

hermes setup                     # Full interactive wizard
hermes setup model               # Model provider only
hermes setup terminal            # Terminal backend only
hermes setup gateway             # Messaging platforms only
hermes setup tools               # Enable/disable tools
hermes setup agent               # Agent behavior settings
hermes setup --non-interactive   # Use defaults / env values
hermes setup --reset             # Reset to defaults first

Config Management

API keys are automatically routed to ~/.hermes/.env. All other settings go to ~/.hermes/config.yaml.

hermes config                    # View current configuration
hermes config edit               # Open config.yaml in editor
hermes config set KEY VAL        # Set a specific value
hermes config check              # Check for missing options after updates
hermes config migrate            # Interactively add missing options
hermes config show               # Display full resolved config

Examples:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saved to .env

Model Provider Setup

hermes model                     # Interactive provider/model chooser

Hermes is LLM-agnostic. Supported providers include Nous Portal, OpenRouter (200+ models), NVIDIA NIM, OpenAI, Anthropic, DeepSeek, Gemini, Ollama, and custom endpoints. Switch with hermes model -- no code changes required.

CLI Commands

Chat

hermes                           # Interactive chat (default)
hermes chat -q "Single query"   # One-shot mode
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills
hermes chat --quiet -q "Return only JSON"
hermes chat --worktree -q "Review this repo and open a PR"
hermes chat --ignore-user-config --ignore-rules -q "Repro without personal setup"
hermes --list-tools              # List available tools and exit

hermes search "deployment script from last week"

FTS5 full-text search across all past sessions with LLM-powered summarization of results.

Skill Management

hermes skills browse                              # Browse all hub skills
hermes skills browse --source official            # Official optional skills only
hermes skills search kubernetes                   # Search all sources
hermes skills search react --source skills-sh     # Search skills.sh directory
hermes skills inspect openai/skills/k8s           # Preview before installing
hermes skills install openai/skills/k8s           # Install with security scan
hermes skills install official/security/1password
hermes skills list --source hub                   # List hub-installed skills
hermes skills check                               # Check for upstream updates
hermes skills update                              # Reinstall with upstream changes
hermes skills audit                               # Re-scan all hub skills for security
hermes skills uninstall k8s                       # Remove a hub skill
hermes skills reset google-workspace              # Un-stick from user-modified state
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json          # Export skill config
hermes skills tap add myorg/skills-repo           # Add custom GitHub source

Honcho Memory

hermes honcho setup              # Configure Honcho integration
hermes honcho status             # Check connection
hermes honcho map my-project     # Map directory to session name
hermes honcho mode hybrid        # Set mode: hybrid | honcho | local

Gateway

hermes gateway setup             # Interactive platform setup
hermes gateway                   # Start in foreground
hermes gateway start             # Start as background service
hermes gateway stop              # Stop service
hermes gateway status            # Check status
hermes gateway install           # Install as system service

System

hermes doctor                    # Health check
hermes update                    # Pull latest code, sync skills
hermes logs tail                 # Tail log files
hermes --version                 # Show version

Terminal Backend Setup

Local (Default)

No additional configuration. Commands run on the host machine.

terminal:
  backend: local
  cwd: "."
  timeout: 180

Dangerous command checks active

The local backend prompts for approval on dangerous patterns (recursive deletes, SQL drops, piping curl to shell). Respond with [o]nce, [s]ession, [a]lways, or [d]eny.

Docker

terminal:
  backend: docker
  cwd: "/root"
  timeout: 180

Each session starts a long-lived container. Commands run via docker exec with a login shell. Container is stopped and removed on cleanup. Security hardening is applied automatically (see Explanation: Sandboxing).

SSH

terminal:
  backend: ssh

Configure SSH host, user, and key in config.yaml or via environment variables. Commands run on the remote server.

Daytona

terminal:
  backend: daytona
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"

Serverless persistence -- workspaces hibernate when idle. Requires a Daytona account.

Singularity

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"

For HPC cluster environments. Uses Singularity/Apptainer containers.

terminal:
  backend: modal
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"

Serverless cloud execution with pay-per-use pricing and near-zero idle cost. Requires a Modal account.

Environment Passthrough

Forward host environment variables to sandboxed backends:

terminal:
  env_passthrough: [GITHUB_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY]

Multi-Platform Channel Configuration

Telegram

# Interactive
hermes gateway setup   # Select Telegram, enter bot token

# Manual (~/.hermes/.env)
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Discord

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

Slack

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890
SLACK_HOME_CHANNEL_NAME=general

Other Platforms

Install platform-specific dependencies as needed:

pip install "hermes-agent[telegram]"
pip install "hermes-agent[discord]"
pip install "hermes-agent[slack]"
pip install "hermes-agent[whatsapp]"

Each platform adapter is configured via environment variables in ~/.hermes/.env. Per-profile bot tokens are supported via ~/.hermes/profiles/<name>/.env.

API Key Management

API keys are stored in ~/.hermes/.env and managed via the CLI:

hermes config set OPENROUTER_API_KEY sk-or-...   # Auto-routed to .env
hermes config set ANTHROPIC_API_KEY sk-ant-...

File permissions

Restrict .env to owner-only access: 

chmod 600 ~/.hermes/.env

Best practices:

  • Never commit .env files to version control
  • Use per-profile .env files (~/.hermes/profiles/<name>/.env) to isolate credentials between use cases
  • In Docker, pass keys via -e flags instead of mounting .env to prevent on-disk storage
  • Use env_passthrough in config.yaml to forward only required keys to sandboxed backends

Channel Authentication

Each platform adapter enforces an allowlist of authorized user IDs:

Platform Env Variable Format
Telegram TELEGRAM_ALLOWED_USERS Comma-separated numeric user IDs
Discord DISCORD_ALLOWED_USERS Comma-separated Discord user IDs
Slack SLACK_ALLOWED_USERS Comma-separated Slack Member IDs

Messages from users not in the allowlist are silently dropped. There is no open-registration mode.

Network Security

API Server Binding

The API server gives full access to Hermes's toolset, including terminal commands. The API_SERVER_KEY is required when binding to a non-loopback address:

# Safe: loopback only (default)
hermes api --host 127.0.0.1

# Requires API_SERVER_KEY for non-loopback
hermes api --host 0.0.0.0

Keep API_SERVER_CORS_ORIGINS narrow to control browser access.

Web Dashboard

The web dashboard reads and writes ~/.hermes/.env. It binds to 127.0.0.1 by default.

Dashboard exposure

Binding the dashboard to 0.0.0.0 exposes your API keys and credentials to anyone on your network. The dashboard has no built-in authentication. Use a reverse proxy with TLS and authentication if remote access is required.

Gateway Network Exposure

Platform adapters use outbound connections (long polling, WebSocket) and do not require inbound port exposure in most configurations. Exceptions:

  • Webhook mode (Telegram, Feishu, WeCom) requires an inbound HTTPS endpoint
  • API server adapter requires a listening port

For webhook-based platforms, deploy behind a reverse proxy with TLS termination.

Monitoring and Logging

hermes logs tail                 # Tail all logs
hermes doctor                    # System health check
hermes gateway status            # Gateway process status
hermes honcho status             # Memory provider status
hermes config show               # Full resolved configuration

Log files are stored in ~/.hermes/logs/ and cover agent, gateway, and error events.

Upgrading

hermes update

This pulls the latest code and syncs new bundled skills to all profiles. User-modified skills are never overwritten.

After upgrading, run:

hermes config check              # Identify new config options
hermes config migrate            # Interactively add missing options

Troubleshooting

Gateway fails to start

pip install "hermes-agent[telegram]"   # Install missing platform deps
lsof -i :8080                          # Check for port conflicts
hermes config show                     # Verify configuration

Model provider errors

hermes doctor                          # Validates API key connectivity
hermes model                           # Reconfigure provider/model

Skill loading issues

hermes skills audit                    # Re-scan for security issues
hermes skills check                    # Check for version mismatches
hermes skills reset <name> --restore   # Restore bundled version

Sources