Урок 16: Развёртывание в Docker

С возвращением, исследователи Hermes! В прошлом уроке мы научились запускать Hermes Agent прямо на наших машинах. Сегодня мы выходим на новый уровень: помещаем Hermes внутрь Docker-контейнера. Это настоящий прорыв для поддержания вашего окружения в чистоте, портативности и лёгкости обновления.

Два способа, которыми Docker встречается с Hermes

Прежде чем мы углубимся, важно понять, что Docker и Hermes Agent могут работать вместе двумя разными способами:

Запуск Hermes в Docker – сам агент живёт внутри контейнера. Именно на этом мы сосредоточимся сегодня.
Docker как терминальный бэкенд – Hermes работает на вашем хосте, но каждая команда, которую он выполняет, происходит внутри постоянной Docker-песочницы. Это отлично подходит для безопасности и изоляции, но это тема для другого дня.

Сегодня мы полностью за вариант 1. Прелесть этого подхода в том, что все ваши данные — конфигурация, ключи API, сессии, навыки и воспоминания — живут в одной директории на вашем хосте, смонтированной в контейнер по пути /opt/data. Сам контейнер не хранит состояние, поэтому вы можете подтянуть новую версию и обновиться без потери чего-либо.

Быстрый старт: ваш первый контейнер

Если вы совсем новичок в Hermes, самый простой путь — создать директорию данных и запустить мастер настройки в интерактивном режиме. Он проведёт вас через ввод ключей API и сохранит их в ~/.hermes/.env.

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Предостережение: избегайте браузерных VPS-консолей (например, Hetzner Cloud) для этих команд. Они часто искажают специальные символы, такие как :, @ и =, что может незаметно повредить ваши аргументы docker run. Всегда подключайтесь по SSH (ssh root@<host>) для безопасного копирования и вставки. Если вам всё же приходится использовать браузерную консоль, вводите команды вручную и перепроверяйте каждый символ.

Как только вы окажетесь в мастере, настоятельно рекомендуется настроить чат-систему (Telegram, Discord и т.д.), чтобы вашему шлюзу было куда отправлять сообщения.

Запуск в режиме шлюза

После настройки вам захочется запустить Hermes как постоянный фоновый шлюз. Именно так он подключается к вашим чат-платформам и остаётся в живых 24/7.

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Флаг -p 8642:8642 открывает OpenAI-совместимый API-сервер шлюза и его эндпоинт для проверки здоровья. Он необязателен, если вы используете только чат-платформы, но обязателен, если вы хотите, чтобы панель управления или внешние инструменты могли обращаться к вашему шлюзу.

Вот классная новая функция: внутри официального Docker-образа gateway run теперь автоматически контролируется s6-overlay. Это означает, что если процесс шлюза упадёт, он будет перезапущен в течение нескольких секунд без потери контейнера. Вы увидите хлебную крошку в docker logs, подтверждающую обновление. Если вы хотите старое поведение (когда контейнер завершается вместе со шлюзом), передайте --no-supervise или установите HERMES_GATEWAY_NO_SUPERVISE=1. Для продакшена контролируемый по умолчанию режим строго лучше.

Открытие API-сервера

По умолчанию API-сервер ограничен параметром API_SERVER_ENABLED=true. Чтобы открыть его за пределы 127.0.0.1 внутри контейнера, вам нужно задать несколько переменных окружения:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

API_SERVER_KEY должен быть не короче 8 символов — сгенерируйте его с помощью openssl rand -hex 32. Важно: открытие любого порта на машине, доступной из интернета, — это риск для безопасности. Не делайте этого, если вы полностью не понимаете последствий.

Запуск панели управления

Хотите веб-панель для мониторинга вашего шлюза? Установите HERMES_DASHBOARD=1 и откройте порт 9119:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Панель также контролируется s6, поэтому она автоматически перезапускается в случае сбоя. Её вывод идёт в docker logs <container>.

Примечание о защитных ограничителях цикла инструментов

Для автономных шлюзов рассмотрите возможность включения жёстких остановок для защитных ограничителей цикла инструментов. По умолчанию стоит false, что нормально для интерактивных сессий, где человек может видеть предупреждения. Но в автономном шлюзе агент, застрявший в цикле, может никогда не остановиться. Добавьте это в config.yaml вашего профиля:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Подводим итоги

Вот и вся история с развёртыванием в Docker! Теперь у вас есть контейнер без состояния, который легко обновлять, а все ваши данные надёжно смонтированы на хосте. В следующем уроке мы более подробно рассмотрим панель управления. А пока — приятного контейнеризирования!