Конфигурация

Все настройки хранятся в каталоге ~/.hermes/ для быстрого доступа.

Структура каталогов

~/.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 set KEY VAL  # Set a specific value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

# Examples:
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to.env
```:::совет
Команда «hermes config set» автоматически направляет значения в нужный файл — ключи API сохраняются в «.env», все остальное — в «config.yaml».</div>
## Приоритет конфигурации

Настройки выполняются в следующем порядке (сначала высший приоритет):

1. **Аргументы CLI** — например, `hermeschat --model anthropic/claude-sonnet-4` (переопределение для каждого вызова)
2. **`~/.hermes/config.yaml`** — основной файл конфигурации для всех несекретных настроек.
3. **`~/.hermes/.env`** — запасной вариант для переменных окружения; **требуется** для секретов (ключи API, токены, пароли)
4. **Встроенные настройки по умолчанию** — жестко запрограммированные безопасные настройки по умолчанию, когда больше ничего не установлено.:::информация Практическое правило
Секреты (ключи API, токены ботов, пароли) хранятся в `.env`. Все остальное (модель, серверная часть терминала, настройки сжатия, ограничения памяти, наборы инструментов) находится в `config.yaml`. Когда оба установлены, `config.yaml` выигрывает для несекретных настроек.</div>
## Замена переменной среды

Вы можете ссылаться на переменные среды в `config.yaml`, используя синтаксис `${VAR_NAME}`:
```yaml
auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Несколько ссылок в одном значении работают: url: "${HOST}:${PORT}". Если ссылочная переменная не установлена, заполнитель сохраняется дословно (${UNDEFINED_VAR} остается как есть). Поддерживается только синтаксис ${VAR} — чистый $VAR не расширяется.

Информацию о настройке поставщика ИИ (OpenRouter, Anthropic, Copilot, пользовательских конечных точек, автономных LLM, резервных моделей и т. д.) см. в разделе Поставщики ИИ.

Тайм-ауты поставщика

Вы можете установить providers.<id>.request_timeout_секундs для таймаута запроса на уровне всего провайдера, а также providers.<id>.models.<model>.timeout_секундs для переопределения для конкретной модели. Применяется к основному клиенту очереди на каждом транспорте (OpenAI-wire, собственный Anthropic, Anthropic-совместимый), резервной цепочке, перестраивается после ротации учетных данных и (для OpenAI-wire) kwarg таймаута для каждого запроса — поэтому настроенное значение выигрывает у устаревшей переменной env HERMES_API_TIMEOUT.

Вы также можете установить providers.<id>.stale_timeout_секундs для непотокового детектора устаревших вызовов, а также providers.<id>.models.<model>.stale_timeout_секундs для переопределения для конкретной модели. Это превосходит устаревшую переменную окружения HERMES_API_CALL_STALE_TIMEOUT.

Если эти значения не заданы, сохраняются устаревшие настройки по умолчанию (HERMES_API_TIMEOUT=1800, HERMES_API_CALL_STALE_TIMEOUT=300, родные Anthropic 900). В настоящее время не подключен к AWS Bedrock (пути SDK Bedrock_converse и AnthropicBedrock используют boto3 со своей собственной конфигурацией тайм-аута). См. пример с комментариями в cli-config.yaml.example.

Конфигурация серверной части терминала

Hermes поддерживает семь серверных частей терминала. Каждый из них определяет, где фактически выполняются команды оболочки агента — ваш локальный компьютер, контейнер Docker, удаленный сервер через SSH, модальная облачная песочница, рабочее пространство Daytona, Vercel Sandbox или контейнер Singularity/Apptainer.

terminal:
  backend: local    # local | docker | ssh | modal | daytona | vercel_sandbox | singularity
  cwd: "."          # Gateway/cron working directory (CLI always uses launch dir)
  timeout: 180      # Per-command timeout in seconds
  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

Для облачных песочниц, таких как Modal, Daytona и Vercel Sandbox, «container_persistent: true» означает, что Hermes попытается сохранить состояние файловой системы во время воссоздания песочницы. Это не гарантирует, что та же действующая песочница, PID-пространство или фоновые процессы будут работать позже.

