# Hermes Agent CLI Configuration

# Copy settings from this example into ~/.hermes/config.yaml, or use

# `hermes config set <section.key> <value>` to update the active profile.

# This file configures CLI behavior; only documented secret environment

# variables in .env take precedence over their corresponding settings.

# Schema version of this file. The installers copy it to seed config.yaml, and

# `hermes update` uses it to know which one-time migrations the file already

# has. Hermes manages it: do not copy it into another config.

_config_version: 52

# =============================================================================

# Database Configuration

# =============================================================================

# WAL is the normal default. Hermes automatically falls back to DELETE when

# SQLite reports that WAL is incompatible with the filesystem. Set this to

# "delete" explicitly for deployments whose backing filesystem is not WAL

# crash-safe, such as Linux containers bind-mounted through macOS virtiofs,

# NFS, or SMB. Hermes will not live-downgrade a database already open in WAL.

database:

journal_mode: "wal" # Supported values: "wal", "delete"

# Optional WAL sizing pragmas (integers). Unset = SQLite defaults.

# wal_autocheckpoint: 1000 # pages between automatic checkpoints

# journal_size_limit: 67108864 # cap the WAL/journal file size in bytes

#

# Durability level for every state.db connection: OFF, NORMAL, FULL, EXTRA

# (or 0-3). Unset leaves SQLite's default, which is baked in at compile time

# (SQLITE_DEFAULT_WAL_SYNCHRONOUS) and therefore differs between the bundled

# interpreter, a distro python3 and a Homebrew one. Set it if you need to

# know which one you are running rather than infer it. On macOS this is a

# floor, not a pin: values below FULL are refused because Darwin's fsync()

# does not guarantee write ordering, while EXTRA is honored normally.

# synchronous: FULL

# =============================================================================

# Runtime Limits

# =============================================================================

# Long-running Hermes server processes raise their RLIMIT_NOFILE soft limit to

# this value when the operating system permits it. The value is clamped to the

# hard limit and never lowers an already higher soft limit. Set to 0, false, or

# null to disable the adjustment. Default: 4096.

runtime:

nofile_soft_limit: 4096

# =============================================================================

# Attachments

# =============================================================================

# Where the TUI/Desktop gateway stages session file attachments (file uploads and

# pasted text). Read per profile: a session bound to profile X follows X's own

# config.yaml, so each agent's attachments stay with its workspace.

# hermes-home (default) <profile home>/attachments — the directory container

# backends bind-mount, so @file: refs resolve inside the sandbox.

# workspace <session workspace>/.hermes/attachments — staging lands inside

# the allowed reference root, so the profile's agent can always

# read its own attachments back. A remote (ssh) workspace keeps

# the profile home directory either way.

attachments:

storage: "hermes-home"

# =============================================================================

# Plugin Installation

# =============================================================================

plugins:

# Deadline for each Git clone, fetch or checkout during plugin install. Default: 300

# seconds. Subdirectory installs download only that folder.

# Raise this for large repositories or slow connections. Maximum: 3600.

clone_timeout_seconds: 300

# =============================================================================

# Model Configuration

# =============================================================================

model:

# Default model to use (can be overridden with --model flag)

# Both "default" and "model" work as the key name here.

default: "anthropic/claude-opus-4.6"

# Inference provider selection:

# "auto" - Auto-detect from credentials (default)

# "openrouter" - OpenRouter (requires: OPENROUTER_API_KEY or OPENAI_API_KEY)

# "nous" - Nous Portal OAuth (requires: hermes auth add nous)

# "nous-api" - Nous Portal API key (requires: NOUS_API_KEY)

# "anthropic" - Direct Anthropic API (requires: ANTHROPIC_API_KEY)

# "openai-codex" - OpenAI Codex (requires: hermes auth)

# "gemini" - Use Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)

# "zai" - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)

# "kimi-coding" - Kimi / Moonshot AI (requires: KIMI_API_KEY)

# "minimax" - MiniMax global (requires: MINIMAX_API_KEY)

# "minimax-cn" - MiniMax China (requires: MINIMAX_CN_API_KEY)

# "huggingface" - Hugging Face Inference (requires: HF_TOKEN)

# "nvidia" - NVIDIA NIM / build.nvidia.com (requires: NVIDIA_API_KEY)

# "xiaomi" - Xiaomi MiMo (requires: XIAOMI_API_KEY)

# "arcee" - Arcee AI Trinity models (requires: ARCEEAI_API_KEY)

# "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY — https://ollama.com/settings)

# "deepinfra" - DeepInfra (requires: DEEPINFRA_API_KEY)

# "kilocode" - KiloCode gateway (requires: KILOCODE_API_KEY)

# "ai-gateway" - Vercel AI Gateway (requires: AI_GATEWAY_API_KEY)

# "azure-foundry" - Microsoft Foundry / Azure OpenAI (API key or Entra ID)

# "lmstudio" - LM Studio local server (optional: LM_API_KEY, defaults to http://127.0.0.1:1234/v1)

#

# Local servers (LM Studio, Ollama, vLLM, llama.cpp):

# "custom" - Any other OpenAI-compatible endpoint. Set base_url below.

# Aliases: "ollama", "vllm", "llamacpp" all map to "custom".

# LM Studio is first-class and uses provider: "lmstudio".

# It works with both no-auth and auth-enabled server modes.

#

# Can also be overridden for a single invocation with the --provider flag.

provider: "auto"

# API configuration (falls back to OPENROUTER_API_KEY env var)

# api_key: "your-key-here" # Uncomment to set here instead of .env

base_url: "https://openrouter.ai/api/v1"

# Stream API responses from the provider (default: true). The agent core

# prefers streaming for every turn — subagents included — for liveness

# health-checking. Set false to force non-streaming requests for the whole

# session (persists across mid-session model switches). Escape hatch for

