Environment Variables Reference

Hermes reads environment variables from the process environment and, for user-managed secrets, from ~/.hermes/.env. Keep API keys, bot tokens, OAuth secrets, and other credentials in .env; prefer config.yaml for non-secret behaviour settings when a config key exists. Some variables below are process-only overrides or internal bridge variables and should not be committed to .env just because they are documented here.

LLM Providers

Variable	Description
OPENROUTER_API_KEY	OpenRouter API key (recommended for flexibility)
OPENROUTER_BASE_URL	Override the OpenRouter-compatible base URL
FIREWORKS_API_KEY	Fireworks AI API key (app.fireworks.ai). Configure endpoint overrides with model.base_url in config.yaml.
HERMES_OPENROUTER_CACHE	Enable OpenRouter response caching (1/true/yes/on). Overrides openrouter.response_cache in config.yaml. See Response Caching.
HERMES_OPENROUTER_CACHE_TTL	Cache TTL in seconds (1-86400). Overrides openrouter.response_cache_ttl in config.yaml.
NOUS_BASE_URL	Override Nous Portal base URL (rarely needed; development/testing only)
NOUS_INFERENCE_BASE_URL	Override Nous inference endpoint directly
AI_GATEWAY_API_KEY	Vercel AI Gateway API key (ai-gateway.vercel.sh)
AI_GATEWAY_BASE_URL	Override AI Gateway base URL (default: https://ai-gateway.vercel.sh/v1)
OPENAI_API_KEY	API key for custom OpenAI-compatible endpoints (used with OPENAI_BASE_URL)
OPENAI_BASE_URL	Base URL for custom endpoint (VLLM, SGLang, etc.)
LM_API_KEY	API key for LM Studio (lmstudio provider). Often a placeholder for local servers
LM_BASE_URL	LM Studio base URL (default: http://localhost:1234/v1)
COPILOT_GITHUB_TOKEN	GitHub token for Copilot API — first priority (OAuth gho_* or fine-grained PAT github_pat_*; classic PATs ghp_* are not supported)
GH_TOKEN	GitHub token — second priority for Copilot (also used by gh CLI)
GITHUB_TOKEN	GitHub token — third priority for Copilot
HERMES_COPILOT_ACP_COMMAND	Override Copilot ACP CLI binary path (default: copilot)
COPILOT_CLI_PATH	Alias for HERMES_COPILOT_ACP_COMMAND
HERMES_COPILOT_ACP_ARGS	Override Copilot ACP arguments (default: --acp --stdio)
COPILOT_ACP_BASE_URL	Override Copilot ACP base URL
COPILOT_API_BASE_URL	Override the Copilot API base URL (copilot provider)
GLM_API_KEY	z.ai / ZhipuAI GLM API key (z.ai)
ZAI_API_KEY	Alias for GLM_API_KEY
Z_AI_API_KEY	Alias for GLM_API_KEY
GLM_BASE_URL	Override z.ai base URL (default: https://api.z.ai/api/paas/v4)
KIMI_API_KEY	Kimi / Moonshot AI API key (moonshot.ai)
KIMI_CODING_API_KEY	Alias key for the kimi-coding provider (accepted alongside KIMI_API_KEY)
KIMI_BASE_URL	Override Kimi base URL (default: https://api.moonshot.ai/v1)
KIMI_CN_API_KEY	Kimi / Moonshot China API key (moonshot.cn)
ARCEEAI_API_KEY	Arcee AI API key (chat.arcee.ai)
ARCEE_BASE_URL	Override Arcee base URL (default: https://api.arcee.ai/api/v1)
GMI_API_KEY	GMI Cloud API key (gmicloud.ai)
GMI_BASE_URL	Override GMI Cloud base URL (default: https://api.gmi-serving.com/v1)
ACTUAL_API_KEY	Actual Computer inference key (ac_..., actual.inc/user/keys). Not needed for the local daemon.
ACTUAL_BASE_URL	Override Actual Computer base URL (default: https://api.actual.inc/v1). Set to http://127.0.0.1:8080 for the local offline daemon — loopback hosts need no API key.
MINIMAX_API_KEY	MiniMax API key — global endpoint (minimax.io). Not used by minimax-oauth (OAuth path uses browser login instead).
MINIMAX_BASE_URL	Override MiniMax base URL (default: https://api.minimax.io/anthropic — Hermes uses MiniMax's Anthropic Messages-compatible endpoint). Not used by minimax-oauth.
MINIMAX_CN_API_KEY	MiniMax API key — China endpoint (minimaxi.com). Not used by minimax-oauth (OAuth path uses browser login instead).
MINIMAX_CN_BASE_URL	Override MiniMax China base URL (default: https://api.minimaxi.com/anthropic). Not used by minimax-oauth.
KILOCODE_API_KEY	Kilo Code API key (kilo.ai)
KILOCODE_BASE_URL	Override Kilo Code base URL (default: https://api.kilo.ai/api/gateway)
XIAOMI_API_KEY	Xiaomi MiMo API key (platform.xiaomimimo.com)
XIAOMI_BASE_URL	Override Xiaomi MiMo base URL (default: https://api.xiaomimimo.com/v1)
UPSTAGE_API_KEY	Upstage API key for Solar models (console.upstage.ai)
UPSTAGE_BASE_URL	Override Upstage base URL (default: https://api.upstage.ai/v1)
TOKENHUB_API_KEY	Tencent TokenHub API key (tokenhub.tencentmaas.com)
TOKENHUB_BASE_URL	Override Tencent TokenHub base URL (default: https://tokenhub.tencentmaas.com/v1)
AZURE_FOUNDRY_API_KEY	Microsoft Foundry / Azure OpenAI API key (ai.azure.com). Not needed when model.auth_mode: entra_id
AZURE_FOUNDRY_BASE_URL	Microsoft Foundry endpoint URL (e.g. https://<resource>.openai.azure.com/openai/v1 for OpenAI-style, or https://<resource>.services.ai.azure.com/anthropic for Anthropic-style)
AZURE_ANTHROPIC_KEY	Azure Anthropic API key for provider: anthropic + base_url pointing at a Microsoft Foundry Claude deployment (alternative to ANTHROPIC_API_KEY when both Anthropic and Azure Anthropic are configured)
AZURE_TENANT_ID	Entra ID tenant ID (service-principal flows; honored by azure-identity when model.auth_mode: entra_id)
AZURE_CLIENT_ID	Entra ID client ID (service principal, workload identity, or user-assigned managed identity)
AZURE_CLIENT_SECRET	Service principal secret used by EnvironmentCredential
AZURE_CLIENT_CERTIFICATE_PATH	Service principal certificate (alternative to AZURE_CLIENT_SECRET)
AZURE_FEDERATED_TOKEN_FILE	Federated token file path for AKS Workload Identity / OIDC flows
AZURE_AUTHORITY_HOST	Sovereign-cloud authority override (e.g. https://login.microsoftonline.us for Azure Government). See Azure Foundry guide
IDENTITY_ENDPOINT / MSI_ENDPOINT	Managed Identity endpoint for App Service, Functions, and Container Apps; VMs usually use IMDS instead and do not set these
HF_TOKEN	Hugging Face token for Inference Providers (huggingface.co/settings/tokens)
HF_BASE_URL	Override Hugging Face base URL (default: https://router.huggingface.co/v1)
GOOGLE_API_KEY	Google AI Studio API key (aistudio.google.com/app/apikey)
GEMINI_API_KEY	Alias for GOOGLE_API_KEY
GEMINI_BASE_URL	Override Google AI Studio base URL
VERTEX_CREDENTIALS_PATH	Path to a Google Cloud service account JSON for Vertex AI (Gemini). Vertex uses OAuth2, not a static API key. Falls back to GOOGLE_APPLICATION_CREDENTIALS, then to ADC (gcloud auth application-default login). Set project/region under vertex: in config.yaml
ANTHROPIC_API_KEY	Anthropic Console API key (console.anthropic.com)
ANTHROPIC_BASE_URL	Override the Anthropic API base URL
ANTHROPIC_TOKEN	Manual or legacy Anthropic OAuth/setup-token override
DASHSCOPE_API_KEY	Qwen Cloud (Alibaba DashScope) API key for Qwen models (modelstudio.console.alibabacloud.com)
DASHSCOPE_BASE_URL	Custom DashScope base URL (default: https://dashscope-intl.aliyuncs.com/compatible-mode/v1; use https://dashscope.aliyuncs.com/compatible-mode/v1 for mainland-China region)
ALIBABA_CODING_PLAN_API_KEY	Qwen Coding Plan API key (alibaba-coding-plan provider)
ALIBABA_CODING_PLAN_BASE_URL	Override the Qwen Coding Plan base URL
DEEPSEEK_API_KEY	DeepSeek API key for direct DeepSeek access (platform.deepseek.com)
DEEPSEEK_BASE_URL	Custom DeepSeek API base URL
DEEPINFRA_API_KEY	DeepInfra API key (deepinfra.com)
DEEPINFRA_BASE_URL	DeepInfra base URL override
NOVITA_API_KEY	NovitaAI API key — AI-native cloud for Model API, Agent Sandbox, and GPU Cloud (novita.ai/settings/key-management)
NOVITA_BASE_URL	Override NovitaAI base URL (default: https://api.novita.ai/openai/v1)
NVIDIA_API_KEY	NVIDIA NIM API key — Nemotron and open models (build.nvidia.com)
NVIDIA_BASE_URL	Override NVIDIA base URL (default: https://integrate.api.nvidia.com/v1; set to http://localhost:8000/v1 for a local NIM endpoint)
STEPFUN_API_KEY	StepFun API key — Step-series models (platform.stepfun.com)
STEPFUN_BASE_URL	Override StepFun base URL (default: https://api.stepfun.com/v1)
OLLAMA_API_KEY	Ollama Cloud API key — managed Ollama catalog without local GPU (ollama.com/settings/keys)
OLLAMA_BASE_URL	Override Ollama Cloud base URL (default: https://ollama.com/v1)
XAI_API_KEY	xAI (Grok) API key for chat + TTS + web search (console.x.ai)
XAI_BASE_URL	Override xAI base URL (default: https://api.x.ai/v1)
MISTRAL_API_KEY	Mistral API key for Voxtral TTS and Voxtral STT (console.mistral.ai)
AWS_REGION	AWS region for Bedrock inference (e.g. us-east-1, eu-central-1). Read by boto3.
AWS_PROFILE	AWS named profile for Bedrock authentication (reads ~/.aws/credentials). Leave unset to use default boto3 credential chain.
BEDROCK_BASE_URL	Override Bedrock runtime base URL (default: https://bedrock-runtime.us-east-1.amazonaws.com; usually leave unset and use AWS_REGION instead)
HERMES_QWEN_BASE_URL	Qwen Portal base URL override (default: https://portal.qwen.ai/v1)
OPENCODE_ZEN_API_KEY	OpenCode Zen API key — pay-as-you-go access to curated models (opencode.ai)
OPENCODE_ZEN_BASE_URL	Override OpenCode Zen base URL
OPENCODE_GO_API_KEY	OpenCode Go API key — $10/month subscription for open models (opencode.ai)
OPENCODE_GO_BASE_URL	Override OpenCode Go base URL
CLAUDE_CODE_OAUTH_TOKEN	Explicit Claude Code token override if you export one manually
HERMES_MODEL	Override model name at process level (used by cron scheduler; prefer config.yaml for normal use)
VOICE_TOOLS_OPENAI_KEY	Preferred OpenAI key for OpenAI speech-to-text and text-to-speech providers
HERMES_LOCAL_STT_COMMAND	Optional local speech-to-text command template. Supports {input_path}, {output_dir}, {language}, and {model} placeholders
HERMES_LOCAL_STT_LANGUAGE	Default language hint for STT. Used by the local (faster-whisper) provider, HERMES_LOCAL_STT_COMMAND, the local whisper CLI fallback (default: en), Groq, and xAI when no per-provider language is set in config.yaml
HERMES_HOME	Override Hermes config directory (default: ~/.hermes). Also scopes the gateway PID file and systemd service name, so multiple installations can run concurrently
HERMES_GIT_BASH_PATH	Windows only. Override bash.exe discovery for the terminal tool. Points at any bash — full Git-for-Windows install, WSL bash via symlink, MSYS2, Cygwin. The installer sets this automatically to the PortableGit it provisioned. See the Windows (Native) Guide
HERMES_DISABLE_WINDOWS_UTF8	Windows only. Set to 1 to disable the UTF-8 stdio shim (configure_windows_stdio()) and fall back to the console's locale code page. Useful for bisecting encoding bugs; rarely the right setting in normal operation
HERMES_KANBAN_HOME	Override the shared Hermes root that anchors the kanban board (db + workspaces + worker logs). Falls back to get_default_hermes_root() (the parent of any active profile). Useful for tests and unusual deployments
HERMES_KANBAN_BOARD	Pin the active kanban board for this process. Takes precedence over ~/.hermes/kanban/current; the dispatcher injects this into worker subprocess env so workers physically cannot see tasks on other boards. Defaults to default. Slug validation: lowercase alphanumerics + hyphens + underscores, 1-64 chars
HERMES_KANBAN_DB	Pin the kanban database file path directly (highest precedence; beats HERMES_KANBAN_BOARD and HERMES_KANBAN_HOME). The dispatcher injects this into worker subprocess env so profile workers converge on the dispatcher's board
HERMES_KANBAN_WORKSPACES_ROOT	Pin the kanban workspaces root directly (highest precedence for workspaces; beats HERMES_KANBAN_HOME). The dispatcher injects this into worker subprocess env
HERMES_KANBAN_DISPATCH_IN_GATEWAY	Runtime override for kanban.dispatch_in_gateway. Set to 0, false, no, or off to keep the gateway from starting the embedded Kanban dispatcher; any other non-empty value enables it. Useful when a separate dispatcher process owns the board.

Provider Auth (OAuth)

For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. OAuth against Anthropic requires a Claude Max plan with purchased extra usage credits — Hermes routes as Claude Code, which only draws from the Max plan's extra/overage credits, not the base Max allowance, and does not work on Claude Pro. Without Max + extra credits, use an API key instead. Environment variables such as ANTHROPIC_TOKEN remain useful as manual overrides, but they are no longer the preferred path for Claude Max login.

Variable	Description
HERMES_PORTAL_BASE_URL	Override Nous Portal URL (for development/testing)
NOUS_INFERENCE_BASE_URL	Override Nous inference API URL
HERMES_NOUS_MIN_KEY_TTL_SECONDS	Min agent key TTL before re-mint (default: 1800 = 30min)
HERMES_NOUS_TIMEOUT_SECONDS	HTTP timeout for Nous credential / token flows
HERMES_DUMP_REQUESTS	Dump API request payloads to log files (true/false)
HERMES_PREFILL_MESSAGES_FILE	Path to a JSON file of ephemeral prefill messages injected at API-call time
HERMES_TIMEZONE	IANA timezone override (for example America/New_York)

Tool APIs

Variable	Description
PARALLEL_API_KEY	AI-native web search (parallel.ai)
FIRECRAWL_API_KEY	Web scraping and cloud browser (firecrawl.dev)
FIRECRAWL_API_URL	Custom Firecrawl API endpoint for self-hosted instances (optional)
TAVILY_API_KEY	Tavily API key for AI-native web search, extract, and crawl (app.tavily.com)
SEARXNG_URL	SearXNG instance URL for free self-hosted web search — no API key required (searxng.github.io)
TAVILY_BASE_URL	Override the Tavily API endpoint. Useful for corporate proxies and self-hosted Tavily-compatible search backends. Same pattern as GROQ_BASE_URL.
EXA_API_KEY	Exa API key for AI-native web search and contents (exa.ai)
BRAVE_SEARCH_API_KEY	Brave Search API subscription token for web search (free tier available) (brave.com/search/api)
BROWSERBASE_API_KEY	Browser automation (browserbase.com)
BROWSERBASE_PROJECT_ID	Browserbase project ID
BROWSER_USE_API_KEY	Browser Use cloud browser API key (browser-use.com)
FIRECRAWL_BROWSER_TTL	Firecrawl browser session TTL in seconds (default: 300)
BROWSER_CDP_URL	Chrome DevTools Protocol URL for local browser (set via /browser connect, e.g. ws://localhost:9222)
CAMOFOX_URL	Camofox local anti-detection browser URL (default: http://localhost:9377)
CAMOFOX_API_KEY	Optional bearer token sent as Authorization header to a remote/authenticated Camofox server
CAMOFOX_USER_ID	Optional externally managed Camofox user ID for shared visible sessions
CAMOFOX_SESSION_KEY	Optional Camofox session key used when creating tabs for CAMOFOX_USER_ID
CAMOFOX_ADOPT_EXISTING_TAB	Set to true to reuse an existing Camofox tab before creating a new one
BROWSER_INACTIVITY_TIMEOUT	Browser session inactivity timeout in seconds
AGENT_BROWSER_ARGS	Extra Chromium launch flags (comma- or newline-separated). Hermes auto-injects --no-sandbox,--disable-dev-shm-usage when running as root or on AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, many container images); set this manually only to override or add other flags.
AGENT_BROWSER_ENGINE	Browser engine for local mode: auto (default — Chromium-family via CDP), or a specific engine override.
FAL_KEY	Image generation (fal.ai)
KREA_API_KEY	Krea API key for Krea 2 image generation (krea.ai)
GROQ_API_KEY	Groq Whisper STT API key (groq.com)
ELEVENLABS_API_KEY	ElevenLabs premium TTS voices (elevenlabs.io)
PORCUPINE_ACCESS_KEY	Picovoice Porcupine wake-word engine (console.picovoice.ai) — only for wake_word.provider: porcupine; the default openWakeWord and sherpa engines need no key
STT_GROQ_MODEL	Override the Groq STT model (default: whisper-large-v3-turbo)
GROQ_BASE_URL	Override the Groq OpenAI-compatible STT endpoint
STT_OPENAI_MODEL	Override the OpenAI STT model (default: whisper-1)
STT_OPENAI_BASE_URL	Override the OpenAI-compatible STT endpoint
GITHUB_TOKEN	GitHub token for Skills Hub (higher API rate limits, skill publish)
HONCHO_API_KEY	Cross-session user modeling (honcho.dev)
HONCHO_BASE_URL	Base URL for self-hosted Honcho instances (default: Honcho cloud). No API key required for local instances
HINDSIGHT_API_KEY	Hindsight API key for graph-aware persistent memory (hindsight.vectorize.io)
HINDSIGHT_API_URL	Base URL for the Hindsight API (default: https://api.hindsight.vectorize.io)
HINDSIGHT_TIMEOUT	Timeout in seconds for Hindsight memory-provider API calls (default: 60). Bump this if your Hindsight instance is slow to respond during /sync or on_session_switch and you're seeing timeouts in errors.log.
MEM0_API_KEY	Mem0 Platform API key for semantic persistent memory (app.mem0.ai)
MEM0_MODE	Mem0 backend mode: platform (default) or oss — see Memory Providers
MEM0_HOST	Base URL of a self-hosted Mem0 server (switches the plugin off the Platform API)
MEM0_USER_ID	Override the user id Mem0 memories are stored under
MEM0_AGENT_ID	Override the agent id Mem0 memories are tagged with
RETAINDB_API_KEY	RetainDB API key for persistent memory (retaindb.com)
RETAINDB_BASE_URL	Base URL for self-hosted RetainDB instances (default: https://api.retaindb.com)
OPENVIKING_API_KEY	OpenViking API key (leave blank for local dev mode)
OPENVIKING_ENDPOINT	OpenViking server URL (default: http://127.0.0.1:1933)
BRV_API_KEY	ByteRover API key (optional, for cloud sync — local-first by default) (app.byterover.dev)
SUPERMEMORY_API_KEY	Semantic long-term memory with profile recall and session ingest (supermemory.ai)
DAYTONA_API_KEY	Daytona cloud sandboxes (daytona.io)
VERCEL_TOKEN	Vercel Sandbox access token (vercel.com)
VERCEL_PROJECT_ID	Vercel project ID (required with VERCEL_TOKEN)
VERCEL_TEAM_ID	Vercel team ID (required with VERCEL_TOKEN)
VERCEL_OIDC_TOKEN	Vercel short-lived OIDC token (development-only alternative)

Skill API Keys

Secrets consumed by specific bundled / optional skills. Each is only needed if you use the corresponding skill.

Variable	Used by skill	Description
NOTION_API_KEY	notion	Notion integration token.
LINEAR_API_KEY	linear	Linear personal API key.
AIRTABLE_API_KEY	airtable	Airtable personal access token.
TENOR_API_KEY	gif-search	Tenor API key for GIF search.

Langfuse Observability

Environment variables for the bundled observability/langfuse plugin. Set these in ~/.hermes/.env. The plugin must also be enabled (hermes plugins enable observability/langfuse, or check the box in hermes plugins) before any of these take effect.

Variable	Description
HERMES_LANGFUSE_PUBLIC_KEY	Langfuse project public key (pk-lf-...). Required.
HERMES_LANGFUSE_SECRET_KEY	Langfuse project secret key (sk-lf-...). Required.
HERMES_LANGFUSE_BASE_URL	Langfuse server URL (default: https://cloud.langfuse.com). Set for self-hosted.
HERMES_LANGFUSE_ENV	Environment tag on traces (production, staging, …)
HERMES_LANGFUSE_RELEASE	Release/version tag on traces
HERMES_LANGFUSE_SAMPLE_RATE	SDK sampling rate 0.0–1.0 (default: 1.0)
HERMES_LANGFUSE_MAX_CHARS	Per-field truncation for serialized payloads (default: 12000)
HERMES_LANGFUSE_DEBUG	true enables verbose plugin logging to agent.log
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL	Standard Langfuse SDK names. Accepted as fallbacks when the HERMES_LANGFUSE_* equivalents are unset.

Nous Tool Gateway

These variables configure the Tool Gateway for paid Nous subscribers or self-hosted gateway deployments. Most users don't need to set these — the gateway is configured automatically via hermes model or hermes tools.

Variable	Description
TOOL_GATEWAY_DOMAIN	Base domain for Tool Gateway routing (default: nousresearch.com)
TOOL_GATEWAY_SCHEME	HTTP or HTTPS scheme for gateway URLs (default: https)
TOOL_GATEWAY_USER_TOKEN	Auth token for the Tool Gateway (normally auto-populated from Nous auth)
FIRECRAWL_GATEWAY_URL	Override URL for the Firecrawl gateway endpoint specifically

Terminal Backend

Variable	Description
TERMINAL_ENV	Backend: local, docker, ssh, singularity, modal, daytona, vercel_sandbox
HERMES_DOCKER_BINARY	Override the container binary Hermes shells out to (e.g. podman, /usr/local/bin/docker). When unset, Hermes auto-discovers docker or podman on PATH. Needed when both are installed and you want the non-default, or when the binary lives outside PATH.
TERMINAL_DOCKER_IMAGE	Docker image (default: nikolaik/python-nodejs:python3.11-nodejs20)
TERMINAL_DOCKER_FORWARD_ENV	JSON array of env var names to explicitly forward into Docker terminal sessions. Note: skill-declared required_environment_variables are forwarded automatically — you only need this for vars not declared by any skill.
TERMINAL_DOCKER_VOLUMES	Additional Docker volume mounts (comma-separated host:container pairs)
TERMINAL_DOCKER_ENV