Configuration

기준일: 2026-07-26
공식 기준: Configuration

Configuration 문서는 Hermes Agent 공식 문서(user-guide/configuration)를 한국어로 정리한 가이드입니다. Configure Hermes Agent — config.yaml, providers, models, API keys, and more 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Configure Hermes Agent — config.yaml, providers, models, API keys, and more

한국어 가이드 범위: user-guide/configuration 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 구성
• Directory Structure
• Managing Configuration
• Examples:
• Configuration Precedence
• Environment Variable Substitution
• Provider Timeouts
• Update Behavior
• Terminal Backend Configuration
• Backend Overview
• Local Backend
• Docker Backend
• SSH Backend
• Modal Backend
• Daytona Backend
• Singularity/Apptainer Backend
• Common Terminal Backend Issues
• Remote-to-Host File Sync on Teardown
• Docker Volume Mounts
• Docker Credential Forwarding
• Running the Container as Your Host User
• Optional: Mount the Launch Directory into /workspace
• Persistent Shell
• Skill Settings
• Guard on agent-created skill writes
• Write approval for skill writes
• Memory Configuration
• Context File Truncation
• File Read Safety
• Large context model (200K+)
• Small local model (16K context)
• Tool Output Truncation Limits
• Large context model (200K+)
• Small local model (16K context)
• Global Toolset Disable
• Git Worktree Isolation
• worktree: false # Default — only when -w flag is passed
• worktree_sync: false # Branch from local HEAD (offline / pinned base)
• .worktreeinclude
• Context Compression

상세 내용

구성

All settings are stored in the ~/.hermes/ directory for easy access.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Directory Structure

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

Managing Configuration

hermes config                 # View current configuration
hermes config edit            # Open config.yaml in your editor
hermes config get KEY         # Print a resolved value
hermes config set KEY VAL     # Set a specific value
hermes config unset KEY       # Remove a user-set value
hermes config check           # Check for missing options (after updates)
hermes config migrate         # Interactively add missing options

Examples

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Configuration Precedence

Settings are resolved in this order (highest priority first):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Environment Variable Substitution

You can reference environment variables in config.yaml using ${VAR_NAME} syntax:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Provider Timeouts

You can set providers..request_timeout_seconds for a provider-wide request timeout, plus providers..models..timeout_seconds for a model-specific override. Applies to the primary turn client on every transport (OpenAI-wire, native Anthropic, Anthropic-compatible), the fallback chain, rebuilds after credential rotation, and (for OpenAI-wire) the per-request timeout kwarg — so the configured value wins over the legacy HERMES_API_TIMEOUT env var.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Update Behavior

hermes update settings live under updates in config.yaml:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

updates:
  pre_update_backup: quick       # quick (state snapshot, default) | full (snapshot + HERMES_HOME zip) | off
  backup_keep: 5                 # Keep this many full pre-update backup zips
  non_interactive_local_changes: stash  # stash | discard

Terminal Backend Configuration

Hermes supports six terminal backends. Each determines where the agent's shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox (direct or via the Nous-managed gateway), a Daytona workspace, or a Singularity/Apptainer container.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Gateway/cron working directory (CLI always uses launch dir)
  timeout: 180      # Per-command timeout in seconds
  home_mode: auto   # auto | real | profile — subprocess HOME policy
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

Backend Overview

Backend	Where commands run	Isolation	Best for
local	Your machine directly	None	Development, personal use
docker	Single persistent Docker container (shared across session, /new, subagents)	Full (namespaces, cap-drop)	Safe sandboxing, CI/CD
ssh	Remote server via SSH	Network boundary	Remote dev, powerful hardware
modal	Modal cloud sandbox	Full (cloud VM)	Ephemeral cloud compute, evals
daytona	Daytona workspace	Full (cloud container)	Managed cloud dev environments
singularity	Singularity/Apptainer container	Namespaces (--containall)	HPC clusters, shared machines