# self-hosted OpenAI-compatible servers whose streaming tool-call path is

# broken (e.g. vLLM with --tool-call-parser qwen3_xml + a reasoning parser

# can leak tool calls into plain text instead of returning tool_calls —

# #72901). Orthogonal to display.streaming, which controls token rendering

# only.

# streaming: true

# Azure Foundry keyless auth example:

# provider: "azure-foundry"

# base_url: "https://<resource>.openai.azure.com/openai/v1"

# auth_mode: "entra_id" # DefaultAzureCredential: az login, managed identity, workload identity, etc.

# default: "gpt-4o" # Deployment/model name

# entra:

# scope: "https://ai.azure.com/.default" # Optional; this is the default.

# ── Token limits — two settings, easy to confuse ──────────────────────────

#

# context_length: TOTAL context window (input + output tokens combined).

# Controls when Hermes compresses history and validates requests.

# Leave unset — Hermes auto-detects the correct value from the provider.

# Set manually only when auto-detection is wrong (e.g. a local server with

# a custom num_ctx, or a proxy that doesn't expose /v1/models).

#

# context_length: 131072

#

# ollama_num_ctx: Ollama only — the num_ctx sent on every chat request.

# Hermes auto-detects the model's window and sends it (Ollama otherwise

# defaults to 2048); context_length, if set, caps the detected value.

# An explicit ollama_num_ctx is sent as-is (never capped) — set it to

# pin VRAM use.

#

# ollama_num_ctx: 32768

#

# Output-token limits are provider-owned, not user configuration. Native

# protocols requiring a limit receive an internal value from Hermes.

# ── Custom request headers (optional) ─────────────────────────────────────

#

# default_headers: extra HTTP headers sent on every request to an

# OpenAI-compatible endpoint. User values take precedence over the

# provider/SDK defaults, so this is the supported way to override the

# OpenAI Python SDK's identifying headers (User-Agent: OpenAI/Python ...,

# X-Stainless-*) when a custom provider sits behind a gateway/WAF that

# rejects them — e.g. an upstream that returns "502 Upstream access

# forbidden" for the SDK default User-Agent but accepts a plain one.

# Applies on the OpenAI wire only (not native Anthropic / Bedrock).

#

# default_headers:

# User-Agent: "curl/8.7.1"

#

# extra_headers: accepted as an alias of default_headers (merged, with

# extra_headers winning when both are set) — matches the per-provider

# extra_headers key below.

#

# Per-provider variant: named providers / custom_providers entries accept an

# extra_headers dict scoped to that endpoint only — for reverse proxies,

# gateways, or custom auth (e.g. Cloudflare Access service tokens).

# Merged onto SDK/provider defaults with the entry's values winning.

# Header values are treated as secrets and are never logged.

#

# providers:

# my-proxy:

# base_url: "https://llm.internal.example.com/v1"

# key_env: "MY_PROXY_API_KEY"

# extra_headers:

# CF-Access-Client-Id: "xxxx.access"

# CF-Access-Client-Secret: "${CF_ACCESS_SECRET}"

# X-Client-Name: "hermes-agent"

#

# session_affinity_header: NAME of a header that carries Hermes' conversation

# id on every request to that provider (all api_modes + auxiliary calls). Off

# unless set. For session-aware proxies that otherwise treat each agent-loop

# request as a new conversation and replay the whole history upstream.

#

# providers:

# my-proxy:

# base_url: "http://127.0.0.1:4000/v1"

# session_affinity_header: x-litellm-session-id

# providers:

# meta:

# base_url: https://api.meta.ai/v1

# api_key: ${MODEL_API_KEY}

# # api_mode auto-detected as codex_responses for api.meta.ai; no need to set

# # (the bundled meta-ai provider covers this — a named custom provider is

# # only needed for a non-default Meta-compatible endpoint)

# Fast/priority tier behind an OpenAI-compatible gateway or proxy: agent.service_tier

# (`/fast`) only reaches first-party endpoints; ask a gateway for its own tier via

# extra_body, which is merged into every request routed to that provider.

# providers:

# my-gateway:

# base_url: https://gateway.example.com/v1

# api_key: ${MY_GATEWAY_KEY}

# extra_body:

# service_tier: priority # whatever tier value your gateway documents

# providers:

# router:

# base_url: https://api.router.com/v1

# api_key: ${RAMP_ROUTER_API_KEY}

# # api_mode auto-detected as codex_responses for api.router.com — the

# # Responses API is Router's native wire (chat/completions is only a

# # compatibility shim). The bundled router provider covers this; a named

# # custom provider is only needed for a non-default Router-compatible

# # endpoint.

# Command-minted credentials (optional): key_cmd

# ------------------------------------------------------------------

# Enterprise gateways often issue SHORT-LIVED bearers (SSO/OIDC brokers, cloud

# IAM, internal auth proxies) rather than static API keys, so a value copied

# into .env via `key_env` is stale within the hour and every later request 401s.

# `key_cmd` names a command that PRINTS a token instead: Hermes runs it per

# request (cached until shortly before expiry), so long sessions keep working

# with no restart.

#

# Contract: print ONLY the token on stdout, either bare or as JSON with an

# "access_token" field ("expires_in" is honoured). Same shape as OAuth 2.0

# token endpoints, Claude Code's `apiKeyHelper`, `gcloud auth

# print-access-token`, and `aws ecr get-login-password`.

#

# Precedence: an explicit --api-key still wins; otherwise key_cmd is preferred

# over inline api_key / key_env on that entry.

#

# Applies to the main agent turn and to auxiliary tasks (title generation,

# context compression, vision, embedding) alike.

#

# Not to be confused with `secrets.command`, which is a different mechanism:

# that one runs a helper ONCE at startup to populate env vars for many secrets

