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

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

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

~/.hermes/
├── config.yaml     # Настройки (модель, терминал, TTS, сжатие и т.д.)
├──.env            # Ключи API и секреты
├── auth.json       # Учётные данные OAuth-провайдеров (Nous Portal и др.)
├── SOUL.md         # Основная идентичность агента (слот №1 в системном промпте)
├── memories/       # Постоянная память (MEMORY.md, USER.md)
├── skills/         # Навыки, созданные агентом (управление через skill_manage)
├── cron/           # Запланированные задания
├── sessions/       # Сессии шлюза
└── logs/           # Журналы (errors.log, gateway.log — секреты автоматически скрываются)

Управление конфигурацией

hermes config              # Просмотр текущей конфигурации
hermes config edit         # Открыть config.yaml в редакторе
hermes config set KEY VAL  # Установить конкретное значение
hermes config check        # Проверить отсутствующие опции (после обновлений)
hermes config migrate      # Интерактивно добавить отсутствующие опции

# Примеры:
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Сохраняется в.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. **Встроенные значения по умолчанию** — жёстко заданные безопасные значения, если ничего другого не установлено.<div class="admonition admonition-info"><p class="admonition-title">ℹ️ Info</p> Правило большого пальца
Секреты (ключи 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 не раскрывается.

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

Тайм-ауты провайдера

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

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

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

Конфигурация бэкенда терминала

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

terminal:
  backend: local    # local | docker | ssh | modal | daytona | vercel_sandbox | singularity
  cwd: "."          # Рабочий каталог для шлюза/cron (CLI всегда использует каталог запуска)
  timeout: 180      # Тайм-аут команды в секундах
  env_passthrough: []  # Имена переменных окружения для передачи в изолированное выполнение (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Образ контейнера для Singularity
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Образ контейнера для Modal
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Образ контейнера для Daytona

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

Обзор бэкендов

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

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

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

Выполняет команды внутри контейнера 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  # Монтировать каталог запуска в /workspace
  docker_run_as_host_user: false   # См. «Запуск контейнера от пользователя хоста» ниже
  docker_forward_env:              # Переменные окружения для передачи в контейнер
    - "GITHUB_TOKEN"
  docker_volumes:                  # Монтирование каталогов хоста
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   #:ro для только чтения

  # Ограничения ресурсов
  container_cpu: 1                 # Ядра ЦП (0 = без ограничений)
  container_memory: 5120           # МБ (0 = без ограничений)
  container_disk: 51200            # МБ (требуется overlay2 на XFS+pquota)
  container_persistent: true       # Сохранять /workspace и /root между сессиями

Требования: 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 включается от одного инструмента вызова к следующему. Контейнер останавливается и удаляется по завершении работ Hermes (или когда сборщик бездействия забирает его).

Параллельные подагенты, порождённые через delegate_task(tasks=[...]), используют этот контейнер — одновременные cd, мутации окружения и записи в одном и тот же путь могут определять. Если подагенту нужна изолированная песочница, он должен зарегистрировать переопределение образа для каждой задачи через 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 МБ)

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

Бэкенд SSH

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

terminal:
  backend: ssh
  persistent_shell: true           # Сохранять долгоживущую сессию bash (по умолчанию: 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                 # Ядра ЦП
  container_memory: 5120           # МБ (5 ГБ)
  container_disk: 51200            # МБ (50 ГБ)
  container_persistent: true       # Снимок/восстановление файловой системы

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

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

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

Бэкенд Дайтона

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

terminal:
  backend: daytona
  container_cpu: 1                 # Ядра ЦП
  container_memory: 5120           # МБ → преобразуется в ГиБ
  container_disk: 10240            # МБ → преобразуется в ГиБ (макс. 10 ГиБ)
  container_persistent: true       # Остановить/возобновить вместо удаления

Требуется: Переменная окружения DAYTONA_API_KEY.

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

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

Бэкенд Vercel Sandbox

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

terminal:
  backend: vercel_sandbox
  vercel_runtime: node24          # node24 | node22 | python3.13
  cwd: /vercel/sandbox            # Корень рабочей области по умолчанию
  container_persistent: true      # Снимок/восстановление файловой системы
  container_disk: 51200           # Только общее значение по умолчанию; пользовательский диск не поддерживается

Необходимая установка: Установите дополнительный SDK:

pip install 'hermes-agent[vercel]'

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

Для разовой локальной разработки Hermes также использует соответствующие токены OIDC Vercel:

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, навыки и денежные средства, которые были скопированы в песочницу. Это сохраняет только состояние файловой системы; оно не сохраняет идентичность активной песочницы, пространства PID, состояния или работы фоновых процессов.

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

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

Бэкенд Singularity/Apptainer

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

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # Ядра ЦП
  container_memory: 5120           # МБ
  container_persistent: true       # Перезаписываемый оверлей сохраняется между сессиями

Требования: Бинарный файл 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. Гермес чётко сообщает о деньгах, если что-то отсутствует.
• Modal — Требуется переменное окружение MODAL_TOKEN_ID или ~/.modal.toml. Запустите hermes Doctor для проверки.
• Daytona — Требуется DAYTONA_API_KEY. SDK Daytona сам проектирует конфигурацию 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     # по умолчанию — синхронизировать файлы размером до 100 МБ каждый
  file_sync_enabled: true   # по умолчанию — установите false, чтобы полностью пропустить синхронизацию

Таким образом, вы восстанавливаете результаты из эфемерных облачных песочниц, которые уничтожаются после завершения сеанса, без необходимости указания агенту явно 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"   # Чтение-запись (по умолчанию)
    - "/home/user/datasets:/data:ro"              # Только чтение
    - "/home/user/.hermes/cache/documents:/output" # Экспорт, видимый шлюзу

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

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

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