Skip to content

Operations

Deployment, configuration, CLI usage, 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 to avoid storing keys 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 execute 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 security).

SSH

terminal:
  backend: ssh

Configure SSH host, user, and key in config.yaml or via environment variables. Commands execute 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.

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