# at the process level. Use it for a vault or keychain helper that hands back a

# KEY=VALUE blob. Use `key_cmd` when ONE provider needs a credential refreshed

# DURING a session, because a startup-time env var cannot be re-minted after it

# expires.

#

# providers:

# my-gateway:

# base_url: "https://gateway.internal.example.com/v1"

# api_mode: chat_completions

# key_cmd: "my-auth-cli print-token --profile prod"

#

# Worked example — an AI gateway that routes by model family, so one entry per

# wire format shares the same credential helper:

#

# providers:

# dbx: # OpenAI-compatible (MLflow) route

# base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/mlflow/v1"

# api_mode: chat_completions

# model: databricks-claude-sonnet-4-6

# key_cmd: "databricks auth token -p MY-PROFILE"

# dbx-gpt: # OpenAI Responses route

# base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/openai/v1"

# api_mode: codex_responses

# model: databricks-gpt-5-5

# key_cmd: "databricks auth token -p MY-PROFILE"

# dbx-claude: # Anthropic Messages route

# base_url: "https://<workspace>.cloud.databricks.com/ai-gateway/anthropic"

# api_mode: anthropic_messages

# model: databricks-claude-fable-5

# key_cmd: "databricks auth token -p MY-PROFILE"

# Named provider overrides (optional)

# Use this for per-provider request timeouts, non-stream stale timeouts,

# and per-model exceptions.

# Applies to the primary turn client on every api_mode (OpenAI-wire, native

# Anthropic, and Anthropic-compatible providers), the fallback chain, and

# client rebuilds during credential rotation. For OpenAI-wire chat

# completions (streaming and non-streaming) the configured value is also

# used as the per-request ``timeout=`` kwarg so it wins over the legacy

# HERMES_API_TIMEOUT env var (which still applies when no config is set).

# ``stale_timeout_seconds`` controls the non-streaming stale-call detector and

# wins over the legacy HERMES_API_CALL_STALE_TIMEOUT env var. Leaving these

# unset keeps the legacy defaults (HERMES_API_TIMEOUT=1800s,

# HERMES_API_CALL_STALE_TIMEOUT=90s, native Anthropic 900s). The

# implicit non-stream stale detector is auto-disabled for local endpoints

# and can scale upward for very large contexts.

#

# Not currently wired for AWS Bedrock (bedrock_converse + AnthropicBedrock

# SDK paths) — those use boto3 with its own timeout configuration.

#

# providers:

# ollama-local:

# request_timeout_seconds: 300 # Longer timeout for local cold-starts

# stale_timeout_seconds: 900 # Explicitly re-enable stale detection on local endpoints

# anthropic:

# request_timeout_seconds: 30 # Fast-fail cloud requests

# models:

# claude-opus-4.6:

# timeout_seconds: 600 # Longer timeout for extended-thinking Opus calls

# openai-codex:

# models:

# gpt-5.4:

# stale_timeout_seconds: 1800 # Longer non-stream stale timeout for slow large-context turns

# =============================================================================

# Unified Timeouts (operation deadlines)

# =============================================================================

# One place to override Hermes's internal operation deadlines (seconds).

# Keys are dotted paths resolved by agent/deadline.py:resolve_timeout().

# Precedence: this section > legacy HERMES_* env var (back-compat) > built-in

# default. 0 or a negative value disables the bound (unbounded); very large

# values are clamped to a platform-safe maximum automatically.

#

# Currently resolved keys (more paths migrate here over time — see issue #85125):

#

# timeouts:

# tools:

# concurrent_batch: 420 # Deadline for a parallel tool-call batch

# # (legacy env: HERMES_CONCURRENT_TOOL_TIMEOUT_S)

# sequential_call: 420 # Deadline for one sequentially-executed tool call.

# # Defaults to concurrent_batch's value so the two

# # executor paths stay in sync; human waits

# # (approval prompts, clarify) never count against it.

# =============================================================================

# OpenRouter Provider Routing (only applies when using OpenRouter)

# =============================================================================

# Control how requests are routed across providers on OpenRouter.

# See: https://openrouter.ai/docs/guides/routing/provider-selection

#

# provider_routing:

# # Sort strategy: "price" (default), "throughput", or "latency"

# # Append :nitro to model name for a shortcut to throughput sorting.

# sort: "throughput"

#

# # Only allow these providers (provider slugs from OpenRouter)

# # only: ["anthropic", "google"]

#

# # Skip these providers entirely

# # ignore: ["deepinfra", "fireworks"]

#

# # Try providers in this order (overrides default load balancing)

# # order: ["anthropic", "google", "together"]

#

# # Require providers to support all parameters in your request

# # require_parameters: true

#

# # Data policy: "allow" (default) or "deny" to exclude providers that may store data

# # data_collection: "deny"

#

# # Per-model overrides: same keys, applied only when the agent is on that model

# # (spelling-tolerant match; unset keys fall through to the flat values above).

# # models:

# # "openai/gpt-6-astra":

# # only: ["openai"]

# # "anthropic/claude-fable-5.1":

# # only: ["anthropic"]

# =============================================================================

# OpenRouter Response Caching (only applies when using OpenRouter)

# =============================================================================

# Cache identical API responses at the OpenRouter edge for free instant replays.

# When enabled, identical requests (same model, messages, parameters) return

# cached responses with zero billing. Separate from Anthropic prompt caching.

# See: https://openrouter.ai/docs/guides/features/response-caching

#

# openrouter:

# response_cache: true # Enable response caching (default: true)

# response_cache_ttl: 300 # Cache TTL in seconds, 1-86400 (default: 300)

# =============================================================================

# Git Worktree Isolation

# =============================================================================

# When enabled, each CLI session creates an isolated git worktree so multiple

# agents can work on the same repo concurrently without file collisions.

# Equivalent to always passing --worktree / -w on the command line.