Local Backend

The default. Commands run directly on your machine with no isolation. No special setup required.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Mode	Host installs	Containers	Tradeoff
auto	Keep the real OS-user HOME	Use {HERMES_HOME}/home	Recommended default. Host CLIs keep working; container state persists.
real	Force the real OS-user HOME	Force the real OS-user HOME if visible	Useful if a parent process accidentally started with HOME pointed at a profile home.
profile	Use {HERMES_HOME}/home when it exists	Use {HERMES_HOME}/home when it exists	Strict per-profile CLI config isolation, but normal ~/.ssh, ~/.gitconfig, ~/.azure, ~/.config/gh, Claude/Codex auth, npm state, etc. will not be visible unless you initialize or link them inside the profile home.

terminal:
  backend: local

terminal:
  home_mode: profile

from pathlib import Path

hermes_home = Path(os.environ["HERMES_HOME"])
real_home = Path(os.environ.get("HERMES_REAL_HOME", os.environ["HOME"]))

Docker Backend

Runs commands inside a Docker container with security hardening (all capabilities dropped, no privilege escalation, PID limits).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "GITHUB_TOKEN"
• "/home/user/projects:/workspace/projects"
• "/home/user/data:/data:ro" # :ro for read-only
• "--gpus=all"
• "--network=host"
• hermes-agent=1 — marks it as Hermes-managed
• hermes-task-id=<sanitized task_id> — keys the per-task reuse probe
• hermes-profile=<sanitized profile name> — scopes reuse and reaping to the active Hermes profile
• OOM kill of in-container PID 1 transitions the container to Exited. Next reuse will docker start it; filesystem state survives, bg processes do not.
• Switching profiles isolates containers from each other — a container labeled hermes-profile=work is invisible to a Hermes process running under hermes-profile=research. The orphan reaper is profile-scoped too, so cross-profile containers don't get reaped accidentally, but they also won't get cleaned up automatically until you start Hermes again under their original profile.
• --cap-drop ALL with only DAC_OVERRIDE, CHOWN, FOWNER added back
• --security-opt no-new-privileges
• --pids-limit 256
• Size-limited tmpfs for /tmp (512MB), /var/tmp (256MB), /run (64MB)

Trigger	When it fires
docker_persist_across_processes: false	Explicit per-process isolation. Every cleanup() does stop + rm -f. Matches pre-issue-#20561 behavior.
Idle reaper (lifetime_seconds, default 300s)	Only when the env is persist_across_processes=false. Persist-mode envs are no-op'd; container survives the idle sweep.
Orphan reaper at next startup	Sweeps Exited hermes-labeled containers older than 2 × lifetime_seconds (default 600s = 10 min), scoped to the current profile. Running containers are never touched — sibling-process safety. Set docker_orphan_reaper: false to disable.
Direct user action	docker rm -f, docker system prune, Docker Desktop restart. We don't set --restart=always, so a host reboot leaves the container Exited (its CoW layer survives and gets reused on next startup, but bg processes are gone).

