Hermes Agent

Learn about configurations >

• ai-api-key | string

  API key for the selected AI provider. Required for most providers. Not required for: ollama (local), bedrock (AWS credentials), nous (OAuth).

• ai-base-url | string

  Custom API base URL for OpenAI-compatible providers. Examples: http://localhost:1234/v1 (LM Studio), http://localhost:8000/v1 (vLLM)

• ai-fallback-models | string

  Comma-separated fallback models in provider/model format. These are tried in order when the primary model fails. Use ai-api-key for the primary provider; fallback providers that share the same key will reuse it automatically. Example: "anthropic/claude-sonnet-4,openai/gpt-4,google/gemini-2.5-pro"

• ai-model | string

  AI model(s) to use. Supports comma-separated list for fallback:

  • Single: claude-opus-4-5
  • Multiple: gpt-4,claude-sonnet-4,gemini-2.5-pro First model is primary, rest are fallbacks.

• ai-provider | string

  Primary AI model provider. Supported providers:

  • copilot: GitHub Copilot (recommended — set ai-api-key to your GitHub token)
  • anthropic: Anthropic Claude models
  • openai: OpenAI GPT models
  • google: Google Gemini models
  • openrouter: OpenRouter aggregator
  • xai: xAI models
  • groq: Groq models
  • deepseek: DeepSeek models
  • mistral: Mistral AI models
  • ollama: Local Ollama models (no API key needed)
  • bedrock: AWS Bedrock (uses AWS credentials)
  • nous: Nous Portal (OAuth) Aliases: github-copilot → copilot, gemini → google

• auto-update | boolean

  Automatically update Hermes Agent to latest version on upgrade-charm

• compression-enabled | boolean

  Default: True

  Enable context compression when conversation grows long

• dashboard-password | string

  Password for dashboard basic auth. The charm hashes this automatically using scrypt before writing to config.yaml. Required when dashboard-username is set.

• dashboard-port | int

  Default: 9119

  Port for the Hermes Dashboard web UI

• dashboard-username | string

  Username for dashboard basic auth. Setting both dashboard-username and dashboard-password enables the dashboard and binds it to 0.0.0.0. Leave empty to disable the dashboard service entirely.

• discord-bot-token | string

  Discord bot token from Discord Developer Portal. Leave empty to disable Discord messaging.

• dm-policy | string

  Default: pairing

  DM access policy: 'pairing' (require pairing code), 'open' (auto-respond), or 'closed' (reject all DMs)

• gateway-allow-all-users | boolean

  Allow all users to interact without pairing. WARNING: Only set to true in trusted environments. When false, users must pair via DM code first.

• gateway-port | int

  Default: 3000

  Port for the Hermes Agent Gateway HTTP/WebSocket server

• home-assistant-token | string

  Long-lived access token for Home Assistant API. Required when home-assistant-url is configured.

• home-assistant-url | string

  Home Assistant URL for HA integration (e.g., http://homeassistant.local:8123). Leave empty to disable.

• install-method | string

  Default: script

  Installation method:

  • 'script' (recommended): Official install.sh from hermes-agent.nousresearch.com. Uses git + uv, installs to ~/.hermes/hermes-agent/. This is the only officially supported install path as of mid-2026.
  • 'git': Clone NousResearch/hermes-agent and install via uv. Use this to track a specific branch or commit.
  • 'pip': Deprecated. PyPI installs are no longer officially supported upstream and will not receive further updates. Retained for backward compatibility only.

• install-pkgs | string

  Comma-separated list of extra packages to install. Supported: 'chrome', 'chromium', 'firefox', 'tailscale', 'homebrew'.

• line-channel-access-token | string

  LINE Messaging API channel access token. Leave empty to disable LINE messaging.

• line-channel-secret | string

  LINE Messaging API channel secret. Required when line-channel-access-token is configured.

• log-level | string

  Default: info

  Log level (debug, info, warn, error)

• manual | boolean

  Manual configuration mode. When enabled:

  • Charm will NOT auto-generate config.yaml or .env
  • User manages ~/.hermes/ configuration manually
  • Charm only installs Hermes Agent and manages the systemd service

• matrix-access-token | string

  Matrix access token for the bot account

• matrix-homeserver | string

  Matrix homeserver URL (e.g., https://matrix.org)

• matrix-user-id | string

  Matrix user ID (e.g., @bot:matrix.org)

• mattermost-token | string

  Mattermost bot token

• mattermost-url | string

  Mattermost server URL

• max-turns | int

  Default: 90

  Maximum agent turns per conversation before requiring reset

• node-version | string

  Default: 24

  Node.js major version to install (minimum 22 required)

• personality | string

  Agent personality preset (e.g., 'kawaii', 'professional', 'pirate'). Leave empty for default personality.

• signal-phone-number | string

  Signal phone number for Signal messaging. Leave empty to disable Signal messaging.

• slack-app-token | string

  Slack app token (xapp-...) from Slack App settings. Required when slack-bot-token is configured.

• slack-bot-token | string

  Slack bot token (xoxb-...) from Slack App settings. Leave empty to disable Slack messaging.

• soul-md | string

  Custom SOUL.md content — defines the agent's identity and personality. This overrides the default SOUL.md in ~/.hermes/. Multi-line YAML string supported.

• telegram-bot-token | string

  Telegram bot token from @BotFather. Leave empty to disable Telegram messaging.

• terminal-backend | string

  Default: local

  Terminal backend for shell commands:

  • 'local': run commands locally on the charm unit
  • 'docker': run in Docker containers
  • 'ssh': run on remote hosts via SSH

• version | string

  Default: latest

  Hermes Agent version to install.

  • 'latest' (default): tracks the latest main branch (script/git methods)
  • branch name: e.g. 'main', 'dev' — passed as --branch to install.sh
  • full 40-char commit SHA: pinned install — passed as --commit to install.sh
  • For pip method: PyPI version string (e.g., '2026.5.1')