#

# worktree: true # Always create a worktree when in a git repo

# worktree: false # Default — only create when -w flag is passed

#

# By default a new worktree branches from the freshly-fetched remote tip

# (the current branch's upstream, else the remote's default branch) so it

# starts current with the project instead of from the local clone's

# (possibly stale) HEAD. Set worktree_sync: false to branch from local HEAD

# instead — useful when offline or when you deliberately want the clone's

# exact current state as the base.

#

# worktree_sync: true # Default — branch from the fetched remote tip

# worktree_sync: false # Branch from local HEAD (offline / pinned base)

# Stale worktree sweep (startup of `hermes -w` + every 6h from the cron ticker, over

# every repo Hermes created a worktree in). Idle dirty/unpushed trees are archived to

# refs/hermes/archive/<tree> and removed; `hermes worktree restore <name>` brings one back.

# worktrees:

# archive_dirty: true # false = never remove dirty/unpushed trees (old behaviour)

# archive_max_file_mb: 50 # untracked files above this are not archived; their tree is kept

# archive_retention_days: 30 # archive refs older than this are deleted (0 = keep)

# max_total_gb: 0 # optional budget for idle trees; oldest evicted first

# =============================================================================

# Kanban Review Dispatch

# =============================================================================

# First-class review tasks are dispatched automatically by default. The worker

# is spawned with the bundled sdlc-review skill and can approve, request changes

# back to the original implementer, or escalate a genuine external blocker.

# Disable this only when every review is performed manually from the dashboard.

kanban:

review_dispatch: true

# =============================================================================

# Terminal Tool Configuration

# =============================================================================

# Choose ONE of the following terminal configurations by uncommenting it.

# The terminal tool executes commands in the specified environment.

# -----------------------------------------------------------------------------

# OPTION 1: Local execution (default)

# Commands run directly on your machine in the current directory

# -----------------------------------------------------------------------------

# Working directory behavior:

# - CLI (`hermes` command): Uses "." (current directory where you run hermes)

# - Gateway/messaging/cron: Uses terminal.cwd here; legacy .env cwd values are deprecated

cron:

catch_up_missed: true # False skips past-grace recurring misses after planned downtime.

terminal:

backend: "local"

cwd: "." # For local backend: "." = current directory. Ignored for remote backends unless a backend documents otherwise.

# Desktop xterm font. Install the font locally; Nerd Fonts render Powerlevel10k glyphs.

# font_family: "MesloLGS NF" # Also accepts a CSS stack; blank uses bundled JetBrains Mono.

timeout: 180

# HOME policy for tool subprocesses:

# auto - default: host uses your real HOME; containers use HERMES_HOME/home

# real - force your real OS-user HOME

# profile - force HERMES_HOME/home for strict per-profile CLI config isolation

home_mode: "auto"

docker_mount_cwd_to_workspace: false # SECURITY: off by default. Opt in to mount the launch cwd into Docker /workspace.

lifetime_seconds: 300

# Two process_manage wait/poll calls in a row with no new output on a running background process

# turn on notify_on_complete for it and tell the agent to stop checking; false = poll as before.

process_wait_auto_notify: true

# A `hermes` / `hermes --tui` session's local tools (terminal, background processes, execute_code)

# start with the launching shell's toolchain: PATH, an activated venv and CONDA_* / NODE_* / NVM_* /

# PYENV_* (plus GOPATH, GOROOT, CARGO_HOME, RUSTUP_HOME, JAVA_HOME), for that session only, when

# the client runs on the gateway's host (a remote client's session keeps the gateway's toolchain).

# As in the classic CLI, the venv reaches `terminal` through PATH (`which python`): VIRTUAL_ENV and

# CONDA_PREFIX themselves are unset there; execute_code sees them.

# A toolchain name the client did not export is unset for its session's tools (PATH excepted).

# List more non-secret names here (default: none); names execute_code treats as credentials (…TOKEN,

# …KEY, …SECRET, …PASSWORD, …AUTH, …DSN, …WEBHOOK, …CREDS, …BEARER, …COOKIE) and HERMES_* names

# are never sent: pass secrets with `env_passthrough` instead.

client_env_passthrough: [] # e.g. ["GEM_HOME", "POETRY_HOME"]

# sudo_password: "hunter2" # Optional: pipe a sudo password via sudo -S. SECURITY WARNING: plaintext.

# sudo_password: "" # Explicit empty password: try empty and never open the interactive sudo prompt.

# -----------------------------------------------------------------------------

# OPTION 2: SSH remote execution

# Commands run on a remote server - agent code stays local (sandboxed)

# Great for: keeping agent isolated from its own code, using powerful remote hardware

# -----------------------------------------------------------------------------

# terminal:

# backend: "ssh"

# cwd: "/home/myuser/project" # Path on the REMOTE server

# timeout: 180

# lifetime_seconds: 300

# ssh_host: "my-server.example.com"

# ssh_user: "myuser"

# ssh_port: 22

# ssh_key: "~/.ssh/id_rsa" # Optional - uses ssh-agent if not specified

# -----------------------------------------------------------------------------

# OPTION 3: Docker container

# Commands run in an isolated Docker container

# Great for: reproducible environments, testing, isolation

# -----------------------------------------------------------------------------

# terminal:

# backend: "docker"

# cwd: "/workspace" # Path INSIDE the container (default: /)

# timeout: 180

# lifetime_seconds: 300

# docker_image: "nousresearch/hermes-sandbox:desktop"

# docker_mount_cwd_to_workspace: true # Explicit opt-in: mount your launch cwd into /workspace

# # Optional: run the container as your host user's uid:gid so files written

# # into bind-mounted dirs are owned by you, not root. Drops SETUID/SETGID

# # caps too since no gosu privilege drop is needed. Leave off if your