Обзор серверной части

Локальный бэкэнд

Значение по умолчанию. Команды выполняются непосредственно на вашем компьютере без изоляции. Никакой специальной настройки не требуется.

terminal:
  backend: local
```:::предупреждение
Агент имеет тот же доступ к файловой системе, что и ваша учетная запись пользователя. Используйте «инструменты Hermes», чтобы отключить ненужные инструменты, или переключитесь на Docker для изолированной программной среды.</div>
### Серверная часть Docker

Запускает команды внутри контейнера Docker с усилением безопасности (отменены все возможности, нет повышения привилегий, ограничения PID).

**Один постоянный контейнер, а не для каждой команды.** Hermes запускает ОДИН долгоживущий контейнер при первом использовании и маршрутизирует каждый вызов терминала, файла и `execute_code` через `docker exec` в тот же контейнер — между сеансами, подагентами `/new`, `/reset` и `delegate_task` - на протяжении всего времени существования процесса Hermes. Изменения рабочего каталога, установленные пакеты и файлы в `/workspace` переносятся от одного вызова инструмента к другому, как в локальной оболочке. Контейнер останавливается и удаляется при выключении. Подробности см. в разделе **Жизненный цикл контейнера** ниже.
```yaml
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:              # Env vars to forward into container
    - "GITHUB_TOKEN"
  docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   #:ro for read-only

  # 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 across sessions

Требования: Docker Desktop или Docker Engine установлены и работают. Hermes исследует $PATH, а также общие места установки macOS (/usr/local/bin/docker, /opt/homebrew/bin/docker, пакет приложений Docker Desktop). Podman поддерживается «из коробки»: установите HERMES_DOCKER_BINARY=podman (или полный путь), чтобы принудительно установить его, когда оба установлены.

Жизненный цикл контейнера: Hermes повторно использует один долгоживущий контейнер (docker run -d... Sleep 2h) для каждого вызова терминала и файлового инструмента, между сеансами, субагентами /new, /reset и delegate_task в течение всего времени существования процесса Hermes. Команды запускаются через docker exec с оболочкой входа в систему, поэтому изменения рабочего каталога, установленные пакеты и файлы в /workspace сохраняются от одного вызова инструмента к другому. Контейнер останавливается и удаляется при выключении Гермеса (или когда его забирает холостой ход).

Параллельные подагенты, порожденные через delegate_task(tasks=[...]), совместно используют этот контейнер — одновременные мутации cd, env и записи по одному и тому же пути будут конфликтовать. Если субагенту требуется изолированная песочница, он должен зарегистрировать переопределение образа для каждой задачи через register_task_env_overrides(), что RL и среды тестирования (TerminalBench2, HermesSweEnv и т. д.) делают автоматически для своих образов Docker для каждой задачи.

Усиление безопасности: - --cap-drop ALL, обратно добавлены только DAC_OVERRIDE, CHOWN, FOWNER - --security-opt no-new-privileges - --pids-limit 256 - tmpfs с ограниченным размером для /tmp (512 МБ), /var/tmp (256 МБ), /run (64 МБ)

Пересылка учетных данных: Переменные Env, перечисленные в docker_forward_env, сначала разрешаются из среды вашей оболочки, а затем из ~/.hermes/.env. Навыки также могут объявлять required_environment_variables, которые автоматически объединяются.

SSH-бэкэнд

Запускает команды на удаленном сервере через SSH. Использует ControlMaster для повторного использования соединения (поддержание активности в режиме ожидания в течение 5 минут). Постоянная оболочка включена по умолчанию — состояние (cwd, env vars) сохраняется при выполнении команд.

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

Необязательно:

Как это работает: Подключается во время инициализации с помощью BatchMode=yes и StrictHostKeyChecking=accept-new. Постоянная оболочка поддерживает работу одного процесса bash -l на удаленном хосте, обмениваясь данными через временные файлы. Команды, которым требуются stdin_data или sudo, автоматически переходят в одноразовый режим.

Модальный бэкэнд

