config.yaml

options:
  gateway-port:
    type: int
    default: 3000
    description: Port for the Hermes Agent Gateway HTTP/WebSocket server

  install-method:
    type: string
    default: script
    description: |
      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.

  version:
    type: string
    default: latest
    description: |
      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')

  auto-update:
    type: boolean
    default: false
    description: Automatically update Hermes Agent to latest version on upgrade-charm

  node-version:
    type: string
    default: "24"
    description: Node.js major version to install (minimum 22 required)

  ai-provider:
    type: string
    default: ""
    description: |
      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

  ai-model:
    type: string
    default: ""
    description: |
      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-api-key:
    type: string
    default: ""
    description: |
      API key for the selected AI provider. Required for most providers.
      Not required for: ollama (local), bedrock (AWS credentials), nous (OAuth).

  ai-base-url:
    type: string
    default: ""
    description: |
      Custom API base URL for OpenAI-compatible providers.
      Examples: http://localhost:1234/v1 (LM Studio), http://localhost:8000/v1 (vLLM)


  ai-fallback-models:
    type: string
    default: ""
    description: |
      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"

  telegram-bot-token:
    type: string
    default: ""
    description: |
      Telegram bot token from @BotFather.
      Leave empty to disable Telegram messaging.

  discord-bot-token:
    type: string
    default: ""
    description: |
      Discord bot token from Discord Developer Portal.
      Leave empty to disable Discord messaging.

  slack-bot-token:
    type: string
    default: ""
    description: |
      Slack bot token (xoxb-...) from Slack App settings.
      Leave empty to disable Slack messaging.

  slack-app-token:
    type: string
    default: ""
    description: |
      Slack app token (xapp-...) from Slack App settings.
      Required when slack-bot-token is configured.

  signal-phone-number:
    type: string
    default: ""
    description: |
      Signal phone number for Signal messaging.
      Leave empty to disable Signal messaging.

  line-channel-access-token:
    type: string
    default: ""
    description: |
      LINE Messaging API channel access token.
      Leave empty to disable LINE messaging.

  line-channel-secret:
    type: string
    default: ""
    description: |
      LINE Messaging API channel secret.
      Required when line-channel-access-token is configured.

  dm-policy:
    type: string
    default: pairing
    description: |
      DM access policy: 'pairing' (require pairing code), 'open' (auto-respond),
      or 'closed' (reject all DMs)

  log-level:
    type: string
    default: info
    description: Log level (debug, info, warn, error)

  manual:
    type: boolean
    default: false
    description: |
      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

  install-pkgs:
    type: string
    default: ""
    description: |
      Comma-separated list of extra packages to install.
      Supported: 'chrome', 'chromium', 'firefox', 'tailscale', 'homebrew'.

  personality:
    type: string
    default: ""
    description: |
      Agent personality preset (e.g., 'kawaii', 'professional', 'pirate').
      Leave empty for default personality.

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

  terminal-backend:
    type: string
    default: local
    description: |
      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

  compression-enabled:
    type: boolean
    default: true
    description: Enable context compression when conversation grows long

  max-turns:
    type: int
    default: 90
    description: Maximum agent turns per conversation before requiring reset

  gateway-allow-all-users:
    type: boolean
    default: false
    description: |
      Allow all users to interact without pairing.
      WARNING: Only set to true in trusted environments.
      When false, users must pair via DM code first.

  home-assistant-url:
    type: string
    default: ""
    description: |
      Home Assistant URL for HA integration (e.g., http://homeassistant.local:8123).
      Leave empty to disable.

  home-assistant-token:
    type: string
    default: ""
    description: |
      Long-lived access token for Home Assistant API.
      Required when home-assistant-url is configured.

  matrix-homeserver:
    type: string
    default: ""
    description: Matrix homeserver URL (e.g., https://matrix.org)

  matrix-user-id:
    type: string
    default: ""
    description: Matrix user ID (e.g., @bot:matrix.org)

  matrix-access-token:
    type: string
    default: ""
    description: Matrix access token for the bot account

  mattermost-url:
    type: string
    default: ""
    description: Mattermost server URL

  mattermost-token:
    type: string
    default: ""
    description: Mattermost bot token

  dashboard-port:
    type: int
    default: 9119
    description: Port for the Hermes Dashboard web UI

  dashboard-username:
    type: string
    default: ""
    description: |
      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.

  dashboard-password:
    type: string
    default: ""
    description: |
      Password for dashboard basic auth. The charm hashes this automatically
      using scrypt before writing to config.yaml. Required when dashboard-username
      is set.