# # chosen docker_image expects to start as root.

# docker_run_as_host_user: true

# # Optional: explicitly forward selected env vars into Docker.

# # These values come from your current shell first, then ~/.hermes/.env.

# # Warning: anything forwarded here is visible to commands run in the container.

# docker_forward_env:

# - "GITHUB_TOKEN"

# - "NPM_TOKEN"

# # Optional: extra flags passed verbatim to docker run (appended after security defaults).

# # Useful for adding capabilities (e.g. apt installs needing SETUID) or custom options.

# # Example: add a Linux capability not included by default

# # docker_extra_args:

# # - "--cap-add"

# # - "SETUID"

# -----------------------------------------------------------------------------

# OPTION 4: Singularity/Apptainer container (the official `singularity` plugin)

# Commands run in a Singularity container (common in HPC environments)

# Great for: HPC clusters, shared compute environments

# Install it first: hermes plugins install singularity

# -----------------------------------------------------------------------------

# terminal:

# backend: "singularity"

# cwd: "/workspace" # Path INSIDE the container (default: /root)

# timeout: 180

# lifetime_seconds: 300

# singularity_image: "docker://nousresearch/hermes-sandbox:desktop"

# -----------------------------------------------------------------------------

# OPTION 5: Modal cloud execution

# Commands run on Modal's cloud infrastructure

# Great for: GPU access, scalable compute, serverless execution

# -----------------------------------------------------------------------------

# terminal:

# backend: "modal"

# cwd: "/workspace" # Path INSIDE the sandbox (default: /root)

# timeout: 180

# lifetime_seconds: 300

# modal_image: "nousresearch/hermes-sandbox:desktop"

# -----------------------------------------------------------------------------

# OPTION 6: Daytona cloud execution

# Commands run in Daytona cloud sandboxes

# Great for: Cloud dev environments, persistent workspaces, team collaboration

# Requires: pip install daytona, DAYTONA_API_KEY env var

# -----------------------------------------------------------------------------

# terminal:

# backend: "daytona"

# cwd: "~"

# timeout: 180

# lifetime_seconds: 300

# daytona_image: "nousresearch/hermes-sandbox:desktop"

# container_disk: 10240 # Daytona max is 10GB per sandbox

#

# --- Container resource limits (docker, modal, daytona, container plugin backends -- ignored for local/ssh) ---

# These settings apply to all container backends. They control the resources

# allocated to the sandbox and whether its filesystem persists across sessions.

container_cpu: 1 # CPU cores

container_memory: 5120 # Memory in MB (5120 = 5GB)

container_disk: 51200 # Disk in MB (51200 = 50GB)

container_persistent: true # Persist filesystem across sessions (false = ephemeral)

# -----------------------------------------------------------------------------

# SUDO SUPPORT (works with ALL backends above)

# -----------------------------------------------------------------------------

# Add sudo_password to any terminal config above to enable sudo commands.

# The password is piped via `sudo -S`. Works with local, ssh, docker, etc.

#

# SECURITY WARNING: Password stored in plaintext!

#

# INTERACTIVE PROMPT: If sudo_password is unset and the CLI is running,

# you'll be prompted to enter your password when sudo is needed:

# - 45-second timeout (auto-skips if no input)

# - Press Enter to skip (command fails gracefully)

# - Password is hidden while typing

# - Password is cached for the session

#

# EMPTY PASSWORDS: Setting sudo_password to an explicit empty string is different

# from leaving it unset. Hermes will try an empty password via `sudo -S` and

# will not open the interactive prompt. This is useful for passwordless sudo,

# Touch ID sudo setups, and environments where prompting is just noise.

#

# ALTERNATIVES:

# - SSH backend: Configure passwordless sudo on the remote server

# - Containers: Run as root inside the container (no sudo needed)

# - Local: Configure /etc/sudoers for specific commands

#

# Example (add to your terminal section):

# sudo_password: "your-password-here"

# =============================================================================

# Security

# =============================================================================

# security:

# approval:

# transport: builtin # Or an explicitly enabled plugin transport name

# transport_fallback: deny # Set builtin to opt into fallback on transport failure

# # Agent writes to instruction files that steer the agent itself

# # (AGENTS.md, CLAUDE.md, SOUL.md, ...) always ask for human approval,

# # even under --yolo, and are refused when nobody can answer. Set false to

# # disable the gate; add fnmatch patterns on the basename to protect more files.

# protected_instruction_files: true

# protected_instruction_extra_patterns: []

# =============================================================================

# LSP Diagnostics (post-write lint for write_file / patch)

# =============================================================================

# lsp:

# enabled: true

# # Language servers only load code a project ships (its .venv interpreter,

# # node_modules TypeScript, svelte.config.js, cargo/Gradle/mix build files)

# # in the git worktree of the directory you launched Hermes in or opened

# # the session in (hermes -w, a Desktop project, terminal.cwd), or under a

# # directory listed here. In other checkouts, such as a repository the agent

# # cloned, only servers that run no project code start (pinned to

# # Hermes-side tools) and the npx tsc / rustfmt lint fallbacks are skipped.

# trusted_workspaces:

# - ~/code/my-app

# =============================================================================

# Browser Tool Configuration

# =============================================================================

browser:

# Inactivity timeout in seconds - browser sessions are automatically closed

# after this period of no activity between agent loops (default: 120 = 2 minutes)

inactivity_timeout: 120

# Local Chromium for browser_exec. Empty executable_path = pm's chromium

# (`hermes pm install chromium`), the Docker image's build, or a system

# chromium where pm builds none (Termux). user_data_dir keeps one persistent

# profile for every local session (empty = a throwaway profile per session).

# executable_path: ""

# user_data_dir: ""

# chromium_args: ["--lang=de"]

# =============================================================================

# Tool Loop Guardrails