Запускает команды в облачной песочнице Modal. Для каждой задачи выделяется изолированная виртуальная машина с настраиваемым процессором, памятью и диском. Файловую систему можно сделать снимок/восстановить между сеансами.

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

Обязательно: либо переменные среды MODAL_TOKEN_ID + MODAL_TOKEN_SECRET, либо файл конфигурации ~/.modal.toml.

Постоянство. Если этот параметр включен, файловая система песочницы создается при очистке и восстанавливается при следующем сеансе. Снимки отслеживаются в ~/.hermes/modal_snapshots.json. При этом сохраняется состояние файловой системы, а не текущие процессы, пространство PID или фоновые задания.

Файлы учетных данных: Автоматически монтируются из ~/.hermes/ (токены OAuth и т. д.) и синхронизируются перед каждой командой.

Серверная часть Daytona

Выполняет команды в управляемой рабочей области Daytona. Поддерживает остановку/возобновление для постоянства.

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

Обязательно: переменная среды DAYTONA_API_KEY.

Постоянство. Если этот параметр включен, песочницы останавливаются (не удаляются) при очистке и возобновляются при следующем сеансе. Имена песочниц следуют шаблону hermes-{task_id}.

Ограничение по диску: Daytona устанавливает максимальный размер в 10 ГиБ. Запросы выше этого уровня ограничиваются предупреждением.

Серверная часть песочницы Vercel

Выполняет команды в облачной микроVM Vercel Sandbox. Hermes использует обычные поверхности терминала и файлового инструмента; инструментов Vercel для работы с моделями нет.

terminal:
  backend: vercel_sandbox
  vercel_runtime: node24          # node24 | node22 | python3.13
  cwd: /vercel/sandbox            # default workspace root
  container_persistent: true      # Snapshot/restore filesystem
  container_disk: 51200           # Shared default only; custom disk is unsupported

Требуется установка. Установите дополнительный SDK:

pip install 'hermes-agent[vercel]'

Требуемая аутентификация: Настройте аутентификацию по токену доступа со всеми тремя параметрами: VERCEL_TOKEN, VERCEL_PROJECT_ID и VERCEL_TEAM_ID. Это поддерживаемая настройка для развертываний и обычных длительных процессов Hermes на Render, Railway, Docker и подобных хостах.

Для разовых местных разработок Hermes также принимает недолговечные токены Vercel OIDC:

VERCEL_OIDC_TOKEN="$(vc project token <project-name>)" hermes chat

В связанном каталоге проекта Vercel вы можете опустить имя проекта:

VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat

Токены OIDC недолговечны и не должны использоваться в качестве документированного пути развертывания.

Среда выполнения: terminal.vercel_runtime поддерживает node24, node22 и python3.13. Если этот параметр не установлен, по умолчанию для Hermes используется node24.

Постоянство: Если container_persistent: true, Hermes делает снимок файловой системы песочницы во время очистки и восстанавливает более позднюю песочницу для той же задачи из этого снимка. Содержимое снимка может включать синхронизированные с Hermes учетные данные, навыки и файлы кэша, которые были скопированы в песочницу. При этом сохраняется только состояние файловой системы; он не сохраняет идентичность активной песочницы, пространство PID, состояние оболочки или запущенные фоновые процессы.

Фоновые команды: terminal(background=true) использует общий нелокальный фоновый процесс обработки Hermes. Вы можете запускать, опрашивать, ждать, просматривать журналы и завершать процессы с помощью обычного инструмента обработки, пока «песочница» жива. Hermes не обеспечивает встроенное восстановление отсоединенного процесса Vercel после очистки или перезапуска.

Размер диска. Vercel Sandbox в настоящее время не поддерживает ручку ресурса Hermes container_disk. Оставьте container_disk неустановленным или оставьте общее значение по умолчанию 51200; значения, отличные от значений по умолчанию, не позволяют выполнить диагностику и создание серверной части, а не игнорируются автоматически.

Серверная часть Singularity/Apptainer

Запускает команды в контейнере Singularity/Apptainer. Предназначен для кластеров HPC и общих компьютеров, где Docker недоступен.

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

Требования: apptainer или singularity двоичный файл в $PATH.

