Environment variables

Hermes reads environment variables from ~/.hermes/.env (loaded on startup) and from the shell environment. The .env file takes precedence over stale shell exports. Use hermes setup to configure variables interactively, or set them directly:

# View current .env path
hermes config env-path

# Set a value
hermes config set <KEY> <value>    # for config.yaml values

To edit the .env file directly:

hermes config edit  # opens config.yaml
# .env is at ~/.hermes/.env

HERMES_HOME overrides the base directory for all config files. Default is ~/.hermes. Set this before running any hermes command.

export HERMES_HOME=/opt/hermes-config

Provider API keys

At least one provider must be configured for Hermes to start. Run hermes setup to choose a provider interactively.

OPENROUTER_API_KEY

string

API key for OpenRouter. Provides access to 100+ models including Claude, GPT, Gemini, and open-source models. Also required for the vision_analyze and mixture_of_agents tools when using auxiliary providers.

ANTHROPIC_API_KEY

string

API key for direct Anthropic API access (Claude models). Alternative to using Anthropic via OpenRouter.

OPENAI_API_KEY

string

OpenAI API key. Used when OPENAI_BASE_URL is set (custom endpoint) or for direct OpenAI access.

OPENAI_BASE_URL

string

Base URL for any OpenAI-compatible endpoint (custom deployments, local models, proxies). When set alongside OPENAI_API_KEY, Hermes routes all requests to this endpoint.

GLM_API_KEY

string

API key for Z.AI / ZhipuAI GLM models (GLM-5, GLM-4.7, etc.). Also recognized as ZAI_API_KEY or Z_AI_API_KEY.

GLM_BASE_URL

string

Base URL override for the Z.AI / GLM API. Leave empty to use the default endpoint.

KIMI_API_KEY

string

API key for Kimi / Moonshot AI models. Keys prefixed with sk-kimi- use the Kimi Code API by default.

KIMI_BASE_URL

string

Base URL override for Kimi. Use https://api.kimi.com/coding/v1 for Kimi Code keys, https://api.moonshot.ai/v1 for legacy Moonshot keys.

MINIMAX_API_KEY

string

API key for MiniMax (international endpoint).

MINIMAX_CN_API_KEY

string

API key for MiniMax China (domestic endpoint).

DEEPSEEK_API_KEY

string

API key for direct DeepSeek access.

DASHSCOPE_API_KEY

string

API key for Alibaba Cloud DashScope (Qwen models).

OPENCODE_ZEN_API_KEY

string

API key for OpenCode Zen — pay-as-you-go access to curated models.

OPENCODE_GO_API_KEY

string

API key for OpenCode Go — $10/month subscription for open models (GLM-5, Kimi K2.5, MiniMax M2.5).

KILOCODE_API_KEY

string

API key for Kilo Code gateway — access to Claude, GPT, and Gemini models.

AI_GATEWAY_API_KEY

string

API key for AI Gateway by Vercel — 200+ models, pay-per-use.

COPILOT_GITHUB_TOKEN

string

GitHub token for GitHub Copilot access. Accepts OAuth tokens (gho_*), fine-grained PATs with Copilot Requests permission (github_pat_*), or GitHub App tokens (ghu_*). Classic PATs (ghp_*) are not supported. Set via hermes model → GitHub Copilot, or run copilot login.

HERMES_INFERENCE_PROVIDER

string

Override the inference provider at runtime without changing config.yaml. Accepted values: auto, openrouter, nous, openai-codex, copilot, anthropic, zai, kimi-coding, minimax, minimax-cn, kilocode, custom.

Tool API keys

PARALLEL_API_KEY

string

API key for Parallel — AI-native web search and content extraction. Powers the web_search and web_extract tools.

FIRECRAWL_API_KEY

string

API key for Firecrawl — web search and scraping. Powers web_search and web_extract.

FIRECRAWL_API_URL

string

URL for a self-hosted Firecrawl instance. Leave empty to use the Firecrawl cloud service.

TAVILY_API_KEY

string

API key for Tavily — AI-native web search, extract, and crawl. Powers web_search, web_extract, and web_crawl tools.

BROWSERBASE_API_KEY

string

API key for Browserbase cloud browser. Required for remote browser execution. Local browser automation works without this key.

BROWSERBASE_PROJECT_ID

string

Browserbase project ID from your dashboard. Required alongside BROWSERBASE_API_KEY for cloud browser sessions.

BROWSER_USE_API_KEY

string

API key for Browser Use cloud browser (alternative to Browserbase).

FAL_KEY

string

API key for FAL.ai — image generation. Required by the image_generate tool.

VOICE_TOOLS_OPENAI_KEY

string