# =============================================================================

# Soft warnings are enabled by default. They append guidance to repeated failed

# or non-progressing tool results but still let the tool execute. Hard stops stay

# opt-in for interactive CLI/TUI/Desktop/ACP sessions, but default on for unattended

# gateway/cron sessions where nobody is present to interrupt a model that

# ignores loop warnings.

tool_loop_guardrails:

warnings_enabled: true

hard_stop_enabled: false

non_interactive_hard_stop_enabled: true

warn_after:

exact_failure: 2

same_tool_failure: 3

idempotent_no_progress: 2

hard_stop_after:

exact_failure: 5

same_tool_failure: 8

idempotent_no_progress: 5

# =============================================================================

# Context Compression (Auto-shrinks long conversations)

# =============================================================================

# When conversation approaches model's context limit, middle turns are

# automatically summarized to free up space while preserving important context.

#

# HOW IT WORKS:

# 1. Tracks actual token usage from API responses (not estimates)

# 2. When prompt_tokens >= threshold% of model's context_length, triggers compression

# 3. Protects first 3 turns (system prompt, initial request, first response)

# 4. Protects last N turns (default 20 messages = ~10 full turns of recent context)

# 5. Summarizes middle turns using a fast/cheap model

# 6. Inserts summary as a user message, continues conversation seamlessly

#

# Post-compression tail budget is target_ratio × threshold × context_length:

# 200K context, threshold 0.50, ratio 0.20 → 20K tokens of recent tail preserved

# 1M context, threshold 0.50, ratio 0.20 → 100K tokens of recent tail preserved

#

compression:

# Enable automatic context compression (default: true)

# Set to false if you prefer to manage context manually or want errors on overflow

enabled: true

# Fail closed before lossy compaction unless an active memory provider that

# implements the pre-compress checkpoint contract (API v2) confirms its

# durable checkpoint (default: false). With this on and no checkpoint, the

# compaction attempt errors with BLOCKED_MISSING_PREREQUISITE and the

# uncompressed transcript is preserved for a later retry. The gate binds to

# every compaction authority: server-side native compaction

# (codex_responses_native) is suppressed while armed, post-turn

# micro-compaction is forced off (no checkpoint hook in its path), and the

# codex_app_server API mode is refused at agent init (the codex agent

# compacts its own thread — no checkpoint can be guaranteed there). Only

# enable it with a checkpoint-capable provider configured — see

# website/docs/developer-guide/memory-provider-plugin.md

# ("Pre-Compress Checkpoints").

checkpoint_required: false

# Opt-in compression progress notices on chat platforms (default: false).

# By design, routine automatic compression is SILENT on human-facing chat

# gateways (Telegram, Discord, Slack, ...) — it happens in the background

# with server-side logging only. Set true to also deliver the routine

# progress statuses (compacting started, preflight/pre-API compression,

# idle compaction, retry progress, and the compaction-complete notice) to

# chat platforms. Unrelated operational noise (auxiliary model failures,

# provider retry chatter) stays suppressed either way, and compression

# FAILURE notices + manual /compress feedback are always visible

# regardless of this setting. (#52995)

progress_notices: false

# Trigger compression at this % of model's context limit (default: 0.50 = 50%)

# Lower values = more aggressive compression, higher values = compress later

# Models with context windows below 512K are floored at 0.75 (raise-only) so

# compaction doesn't fire with half the window still free; set above 0.75 to override.

threshold: 0.50

# Per-model threshold overrides: keys are substring-matched against the model

# name (longest match wins). Useful when some models need different compaction

# points — e.g. a 1M-context model can compress later (0.30) while a 128K

# model needs to compress earlier (0.60). The small-context floor (75% for

# <512K models) still applies on top of per-model overrides.

# model_thresholds:

# "glm-5.2": 0.40

# "claude-sonnet": 0.35

# "gpt-5": 0.30

# Optional absolute token cap for the compression trigger (default: null = disabled).

# When set, compression fires at the LOWER of the ratio-based threshold and this

# absolute token count. Clamped to the model's context length at apply-time, so a

# cap above the window is a no-op. Survives model switches and fallback activations.

# threshold_tokens: 200000

# Existing Codex gpt-5.5 behavior: raise Hermes' compaction trigger to 85%

# for the ChatGPT Codex OAuth route. Set false to opt back down to threshold.

codex_gpt55_autoraise: true

# Fraction of the threshold to preserve as recent tail (default: 0.20 = 20%)

# e.g. 20% of 50% threshold = 10% of total context kept as recent messages.

# Summary output is separately capped at 12K tokens (Gemini output limit).

# Range: 0.10 - 0.80

target_ratio: 0.20

# Number of most-recent messages to always preserve (default: 20 ≈ 10 full turns)

# Higher values keep more recent conversation intact at the cost of more aggressive

# compression of older turns.

protect_last_n: 20

# Minimum number of REAL (actionable) user messages guaranteed to survive in

# the uncompressed tail (default: 1 = the existing single last-user anchor,

# behavior-preserving). Raise to e.g. 3 to keep the last 3 real user turns

# verbatim even when bulky tool outputs fill the tail token budget — blank

# platform echoes, compaction handoffs, and synthetic continuation rows never

# count toward N. The tail can exceed the token budget when this pulls the

# cut back; the guarantee wins over the budget by design.

min_tail_user_messages: 1

# Compression retry rounds before a turn gives up with "max compression

# attempts reached" (default: 3, same as the previous hardcoded value).

# Raise (e.g. 6) for tool-schema-heavy sessions where 3 rounds cannot bring

# the request estimate under the threshold. Validated >= 1, hard cap 10.

max_attempts: 3

# Codex app-server (codex CLI runtime) thread-compaction mode. The codex

# agent owns the real thread context on this runtime, so Hermes' summarizer