Обработка изображений. URL-адреса Docker (docker://...) автоматически преобразуются в файлы SIF и кэшируются. Существующие файлы .sif используются напрямую.

Каталог временных файлов: Решается в следующем порядке: TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent (соглашение HPC) → ~/.hermes/sandboxes/singularity.

Изоляция: используется --containall --no-home для полной изоляции пространства имен без монтирования домашнего каталога хоста.

Распространенные проблемы с серверной частью терминала

Если команды терминала немедленно завершаются сбоем или инструмент терминала сообщается как отключенный:

• Локальный — особых требований нет. Самый безопасный вариант по умолчанию при начале работы.
• Docker — запустите docker version, чтобы убедиться, что Docker работает. Если это не помогло, исправьте Docker или hermes config set Terminal.backend local.
• SSH — должны быть установлены оба TERMINAL_SSH_HOST и TERMINAL_SSH_USER. Hermes регистрирует явную ошибку, если что-то отсутствует.
• Модальный — требуется переменная окружения MODAL_TOKEN_ID или ~/.modal.toml. Запустите «Гермес доктор», чтобы проверить.
• Daytona — требуется DAYTONA_API_KEY. Daytona SDK управляет настройкой URL-адреса сервера.
• Singularity — требуется apptainer или singularity в $PATH. Обычно используется в кластерах HPC.

Если у вас есть сомнения, установите для terminal.backend значение local и убедитесь, что команды сначала выполняются там.

Синхронизация файлов между удаленным компьютером и хостом при демонтаже

Для бэкэндов SSH, Modal и Daytona (везде, где рабочее дерево агента находится на компьютере, отличном от хоста, на котором работает Hermes), Hermes отслеживает файлы, к которым обращался агент, внутри удаленной песочницы и при удалении сеанса/очистке песочницы синхронизирует измененные файлы обратно на хост в ~/.hermes/cache/remote-syncs/<session-id>/.

• Срабатывает при: закрытии сеанса, /new, /reset, тайм-ауте сообщения шлюза, завершении субагента delegate_task, когда дочерний элемент использовал удаленный бэкэнд.
• Охватывает все дерево, измененное агентом, а не только файлы, которые он явно открыл. Все добавления, изменения и удаления фиксируются.
• Удаленная песочница могла быть уже разобрана к тому времени, как вы отправитесь ее искать; локальная копия ~/.hermes/cache/remote-syncs/… является достоверной записью того, что изменил агент.
• Большие двоичные выходные данные (контрольные точки модели, наборы необработанных данных) ограничены размером — синхронизация пропускает файлы по file_sync_max_mb (по умолчанию 100). Ударьте по этому поводу, если ожидаете возвращения более крупных артефактов.

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

Таким образом вы восстанавливаете результаты из эфемерных облачных песочниц, которые уничтожаются после завершения сеанса, без необходимости явно указывать агенту scp или modal Volume put для каждого артефакта.

Монтирование томов Docker

При использовании бэкэнда Docker docker_volumes позволяет вам делиться каталогами хоста с контейнером. Каждая запись использует стандартный синтаксис Docker -v: host_path:container_path[:options].

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

Это полезно для: - Предоставление файлов агенту (наборы данных, конфигурации, справочный код) - Получение файлов от агента (сгенерированный код, отчеты, экспорт) - Общие рабочие пространства, где и вы, и агент имеют доступ к одним и тем же файлам.

Если вы используете шлюз обмена сообщениями и хотите, чтобы агент отправлял сгенерированные файлы через MEDIA:/..., отдайте предпочтение выделенному, видимому хосту экспортному монтированию, например /home/user/.hermes/cache/documents:/output.

• Записывайте файлы внутри Docker в /output/... – Укажите путь хоста в MEDIA:, например: МЕДИА:/home/user/.hermes/cache/documents/report.txt
• Не не генерировать /workspace/... или /output/..., если только этот точный путь также не указан. существует для процесса шлюза на хосте:::предупреждение Дублирующиеся ключи YAML автоматически переопределяют предыдущие. Если у вас уже есть docker_volumes: блокирует новые подключения в один список вместо добавления еще один ключ docker_volumes: позже в файле.