Env var	Maps to	Notes
TERMINAL_DOCKER_IMAGE	docker_image	Base image
TERMINAL_DOCKER_FORWARD_ENV	docker_forward_env	JSON array: '["GITHUB_TOKEN","OPENAI_API_KEY"]'
TERMINAL_DOCKER_ENV	docker_env	JSON dict: '{"DEBUG":"1"}'
TERMINAL_DOCKER_VOLUMES	docker_volumes	JSON array of "host:container[:ro]" strings
TERMINAL_DOCKER_EXTRA_ARGS	docker_extra_args	JSON array
TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE	docker_mount_cwd_to_workspace	true / false
TERMINAL_DOCKER_RUN_AS_HOST_USER	docker_run_as_host_user	true / false
TERMINAL_DOCKER_NETWORK	docker_network	true / false — default true; false = --network=none
TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSES	docker_persist_across_processes	true / false — default true
TERMINAL_DOCKER_ORPHAN_REAPER	docker_orphan_reaper	true / false — default true
TERMINAL_CONTAINER_CPU	container_cpu	CPU cores
TERMINAL_CONTAINER_MEMORY	container_memory	MB
TERMINAL_CONTAINER_DISK	container_disk	MB
TERMINAL_CONTAINER_PERSISTENT	container_persistent	true / false — controls the bind-mount workspace dirs, distinct from docker_persist_across_processes
TERMINAL_LIFETIME_SECONDS	lifetime_seconds	Idle reaper window
TERMINAL_TIMEOUT	timeout	Per-command timeout
HERMES_DOCKER_BINARY	none	Force a specific docker/podman binary path

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # Mount launch dir into /workspace
  docker_run_as_host_user: false   # See "Running container as host user" below
  docker_forward_env:              # Host env vars to forward into container
    - "GITHUB_TOKEN"
  docker_env:                      # Literal env vars to inject (KEY=value)
    DEBUG: "1"
    PYTHONUNBUFFERED: "1"
  docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro for read-only
  docker_extra_args:               # Extra flags appended verbatim to `docker run`
    - "--gpus=all"
    - "--network=host"
  docker_network: true             # false = air-gap the container (--network=none)

  # Resource limits
  container_cpu: 1                 # CPU cores (0 = unlimited)
  container_memory: 5120           # MB (0 = unlimited)
  container_disk: 51200            # MB (requires overlay2 on XFS+pquota)
  container_persistent: true       # Persist /workspace and /root bind-mount dirs

  # Cross-process container reuse (defaults match the "one long-lived
  # container shared across sessions" contract — see Container lifecycle).
  docker_persist_across_processes: true   # Reuse container across Hermes restarts
  docker_orphan_reaper: true              # Sweep abandoned Exited containers at startup

  # Cross-backend lifecycle settings (apply to docker as well)
  timeout: 180                     # Per-command timeout in seconds
  lifetime_seconds: 300            # Idle-reaper window; also feeds 2× orphan-reaper threshold

SSH Backend

Runs commands on a remote server over SSH. Uses ControlMaster for connection reuse (5-minute idle keepalive). Persistent shell is enabled by default — state (cwd, env vars) survives across commands.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Variable	Default	Description
TERMINAL_SSH_PORT	22	SSH port
TERMINAL_SSH_KEY	(system default)	Path to SSH private key
TERMINAL_SSH_PERSISTENT	true	Enable persistent shell

terminal:
  backend: ssh
  persistent_shell: true           # Keep a long-lived bash session (default: true)

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

Modal Backend

Runs commands in a Modal cloud sandbox. Each task gets an isolated VM with configurable CPU, memory, and disk. Filesystem can be snapshot/restored across sessions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

terminal:
  backend: modal
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # Snapshot/restore filesystem

Daytona Backend

Runs commands in a Daytona managed workspace. Supports stop/resume for persistence.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

terminal:
  backend: daytona
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB → converted to GiB
  container_disk: 10240            # MB → converted to GiB (max 10 GiB)
  container_persistent: true       # Stop/resume instead of delete

Singularity/Apptainer Backend

Runs commands in a Singularity/Apptainer container. Designed for HPC clusters and shared machines where Docker isn't available.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB
  container_persistent: true       # Writable overlay persists across sessions

Common Terminal Backend Issues

If terminal commands fail immediately or the terminal tool is reported as disabled:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Local — No special requirements. The safest default when getting started.
• Docker — Run docker version to verify Docker is working. If it fails, fix Docker or hermes config set terminal.backend local.
• SSH — Both TERMINAL_SSH_HOST and TERMINAL_SSH_USER must be set. Hermes logs a clear error if either is missing.
• Modal — Needs MODAL_TOKEN_ID env var or ~/.modal.toml. Run hermes doctor to check.
• Daytona — Needs DAYTONA_API_KEY. The Daytona SDK handles server URL configuration.
• Singularity — Needs apptainer or singularity in $PATH. Common on HPC clusters.