# cannot shrink it — compaction goes through the app server instead.

# native = let Codex decide when to compact its own thread (default)

# hermes = let Hermes threshold trigger Codex thread/compact/start

# off = Hermes will not auto-trigger compaction; Codex may still compact natively

codex_app_server_auto: native

# Native OpenAI Responses server-side compaction (default: false). When true,

# gpt-5.6-family models on the DIRECT OpenAI API (api.openai.com) or a ChatGPT

# Codex subscription, plus gpt-6-astra (and its -900k alias) on official Codex OAuth, compact

# server-side: OpenAI prunes older context into an

# encrypted checkpoint that Hermes replays on later turns. No other provider,

# route, or model is affected. Hermes' local compression stays armed as the

# fallback and still handles every non-eligible session.

codex_responses_native: false

# Optional absolute server compaction trigger in input tokens. The default

# null value follows the resolved local compression trigger with an 8192 token

# safety margin. For example, a local trigger of 765000 selects 756808.

# A positive integer stays absolute and only clamps downward when needed so

# the server compacts first. Invalid values use this automatic behavior. If

# the local trigger is unavailable, automatic mode uses 200000.

codex_responses_compact_threshold: null

# Number of non-system messages to protect at the head of the transcript, in

# ADDITION to the system prompt (which is always implicitly protected).

# Head messages are NEVER summarized — they survive every compression

# indefinitely. This gives stable early context for short/medium sessions,

# but in long-running sessions that rely on rolling compaction the pinned

# opening turns may not match how you want the session framed over time.

# Set to 0 to preserve ONLY the system prompt (plus the rolling summary

# and recent tail) — the cleanest configuration for long-running sessions.

# Default 3 preserves the system prompt plus the first three non-system

# head messages, matching the pre-feature behaviour.

protect_first_n: 3

# Idle compaction (default: 0 = disabled). When > 0, a session that resumes

# after at least this many seconds of inactivity compacts its accumulated

# history up front, before the first reply, so a long-lived thread you come

# back to later doesn't re-read its full stale context on every turn.

# Time-based, so it complements (does not replace) the size-based `threshold`

# above. It is skipped when the context is already small (at or below the

# post-compression target = threshold × target_ratio), so it never wastes a

# summarization on a short idle thread. Example: 1800 = compact after 30 min idle.

idle_compact_after_seconds: 0

# Gateway session-hygiene turn-hold budget (default: 10). Max seconds an

# arriving user turn is held while a still-streaming hygiene summary

# finishes. Distinct from hygiene_timeout_seconds (compressor inactivity

# budget): this bounds user-visible latency so chat transports (Telegram

# ~30s) do not drop a silent connection. On expiry the turn proceeds

# uncompressed; the detached worker keeps its commit admission (when the

# commit is watermark-fenced) and the summary is adopted at the next safe

# boundary. Thinking-model summarizers often need longer than 10s to emit

# the first content token — raise to 300 (or >= your summarizer's real

# time-to-first-content) only if you want THIS turn to wait for the

# compression instead of adopting it one turn late.

hygiene_max_turn_hold_seconds: 10

# Proactive tool-result prune (default: 0 = disabled). Opt-in token trigger

# for a deterministic, no-LLM prune of OLD tool-result payloads, run

# independently of `threshold` above. On large-window models (512K/1M) the

# ratio threshold rarely fires, so bulky tool outputs (terminal dumps, file

# reads, web extracts) ride along in history and get re-billed every turn.

# When re-sent history exceeds this many tokens, the prune dedupes identical

# results, summarizes older oversized ones, and truncates large tool-call

# arguments — protecting the most recent `protect_last_n` messages and never

# calling the model. Try 48000 to enable. Built-in compressor engine only;

# other context engines inherit a safe no-op.

# NOTE: a committed prune rewrites already-sent history, which invalidates

# the provider's prompt-cache prefix — the min_reclaim gate below keeps

# those cache breaks episodic (like a compression boundary) instead of

# per-turn.

proactive_prune_tokens: 0

# The prune's summarize pass only touches tool results larger than this many

# characters (clamped to >= 200 so a generated summary can't be

# re-summarized). Default 8000.

proactive_prune_min_result_chars: 8000

# A proactive prune only COMMITS when it reclaims at least this many tokens

# (measured on the pruned output). This is the prompt-cache hysteresis gate:

# one meaningful, amortized cache break per batch of stale tool output

# instead of a tiny break on every tool iteration. 0 = commit any non-zero

# prune. Default 4096.

proactive_prune_min_reclaim_tokens: 4096

# To pin a specific model/provider for compression summaries, use the

# auxiliary section below (auxiliary.compression.provider / model).

# =============================================================================

# Tool-result budget (optional)

# =============================================================================

# Controls when a large tool result is spilled to disk (full output saved to

# $HERMES_HOME/cache/spillover, preview + path kept in context). MCP tool

# results (tools named mcp_*) spill at a tighter 50,000-char threshold than

# the generic 100K default: MCP servers routinely return un-paginated 20-50K

# payloads that bloat context and slow every subsequent turn. Nothing is

# lost — the full result is on disk and readable with read_file.

#

# tool_budget:

# mcp_result_size_chars: 50000 # per-result spillover threshold for mcp_* tools

# =============================================================================

# Anthropic prompt caching TTL

# =============================================================================

# When prompt caching is active (Claude via OpenRouter or native Anthropic),

# Anthropic supports two TTL tiers for cached prefixes: "5m" (default) and

# "1h". Other values are ignored and "5m" is used.

#

prompt_caching:

cache_ttl: "5m" # use "1h" for long sessions with pauses between turns

# =============================================================================

# Auxiliary Models (Advanced — Experimental)

# =============================================================================

# Hermes uses lightweight "auxiliary" models for side tasks: image analysis,