OpenAI API key used exclusively for voice transcription (Whisper) and OpenAI TTS. Named separately to avoid interfering with the main inference provider. Get one at platform.openai.com/api-keys.

ELEVENLABS_API_KEY

string

API key for ElevenLabs premium text-to-speech voices.

HONCHO_API_KEY

string

API key for Honcho AI-native cross-session user memory. Required by the honcho_context, honcho_profile, honcho_search, and honcho_conclude tools. Also requires ~/.honcho/config.json.

GITHUB_TOKEN

string

GitHub personal access token for the Skills Hub (higher API rate limits) and skill publishing. Get one at github.com/settings/tokens.

TINKER_API_KEY

string

API key for Tinker — RL training service. Required by rl_start_training and related tools.

WANDB_API_KEY

string

Weights & Biases API key for experiment tracking. Used by rl_get_results and rl_check_status.

Messaging platforms

TELEGRAM_BOT_TOKEN

string

Telegram bot token obtained from @BotFather. Required to enable the Telegram gateway.

TELEGRAM_ALLOWED_USERS

string

Comma-separated Telegram user IDs allowed to interact with the bot. Get your ID from @userinfobot. Leave empty (with GATEWAY_ALLOW_ALL_USERS=true) for open access.

DISCORD_BOT_TOKEN

string

Discord bot token from the Developer Portal. Required to enable the Discord gateway.

DISCORD_ALLOWED_USERS

string

Comma-separated Discord user IDs allowed to use the bot.

SLACK_BOT_TOKEN

string

Slack bot token (xoxb-...) from your app’s OAuth & Permissions settings. Required scopes: chat:write, app_mentions:read, channels:history, groups:history, im:history, im:read, im:write, users:read, files:write.

SLACK_APP_TOKEN

string

Slack app-level token (xapp-...) for Socket Mode. Create in Basic Information → App-Level Tokens. Also requires Event Subscriptions: message.im, message.channels, message.groups, app_mention.

MATTERMOST_URL

string

Mattermost server URL, e.g. https://mm.example.com.

MATTERMOST_TOKEN

string

Mattermost bot token or personal access token.

MATTERMOST_ALLOWED_USERS

string

Comma-separated Mattermost user IDs allowed to use the bot.

MATRIX_HOMESERVER

string

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

MATRIX_ACCESS_TOKEN

string

Matrix access token (preferred over password login).

MATRIX_USER_ID

string

Matrix user ID in @user:server format.

MATRIX_ALLOWED_USERS

string

Comma-separated Matrix user IDs in @user:server format.

WHATSAPP_ENABLED

string

Set to true to enable the WhatsApp gateway. Use hermes whatsapp to pair via QR code.

WHATSAPP_ALLOWED_USERS

string

Comma-separated phone numbers (e.g. 15551234567) allowed to message the bot. Use * for anyone.

GATEWAY_ALLOW_ALL_USERS

string

default:"false"

Set to true to allow all users to interact with messaging bots without an allowlist. Use only for private deployments.

API_SERVER_ENABLED

string

default:"false"

Set to true to enable the OpenAI-compatible API server. Allows frontends like Open WebUI and LobeChat to connect.

API_SERVER_KEY

string

Bearer token for API server authentication. If empty, all requests are allowed (suitable for local use only).

API_SERVER_PORT

string

default:"8642"

Port for the API server.

API_SERVER_HOST

string

default:"127.0.0.1"

Host/bind address for the API server. Use 0.0.0.0 for network access — set API_SERVER_KEY for security.

Settings

MESSAGING_CWD

string

Working directory for terminal commands executed via messaging platforms. Defaults to the home directory. The CLI always uses the directory where hermes was launched.

SUDO_PASSWORD

string

Sudo password for terminal commands requiring root access. Piped via sudo -S. Works with all terminal backends.

Stored in plaintext. Use only on trusted machines. Consider passwordless sudo or running containers as root instead.

HERMES_MAX_ITERATIONS

string

default:"90"

Maximum tool-calling iterations per conversation. Overrides agent.max_turns in config.yaml.

HERMES_PREFILL_MESSAGES_FILE

string

Path to a JSON file containing ephemeral prefill messages for few-shot priming. The messages are injected at the start of every API call but never saved to sessions or logs.

HERMES_EPHEMERAL_SYSTEM_PROMPT

string

An ephemeral system prompt injected at API-call time. Never persisted to sessions.

CLI Reference

Toolsets

Provider API keys

Tool API keys

Messaging platforms

Settings

Build docs developers (and LLMs) love

CLI Reference

Toolsets

​Provider API keys

​Tool API keys

​Messaging platforms

​Settings

Build docs developers (and LLMs) love

Provider API keys

Tool API keys

Messaging platforms

Settings