Remote-to-Host File Sync on Teardown

For the SSH, Modal, and Daytona backends (anywhere the agent's working tree lives on a different machine than the host running Hermes), Hermes tracks files the agent touched inside the remote sandbox and, on session teardown / sandbox cleanup, syncs the modified files back to the host under ~/.hermes/cache/remote-syncs//.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Triggers on: session close, /new, /reset, gateway message timeout, delegate_task subagent completion when the child used a remote backend.
• Covers the whole tree the agent modified, not just files it explicitly opened. Additions, edits, and deletions are all captured.
• The remote sandbox may have been torn down by the time you go looking; the local ~/.hermes/cache/remote-syncs/… copy is the authoritative record of what the agent changed.
• Large binary outputs (model checkpoints, raw datasets) are capped by size — the sync skips files over file_sync_max_mb (default 100). Bump that if you expect bigger artifacts to come back.

terminal:
  file_sync_max_mb: 100     # default — sync files up to 100 MB each
  file_sync_enabled: true   # default — set false to skip the sync entirely

Docker Volume Mounts

When using the Docker backend, docker_volumes lets you share host directories with the container. Each entry uses standard Docker -v syntax: host_path:container_path[:options].

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "/home/user/projects:/workspace/projects" # Read-write (default)
• "/home/user/datasets:/data:ro" # Read-only
• "/home/user/.hermes/cache/documents:/output" # Gateway-visible exports
• Providing files to the agent (datasets, configs, reference code)
• Receiving files from the agent (generated code, reports, exports)
• Shared workspaces where both you and the agent access the same files
• Write files inside Docker to /output/...
• Emit the host path in MEDIA:, for example:
• Do not emit /workspace/... or /output/... unless that exact path also

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # Read-write (default)
    - "/home/user/datasets:/data:ro"              # Read-only
    - "/home/user/.hermes/cache/documents:/output" # Gateway-visible exports

Docker Credential Forwarding

By default, Docker terminal sessions do not inherit arbitrary host credentials. If you need a specific token inside the container, add it to terminal.docker_forward_env.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "GITHUB_TOKEN"
• "NPM_TOKEN"

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Running the Container as Your Host User

By default Docker containers run as root (UID 0). Files created inside /workspace or other bind-mounts end up owned by root on the host, so after a session you have to sudo chown them before you can edit them from your host editor. The terminal.docker_run_as_host_user flag fixes this:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

terminal:
  backend: docker
  docker_run_as_host_user: true   # default: false

Optional: Mount the Launch Directory into /workspace

Docker sandboxes stay isolated by default. Hermes does not pass your current host working directory into the container unless you explicitly opt in.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• if you launch Hermes from ~/projects/my-app, that host directory is bind-mounted to /workspace
• the Docker backend starts in /workspace
• file tools and terminal commands both see the same mounted project
• false preserves the sandbox boundary
• true gives the sandbox direct access to the directory you launched Hermes from

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

Persistent Shell

By default, each terminal command runs in its own subprocess — working directory, environment variables, and shell variables reset between commands. When persistent shell is enabled, a single long-lived bash process is kept alive across execute() calls so that state survives between commands.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Working directory (cd /tmp sticks for the next command)
• Exported environment variables (export FOO=bar)
• Shell variables (MY_VAR=hello)

Level	Variable	Default
Config	terminal.persistent_shell	true
SSH override	TERMINAL_SSH_PERSISTENT	follows config
Local override	TERMINAL_LOCAL_PERSISTENT	false

terminal:
  persistent_shell: true   # default — enables persistent shell for SSH

hermes config set terminal.persistent_shell false

Skill Settings

Skills can declare their own configuration settings via their SKILL.md frontmatter. These are non-secret values (paths, preferences, domain settings) stored under the skills.config namespace in config.yaml.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• hermes config migrate scans all enabled skills, finds unconfigured settings, and offers to prompt you
• hermes config show displays all skill settings under "Skill Settings" with the skill they belong to
• When a skill loads, its resolved config values are injected into the skill context automatically

skills:
  config:
    myplugin:
      path: ~/myplugin-data   # Example — each skill defines its own keys

hermes config set skills.config.myplugin.path ~/myplugin-data

Guard on agent-created skill writes

When the agent uses skill_manage to create, edit, patch, or delete a skill, Hermes can optionally scan the new/updated content for dangerous keyword patterns (credential harvesting, obvious prompt injection, exfil instructions). The scanner is off by default — real agent workflows that legitimately touch ~/.ssh/ or mention $OPENAI_API_KEY were tripping the heuristic too often. Turn it back on if you want the scanner to prompt you before the agent's skill writes land:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

skills:
  guard_agent_created: true   # default: false

Write approval for skill writes

Independent of the content scanner above, skills.write_approval gates every agent skill write (create / edit / patch / delete / supporting files) behind your explicit approval — the same approve/deny mechanism as dangerous commands:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

skills:
  write_approval: false   # false = write freely (default) | true = stage every write for review

Memory Configuration

With memory.write_approval: true, memory writes need your approval before they land: interactive CLI turns prompt inline; messaging sessions and the background self-improvement review stage the write for /memory pending → /memory approve / /memory reject review. Toggle at runtime with /memory approval on|off. See Controlling memory writes.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # true = require approval before any memory write

Context File Truncation

Controls how much content Hermes loads from each automatic context file before applying head/tail truncation. This applies to files injected into the system prompt such as SOUL.md, .hermes.md, AGENTS.md, CLAUDE.md, and .cursorrules. It does not affect the read_file tool.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

context_file_max_chars: 20000  # default

context_file_max_chars: 25000

File Read Safety

Controls how much content a single read_file call can return. Reads that exceed the limit are rejected with an error telling the agent to use offset and limit for a smaller range. This prevents a single read of a minified JS bundle or large data file from flooding the context window.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

file_read_max_chars: 100000  # default — ~25-35K tokens

Large context model (200K+)

file_read_max_chars: 200000

Small local model (16K context)

The agent also deduplicates file reads automatically — if the same file region is read twice and the file hasn't changed, a lightweight stub is returned instead of re-sending the content. This resets on context compression so the agent can re-read files after their content is summarized away.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Tool Output Truncation Limits

Three related caps control how much raw output a tool can return before Hermes truncates it:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• max_bytes — When a terminal command produces more than this many characters of combined stdout/stderr, Hermes keeps the first 40% and last 60% and inserts a [OUTPUT TRUNCATED] notice between them. Default 50000 (≈12-15K tokens across typical tokenisers).
• max_lines — Upper bound on the limit parameter of a single read_file call. Requests above this are clamped so a single read can't flood the context window. Default 2000.
• max_line_length — Per-line cap applied when read_file emits the line-numbered view. Lines longer than this are truncated to this many chars followed by ... [truncated]. Default 2000.

tool_output:
  max_bytes: 50000        # terminal output cap (chars)
  max_lines: 2000         # read_file pagination cap
  max_line_length: 2000   # per-line cap in read_file's line-numbered view

Large context model (200K+)

tool_output: max_bytes: 150000 max_lines: 5000

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Small local model (16K context)

tool_output: max_bytes: 20000 max_lines: 500

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

### Global Toolset Disable

To suppress specific toolsets across the CLI and every gateway platform in one place, list their names under `agent.disabled_toolsets`:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

- memory       # hide memory tools + MEMORY_GUIDANCE injection
- web          # no web_search / web_extract anywhere

```yaml
agent:
  disabled_toolsets:
    - memory       # hide memory tools + MEMORY_GUIDANCE injection
    - web          # no web_search / web_extract anywhere

Git Worktree Isolation

Enable isolated git worktrees for running multiple agents in parallel on the same repo:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

When enabled, each CLI session creates a fresh worktree under `.worktrees/` with its own branch. Agents can edit files, commit, push, and create PRs without interfering with each other. Clean worktrees are removed on exit; dirty ones are kept for manual recovery.

By default the new worktree branches from the **freshly-fetched remote tip** (the current branch's upstream, otherwise the remote's default branch) so it starts current with the project rather than from the local clone's possibly-stale `HEAD`. This keeps a PR's diff scoped to the actual change instead of inheriting whatever the local clone was behind by. Set `worktree_sync: false` to branch from local `HEAD` instead — useful offline, or when you deliberately want the clone's exact current state as the base. If the remote can't be reached, it falls back to local `HEAD` automatically.

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

You can also list gitignored files to copy into worktrees via `.worktreeinclude` in your repo root:

.worktreeinclude

.env .venv/ node_modules/

### Context Compression

Hermes automatically compresses long conversations to stay within your model's context window. The compression summarizer is a separate LLM call — you can point it at any provider or endpoint.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

### Full reference

```yaml compression: enabled: true # Toggle compression on/off progress_notices: false # Opt-in: deliver routine compression progress notices to chat platforms — see below threshold: 0.50 # Compress at this % of context limit threshold_tokens: null # Absolute token cap (optional) — takes lower of ratio vs absolute target_ratio: 0.20 # Fraction of threshold to preserve as recent tail protect_last_n: 20 # Min recent messages to keep uncompressed protect_first_n: 3 # Non-system head messages pinned across compactions (0 = pin nothing) idle_compact_after_seconds: 0 # Opt-in idle compaction (0 = disabled) — see below hygiene_hard_message_limit: 5000 # Gateway safety valve — see below hygiene_timeout_seconds: 30 # Max seconds of NO summary-model output before hygiene compression is cut off hygiene_total_ceiling_seconds: 600 # Absolute cap on the hygiene wait even while tokens are still streaming hygiene_failure_cooldown_seconds: 300 # Skip repeated failed hygiene attempts for this session proactive_prune_tokens: 0 # Opt-in tokens trigger for the no-LLM tool-result prune (0 = off; see below) proactive_prune_min_result_chars: 8000 # Prune's summarize pass only touches tool results larger than this (clamped >= 200) proactive_prune_min_reclaim_tokens: 4096 # Prune only commits when it reclaims at least this many tokens (0 = commit any)

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

### The summarization model/provider is configured under auxiliary:

auxiliary: compression: model: "" # Empty = use main chat model. Override with e.g. "google/gemini-3-flash-preview" for cheaper/faster compression. provider: "auto" # Provider: "auto", "openrouter", "nous", "codex", "main", etc. base_url: null # Custom OpenAI-compatible endpoint (overrides provider) 

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Common setups

Uses your main provider and main model. Override per-task (e.g. auxiliary.compression.provider: openrouter + model: google/gemini-2.5-flash) if you want compression on a cheaper model than your main chat model.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

compression:
  enabled: true
  threshold: 0.50

auxiliary:
  compression:
    provider: nous
    model: gemini-3-flash

auxiliary:
  compression:
    model: glm-4.7
    base_url: https://api.z.ai/api/coding/paas/v4

How the three knobs interact

:::warning Summary model context length requirement The summary model must have a context window at least as large as your main agent model's. The compressor sends the full middle section of the conversation to the summary model — if that model's context window is smaller than the main model's, the summarization call will fail with a context length error. When this happens, the middle turns are dropped without a summary, losing conversation context silently. If you override the model, verify its context length meets or exceeds your main model's. :::

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

auxiliary.compression.provider	auxiliary.compression.base_url	Result
auto (default)	not set	Auto-detect best available provider
nous / openrouter / etc.	not set	Force that provider, use its auth
any	set	Use the custom endpoint directly (provider ignored)

Context Engine

The context engine controls how conversations are managed when approaching the model's token limit. The built-in compressor engine uses lossy summarization (see Context Compression). Plugin engines can replace it with alternative strategies.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

context:
  engine: "compressor"    # default — built-in lossy summarization

context:
  engine: "lcm"          # must match the plugin's name

Iteration Budget

When the agent is working on a complex task with many tool calls, it can burn through its iteration budget (default: 500 turns). Hermes does not inject mid-task pressure warnings — earlier builds warned the model at 70%/90% budget, which caused models to abandon complex tasks prematurely and was removed in April 2026.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

agent:
  max_turns: 500               # Max iterations per conversation turn (default: 500)
  api_max_retries: 3           # Retries per provider before fallback engages (default: 3)

Standing Goals (/goal)

When a standing goal is active, Hermes judges whether each assistant response satisfies it. If not, it feeds a continuation prompt back into the same session and keeps working until the goal is done, the turn budget is exhausted, or the user pauses/clears it. The turn budget is the real backstop — judge failures fail open (continue) so a flaky judge never wedges progress.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

goals:
  max_turns: 20   # Max continuation turns before Hermes auto-pauses the goal (default: 20)

API Timeouts

Hermes has separate timeout layers for streaming, plus a stale detector for non-streaming calls. The stale detectors auto-adjust for local providers only when you leave them at their implicit defaults.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Timeout	Default	Local providers	Config / env
Socket read timeout	120s	Auto-raised to 1800s	HERMES_STREAM_READ_TIMEOUT
Stale stream detection	180s	Auto-disabled	HERMES_STREAM_STALE_TIMEOUT
Stale non-stream detection	300s	Auto-disabled when left implicit	providers.<id>.stale_timeout_seconds or HERMES_API_CALL_STALE_TIMEOUT
API call (non-streaming)	1800s	Unchanged	providers.<id>.request_timeout_seconds / timeout_seconds or HERMES_API_TIMEOUT

Context Pressure Warnings

Separate from iteration budget pressure, context pressure tracks how close the conversation is to the compaction threshold — the point where context compression fires to summarize older messages. This helps both you and the agent understand when the conversation is getting long.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Progress	Level	What happens
≥ 60% to threshold	Info	CLI shows a cyan progress bar; gateway sends an informational notice
≥ 85% to threshold	Warning	CLI shows a bold yellow bar; gateway warns compaction is imminent

◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

Credential Pool Strategies

When you have multiple API keys or OAuth tokens for the same provider, configure the rotation strategy:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

credential_pool_strategies:
  openrouter: round_robin    # cycle through keys evenly
  anthropic: least_used      # always pick the least-used key

실습 체크리스트

1. 공식 문서와 설치된 Hermes 버전을 대조합니다.
2. 관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
3. Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
4. 시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

hermes config              # View current configuration
hermes config edit         # Open config.yaml in your editor
hermes config get KEY      # Print a resolved value
hermes config set KEY VAL  # Set a specific value
hermes config unset KEY    # Remove a user-set value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

# Examples:
hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

updates:
  pre_update_backup: quick       # quick (state snapshot, default) | full (snapshot + HERMES_HOME zip) | off
  backup_keep: 5                 # Keep this many full pre-update backup zips
  non_interactive_local_changes: stash  # stash | discard

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Gateway/cron working directory (CLI always uses launch dir)
  timeout: 180      # Per-command timeout in seconds
  home_mode: auto   # auto | real | profile — subprocess HOME policy
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

terminal:
  backend: local

terminal:
  home_mode: profile

from pathlib import Path

hermes_home = Path(os.environ["HERMES_HOME"])
real_home = Path(os.environ.get("HERMES_REAL_HOME", os.environ["HOME"]))

관련 링크

• 공식 원문: user-guide/configuration
• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.