# browser screenshot analysis, web page summarization, TTS audio-tag insertion,

# and context compression.

#

# By default these use Gemini Flash via OpenRouter or Nous Portal and are

# auto-detected from your credentials. You do NOT need to change anything

# here for normal usage.

#

# WARNING: Overriding these with providers other than OpenRouter or Nous Portal

# is EXPERIMENTAL and may not work. Not all models/providers support vision,

# produce usable summaries, or accept the same API format. Change at your own

# risk — if things break, reset to "auto" / empty values.

#

# Each task has its own provider + model pair so you can mix providers.

# For example: OpenRouter for vision (needs multimodal), but your main

# local endpoint for compression (just needs text).

#

# Provider options:

# "auto" - Best available: OpenRouter → Nous Portal → main endpoint (default)

# "openrouter" - Force OpenRouter (requires OPENROUTER_API_KEY)

# "nous" - Force Nous Portal (requires: hermes auth add nous)

# "gemini" - Force Google AI Studio direct (requires: GOOGLE_API_KEY or GEMINI_API_KEY)

# "ollama-cloud" - Ollama Cloud (requires: OLLAMA_API_KEY)

# "codex" - Force Codex OAuth (requires: hermes model → Codex).

# Uses gpt-5.3-codex which supports vision.

# "main" - Use your custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY).

# Works with OpenAI API, local models, or any OpenAI-compatible

# endpoint. Also falls back to Codex OAuth and API-key providers.

#

# Model: leave empty to use the provider's default. When empty, OpenRouter

# uses "google/gemini-3-flash-preview" and Nous uses "gemini-3-flash".

# Other providers pick a sensible default automatically.

#

# Native vision embeds (vision_analyze / browser screenshots when the MAIN model

# is vision-capable) ride conversation history and are re-sent on every later

# API call, so both knobs below bound recurring cost:

#

# vision:

# # Byte budget for one embedded image (clamped 64 KiB..4 MiB). Raise it for

# # dense phone screenshots of tables that read as "unreadable" at 256 KB.

# embed_target_bytes: 262144

# # How often vision_analyze may embed the SAME image (region crops included)

# # per session. Unset = 3 inside delegated subagents, unlimited for the main

# # agent; a number applies everywhere; 0 = unlimited.

# max_calls_per_image: 3

# # Newest user images re-sent on turns rebuilt from the session DB (API server,

# # --resume) when the model takes images natively; 0 = off. Older images drop

# # in whole batches of this size, so the cached prefix changes once per batch.

# replay_recent_images: 3

#

# auxiliary:

# # Image analysis: vision_analyze tool + browser screenshots

# vision:

# provider: "auto"

# model: "" # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"

# timeout: 30 # LLM API call timeout (seconds)

# download_timeout: 30 # Image HTTP download timeout (seconds)

# # Increase for slow connections or self-hosted image servers

# reasoning_effort: "" # Per-task thinking level: none, minimal, low, medium,

# # high, xhigh, max, ultra. Empty = provider default.

# # Works on every auxiliary task block (vision,

# # web_extract, compression, title_generation, curator,

# # background_review, moa_reference, ...). Example: run

# # compression at "low" and vision at "none" to cut

# # side-task latency/cost on reasoning models.

#

# # Web page scraping / summarization + browser page text extraction

# web_extract:

# provider: "auto"

# model: ""

# reasoning_effort: "low"

#

# # Gemini 3.1 TTS hidden audio-tag insertion

# tts_audio_tags:

# provider: "auto" # empty model = your main chat model

# model: ""

# timeout: 30

#

# # Automatic session title generation after the first exchange

# title_generation:

# enabled: true # set false to disable auto-title generation

# model_upgrade_enabled: true # set false to keep the instant derived title and skip the model call

# provider: "auto"

# model: ""

# timeout: 30

# language: "" # empty = match the user's language; or e.g. "English"

#

# # Session search — summarizes matching past sessions

# session_search:

# provider: "auto"

# model: ""

# timeout: 30

# max_concurrency: 3 # Limit parallel summaries to reduce request-burst 429s

# extra_body: {} # Provider-specific OpenAI-compatible request fields

# # Example for providers that support request-body

# # reasoning controls:

# # extra_body:

# # enable_thinking: false

# # Some vLLM/Qwen deployments expect this nested:

# # extra_body:

# # chat_template_kwargs:

# # enable_thinking: false

#

# # Auto-generated short session titles after the first exchange.

# # Each active Discord/Telegram channel can spawn a background title

# # call. Cap concurrency to keep retries during provider incidents

# # from amplifying the request burst. Leave unset for legacy behavior

# # (unlimited).

# title_generation:

# provider: "auto"

# model: ""

# # max_concurrency: 2 # Optional: cap simultaneous title calls

#

# # Context compression — summarizes long sessions to shrink the prompt.

# # Heavy and often hits the slowest provider chain. Setting a small

# # cap prevents many sessions from compressing simultaneously during

# # provider degradation. Leave unset for legacy behavior (unlimited).

# compression:

# provider: "auto"

# model: ""

# # max_concurrency: 2 # Optional: cap simultaneous compression calls

# # no_progress_timeout: 60 # Codex/Responses-only: seconds a stream may go without a

# # substantive event before it fails fast (default: 60).

# # Independent of "timeout" above (the overall request

# # budget) — raising "timeout" alone does not widen this

# # window. Each substantive event re-arms it; a slow but

# # progressing reasoning/summary stream is not affected.

#

# # Post-turn memory/skill self-improvement review fork. Runs after a turn

# # when the nudge intervals fire; writes skills/memories in a daemon thread.

# # Usage is recorded under session_model_usage task='background_review'.

# background_review:

# enabled: true # false = skip automatic forks (/refine still works)

# provider: "auto" # or pin a cheaper model (see memory.md)

# model: ""