Hermes Agent на VPS в Docker: установка и постоянная работа

Инструкция рассчитана на сервер с уже установленными Docker Engine и Compose. Она не устанавливает Docker за вас и не настраивает удалённый рабочий стол. Команды ниже сверены с официальной документацией, исходниками и метаданными опубликованного образа на 8 октября 2026 года. Запуск на отдельном VPS, перезагрузку сервера и восстановление из копии при подготовке материала не выполняли.

Где вы сейчас

• VPS ещё не подготовлен. Сначала установите Docker по инструкции для вашей серверной ОС и проверьте Compose. Дальнейшие шаги рассчитаны на сервер, где эта проверка пройдена.
• Docker работает, Hermes ещё нет. Создайте отдельный каталог и пройдите шаги установки ниже.
• Hermes работает на другой машине. Сначала сохраните его данные и определите, какие настройки относятся к прежнему окружению. Не копируйте в новый каталог лишние серверные доступы.
• Контейнер уже запущен, но бот не отвечает. Перейдите к разделам проверки и ошибок. Второй gateway поверх тех же данных может добавить ещё одну проблему.

Если пока непонятно, какое действие агент должен выполнять для компании, начните с постановки задачи для ИИ-агента. Перенос на VPS решает вопрос размещения процесса. Доступы, исходные документы и критерий правильного результата задаются отдельно.

Какой Docker-образ использовать для Hermes Agent

В официальной документации есть два сценария. В первом сам Hermes Agent находится в контейнере. Во втором агент установлен на основной машине, а Docker используется как отдельная песочница для терминальных команд. Ниже разобран первый сценарий: один серверный gateway в контейнере, который обращается к выбранному провайдеру модели.

Для такого размещения не требуется добавлять /var/run/docker.sock. Этот файл даёт доступ к Docker-движку VPS. Его подключение существенно расширяет полномочия контейнера и не входит в показанную конфигурацию. Терминальный режим local внутри контейнера означает выполнение команд в этом контейнере. Если вам нужен отдельный Docker backend для инструментов, потребуется отдельная конфигурация с проверкой доступов и путей.

У образа существуют каналы: latest и stable для принятой стабильной сборки, main для разработки, а также версионные теги. Тег может переключиться на новую сборку. Digest фиксирует содержимое и поэтому удобен, когда агент уже выполняет постоянную работу.

На дату проверки latest указывает на multiarch-образ с Linux-вариантами amd64 и arm64. В метаданных варианта amd64 указана исходная ревизия 749220ef0007f8d87bd1531f1c24b0fe93816385. Сборка опубликована 24 сентября. Проверенная ветка main уже содержит изменения от 7 октября - считать их автоматически установленными в стабильном образе нельзя. Это видно при сопоставлении метаданных тега и Dockerfile его исходной ревизии.

По Dockerfile этой ревизии образ содержит Debian 13.4, окружение Python на базе 3.13, Node.js 26, Git, OpenSSH-клиент, Docker CLI, FFmpeg, ripgrep и браузерную сборку Playwright Chromium headless shell. В него входят зависимости Hermes и служебный процесс s6-overlay. Наличие Docker CLI не означает, что внутри есть работающий Docker-движок. Образ также не устанавливает локальную языковую модель: её подключают как отдельный сервис или используют доступного провайдера.

Состав нового образа может измениться. Например, нынешний Dockerfile ветки main уже использует другой способ подготовки браузера и Python 3.14. Поэтому инструкции с точными версиями зависимостей надо сверять с ревизией выбранного образа. Для запуска Hermes Agent в режиме gateway не нужно повторять установку Python и Node на VPS: они уже входят в образ.

1. Проверить сервер и подготовить данные

   Проверьте Docker и Compose, затем создайте отдельный каталог data под обычным пользователем сервера.

2. Закрепить образ и создать Compose

   Выберите digest официального образа и подключите постоянный каталог к /opt/data в одном сервисе gateway.

3. Настроить модель и канал общения

   Выполните setup в одноразовом контейнере до постоянного запуска и ограничьте разрешённых пользователей.

4. Запустить постоянный gateway

   Укажите рабочую папку под /opt/data и запустите сервис командой Compose up -d.

5. Проверить ответ и сохранение данных

   Проверьте gateway, контрольное обращение и файл, затем повторите проверку после согласованного рестарта.

Шаг 1. Подготовить VPS и постоянный каталог

VPS - виртуальный сервер, который продолжает работать после закрытия вашего ноутбука. Для этой схемы нужен Linux и Docker Engine с модулем Compose. Проверьте их из той учётной записи, которая будет управлять сервисом:

docker version
docker compose version
uname -m
id -u
id -g

Команда docker version должна показать сведения и о клиенте, и о сервере Docker. Если виден только клиент с ошибкой подключения, переходить к запуску Hermes рано. Причиной может быть остановленный Docker или отсутствие у пользователя доступа к нему. Установку и исправление самого движка выполняйте по документации выбранной ОС.

По ресурсам документация Hermes указывает минимум 1 ГБ оперативной памяти и одно ядро CPU, а рекомендация проекта - 2-4 ГБ и два ядра. Это ориентиры проекта; собственный замер для этой инструкции не проводили. Браузерные задачи расходуют дополнительную память; число одновременных задач также влияет на нагрузку. Размер каталога данных в таблице проекта не равен полному диску VPS: место потребуется ещё для образов, слоёв Docker, журналов и резервных копий.

Дальше предполагается, что вы работаете под обычным пользователем. В проверенном образе UID и GID должны находиться в диапазоне 1-65534; нулевые значения для этой схемы не подходят. Каталог data размещайте на локальном диске Linux VPS. Сетевое хранилище NFS/SMB требует отдельной проверки режима и блокировок SQLite. Если вошли как root, выберите отдельного пользователя для данных и выполнения команд. Подстановка root в HERMES_UID противоречит обычной схеме образа: рабочий gateway по умолчанию не должен запускаться от root.

Подготовьте каталог в домашней папке этого пользователя:

mkdir -p "$HOME/hermes-vps/data/workspace"
chmod 700 "$HOME/hermes-vps/data"
printf 'HERMES_UID=%s\nHERMES_GID=%s\n' \
  "$(id -u)" "$(id -g)" > "$HOME/hermes-vps/.env"

Файл .env рядом с будущим Compose содержит только два несекретных числа. У Hermes будет свой файл data/.env с доступами к провайдерам и мессенджеру. Не смешивайте эти файлы. Если каталог уже существовал, сначала проверьте его владельца и содержимое: приведённая команда рассчитана только на новую установку, для исправления чужого сервиса она не предназначена.

Внутри образа процесс работает от пользователя hermes, чей исходный UID равен 10000. Параметры HERMES_UID и HERMES_GID согласуют его с владельцем папки на VPS. При старте служебный процесс образа выполняет подготовку, затем снижает права рабочих процессов. Поэтому в Compose ниже нет строки user: и собственного entrypoint:: такие изменения могут обойти штатную подготовку каталога.

Если агент нужен для рабочего процесса компании, в ClaudeLab можно подготовить внедрение ИИ с серверным размещением и поддержкой. До запуска определяют задачу, разрешённые действия и способ проверки результата. Круглосуточный процесс без этих условий может регулярно повторять одну и ту же ошибку.

Шаг 2. Создать Compose и пройти настройку

Сохраните следующий файл как $HOME/hermes-vps/compose.yaml. Это сокращённая конфигурация для одного gateway, подготовленная на основе официального образа и документации. Она отличается от Compose в репозитории Hermes: тот содержит локальную сборку и отдельный dashboard. Здесь используется уже опубликованный образ без панели управления и публичных портов.

services:
  gateway:
    image: nousresearch/hermes-agent@sha256:d4da4a40cd7a28aba983775d9fd31d94cbf153eeb0cb9e844d6d0f612b7c24db
    restart: unless-stopped
    command: ["gateway", "run"]
    environment:
      HERMES_UID: "${HERMES_UID:?Set HERMES_UID}"
      HERMES_GID: "${HERMES_GID:?Set HERMES_GID}"
    volumes:
      - ./data:/opt/data
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Длинный идентификатор в image - подтверждённый digest на дату проверки. При следующем осознанном обновлении вы замените его новым. Относительный путь ./data Compose разрешает от каталога файла, поэтому все команды далее явно используют один файл в домашней папке. Ограничение журналов в этом примере относится к журналу Docker; оно не ограничивает собственные файлы Hermes в каталоге данных.

Проверьте конфигурацию и загрузите образ:

docker compose --file "$HOME/hermes-vps/compose.yaml" config --quiet
docker compose --file "$HOME/hermes-vps/compose.yaml" pull gateway
docker compose --file "$HOME/hermes-vps/compose.yaml" run --rm gateway setup

Первая команда проверяет Compose и подстановку UID/GID без вывода полной конфигурации. Если переменной нет, выражение с :? даст ошибку и не подставит случайное значение. Вторая скачивает выбранный образ. Третья открывает мастер Hermes Agent. Ожидаемый результат настройки - сохранённые параметры провайдера, модели и выбранного канала общения в data на VPS.

Подключите провайдера, к которому у вас уже есть разрешённый доступ. В зависимости от способа входа это может быть API-ключ или поддержанный вход через учётную запись. Не выбирайте модель только по названию в чужой инструкции: она должна быть доступна именно у вашего провайдера. Ключи вводите в мастер или в предусмотренный защищённый файл; не размещайте их в Compose и командной строке.

Для Telegram нужен отдельный бот и его токен; для другого мессенджера - настройка выбранного сервиса. Ограничьте разрешённых пользователей. В справочнике Hermes Agent для Telegram это TELEGRAM_ALLOWED_USERS, куда указывают числовые ID пользователей. Не включайте общий доступ ради проверки: серверный агент может иметь терминал и рабочие файлы. Если канал не был настроен в основном мастере, выполните отдельный мастер до постоянного запуска:

docker compose --file "$HOME/hermes-vps/compose.yaml" run --rm gateway gateway setup

Для показанного режима общения в Telegram публикация портов на VPS не требуется. В официальном примере Hermes Agent встречается порт 8642 для отдельного API-сервера; сама строка ports его не включает и не заменяет авторизацию. Dashboard на 9119 также относится к отдельному способу управления. Не добавляйте эти порты в базовую схему только ради сходства с чужим файлом.

Если вы переносите существующего бота, предварительно остановите прежний gateway в согласованное окно. Не оставляйте два экземпляра с одним токеном и одной задачей обработки сообщений. Для версии, статуса и просмотра журналов используйте compose exec в существующем контейнере. Повторный setup, смену канала и другие настройки работающего сервиса выполняйте по процедуре выбранной версии с остановкой нужных процессов. Не повторяйте первичную установку поверх рабочего data и не создавайте второй контейнер через compose run ради настройки.

Шаг 3. Указать рабочую папку и запустить gateway

Образ и данные выполняют разные задачи. Установленный Hermes Agent находится в /opt/hermes. Конфигурация, ключи, навыки, память, история и база state.db относятся к /opt/data. Созданная на VPS папка data/workspace видна контейнеру как /opt/data/workspace; в неё удобно складывать отчёты и промежуточные документы.

В конфигурации Hermes Agent установите терминальный режим local и эту рабочую папку. На новой установке, пока постоянный gateway ещё не запущен, можно выполнить:

docker compose --file "$HOME/hermes-vps/compose.yaml" run --rm gateway config set terminal.backend local
docker compose --file "$HOME/hermes-vps/compose.yaml" run --rm gateway config set terminal.cwd /opt/data/workspace
docker compose --file "$HOME/hermes-vps/compose.yaml" up -d gateway

Терминал будет выполнять команды в контейнере Hermes Agent. Рабочая папка задаёт начальный каталог, но не запрещает программе обращаться к другим доступным путям. В конфигурацию безопасности дополнительно входят разрешённые инструменты, доступ к интеграциям и правила подтверждения действий. Их следует сопоставить с задачей агента; общий разбор есть в материале о безопасности ИИ-агентов.

Для Hermes Agent сохраняйте рабочие инструкции и источники отдельно от случайных результатов диалога. Структура базы знаний для ИИ помогает определить, какие документы агенту разрешено использовать и чему доверять. Наличие memories/ само по себе не заменяет проверенный справочник компании.

Команда up -d создаёт и запускает сервис в фоне. После неё закрытие терминала не должно останавливать контейнер. Если вместо gateway вы запускаете обычный интерактивный чат, срок его работы связан с жизнью этого процесса: такой запуск не заменяет постоянный серверный сервис.

Не устанавливайте недостающие системные программы вручную в контейнер как единственный способ подготовки. Обычный рестарт сохраняет его записываемый слой, но пересоздание с новым образом заменяет слой. Для повторяемого набора системных зависимостей нужен собственный производный образ. При обслуживании Hermes Agent конфигурацию внешних инструментов и их файлы сохраняйте в постоянных путях; отдельные инструменты могут использовать свой домашний каталог под data/home.

Как проверить, что агент действительно работает

После запуска выполните команды чтения:

docker compose --file "$HOME/hermes-vps/compose.yaml" ps
docker compose --file "$HOME/hermes-vps/compose.yaml" logs --tail=80 gateway
docker compose --file "$HOME/hermes-vps/compose.yaml" exec gateway hermes --version
docker compose --file "$HOME/hermes-vps/compose.yaml" exec gateway hermes gateway status
docker compose --file "$HOME/hermes-vps/compose.yaml" exec gateway hermes doctor

В логах Hermes Agent ищите подтверждение старта нужного канала и повторяющиеся ошибки. Команда версии фиксирует фактически работающую установку. Статус gateway показывает состояние процесса, а doctor проверяет доступные параметры окружения. Ни одна из этих команд отдельно не доказывает, что модель ответит на следующее сообщение. В официальном s6-образе контейнер способен оставаться запущенным, пока внутренний gateway перезапускается после ошибки.

Контрольное обращение отправьте сами из разрешённой учётной записи. Возьмите задачу без внешних изменений: например, попросите коротко пересказать вымышленный список задач и явно запретите инструменты, отправку сообщений другим людям и изменение файлов. Такое обращение может использовать лимит или оплату провайдера модели. Его выполняют после проверки выбранного провайдера и доступов.

Успешный ответ подтвердит весь путь от вашего сообщения до модели и обратно для этой задачи. Следующая проверка относится к данным. Создайте обычный контрольный файл через shell внутри работающего контейнера:

docker compose --file "$HOME/hermes-vps/compose.yaml" exec --user hermes gateway \
  sh -c 'printf "persistent-check\n" > /opt/data/workspace/persistence-check.txt'

На VPS он должен появиться в $HOME/hermes-vps/data/workspace/persistence-check.txt. Если его нет, сначала проверьте mount и путь. Не поручайте модели выяснять это через случайные команды: проблема подключения каталога проверяется средствами Docker.

Сохраните для себя digest образа, выведенную версию, время проверки и краткий результат. Ключи и полные диалоги в отчёт не нужны. Такая запись позволит после обновления сравнить фактическое поведение с исходным, а при проблеме понять, какой уровень перестал работать.

Перезапуск контейнера и перезагрузка VPS

Политика restart: unless-stopped помогает при завершении контейнера и последующем запуске Docker. При этом Docker Engine на VPS должен сам запускаться после перезагрузки ОС. Контейнер, который вы намеренно остановили, эта политика не возвращает автоматически. Поведение политики описано в документации Docker.

В проверенной ревизии официального образа entrypoint - специальный dispatcher. В обычном запуске Docker он передаёт управление s6-overlay, который запускает служебные процессы и следит за gateway. Не переопределяйте entrypoint и не добавляйте init: true по привычному шаблону: внешний init меняет этот путь, и внутреннее наблюдение за службами может быть недоступно.

Проверьте простой рестарт в окно, когда агент не выполняет длительную задачу:

docker compose --file "$HOME/hermes-vps/compose.yaml" restart gateway
docker compose --file "$HOME/hermes-vps/compose.yaml" exec --user hermes gateway \
  cat /opt/data/workspace/persistence-check.txt
docker compose --file "$HOME/hermes-vps/compose.yaml" exec gateway hermes gateway status

Контрольный файл должен содержать прежнюю строку. Проверьте также ответ на новое контрольное обращение из мессенджера. Если Docker ещё показывает переходное состояние, дождитесь запуска и повторите команды чтения. Рестарт прерывает текущее выполнение; повторная обработка незавершённой задачи зависит от её устройства и не гарантируется этой политикой.

Полную перезагрузку VPS проводите отдельно, когда на нём нет работ, которые нельзя прерывать. После возвращения сервера проверьте доступ к Docker, тот же Compose-сервис, gateway, данные и контрольный ответ. До этой проверки записывать «переживает перезагрузку VPS» в результат установки рано. При общей аварии провайдера или недоступности модели один исправный контейнер проблему не решит; для рабочего процесса полезно заранее подготовить порядок действий при отказе ИИ.

Gateway Hermes Agent принимает обращения. Расписание задач и подключённые каналы нужно настроить отдельно. Если процесс состоит из нескольких заранее заданных действий разных сервисов, сопоставьте его с автоматизацией в n8n. Серверное размещение агента не требует передавать ему каждый шаг такого процесса.

Резервная копия и обновление без потери данных

Резервная копия включает больше, чем config.yaml и память. Для Hermes Agent в ней нужны база state.db, возможные файлы журнала SQLite, профили, ключи, навыки, расписания, история и рабочие документы. Не копируйте только главный файл базы во время записи: часть актуального состояния может находиться в связанных файлах WAL.

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

Успех архивации проверяют по коду завершения tar и чтением списка файлов через tar -tzf. При ошибке копирования обновление откладывают; автоматического возврата gateway в блоке нет. Если решите отменить обслуживание, сначала верните прежний digest в Compose и отдельно запустите прежний сервис. После неудачи копирования не считайте резервную копию готовой. Хранение архива на том же VPS защищает от случайной замены контейнера, но не от потери самого сервера. Вторую защищённую копию разместите отдельно; архив содержит секреты и не должен попадать в публичный Git или открытое файловое хранилище.

Перед обновлением сохраните также Compose со старым digest и два значения UID/GID. Сверьте новую стабильную сборку с официальными релизами и получите её digest. Например, чтение тега и локальных метаданных выполняется так:

docker pull nousresearch/hermes-agent:latest
docker image inspect nousresearch/hermes-agent:latest \
  --format '{{index .RepoDigests 0}}'
docker image inspect nousresearch/hermes-agent:latest \
  --format '{{index .Config.Labels "org.opencontainers.image.revision"}}'

Первая команда только загружает образ, она не меняет работающий сервис. Полученный RepoDigest сравните с текущим значением в Compose. Если он тот же, версии для переключения нет. Если новый, сначала прочитайте условия обновления. Метка ревизии показывает связь с исходным кодом; отсутствие метки нельзя заменять догадкой по дате скачивания.

Сохраните прежний Compose, внесите новый digest в image и выполните следующую последовательность целиком. Смена строки image ещё не меняет работающий контейнер. Блок сначала останавливает сервис, создаёт и проверяет копию данных, затем загружает и запускает новый образ:

hermes_backup_path="$HOME/hermes-vps/backups/hermes-data-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
mkdir -p "$HOME/hermes-vps/backups" || exit 1
chmod 700 "$HOME/hermes-vps/backups" || exit 1
umask 077
docker compose --file "$HOME/hermes-vps/compose.yaml" stop gateway || exit 1
if ! tar -C "$HOME/hermes-vps" -czf "$hermes_backup_path" data; then
  printf 'Копия не создана. Обновление остановлено.\n' >&2
  exit 1
fi
if ! tar -tzf "$hermes_backup_path" >/dev/null; then
  printf 'Архив не читается. Обновление остановлено.\n' >&2
  exit 1
fi
docker compose --file "$HOME/hermes-vps/compose.yaml" config --quiet || exit 1
docker compose --file "$HOME/hermes-vps/compose.yaml" pull gateway || exit 1
docker compose --file "$HOME/hermes-vps/compose.yaml" up -d gateway

При закреплённом digest команда pull прежней конфигурации загрузит прежний образ. Она сама не выберет новую версию. Обычный restart также не применяет новый image: нужен запуск Compose с пересозданием сервиса с новым образом. После замены повторите проверку версии, состояния gateway, контрольного файла и ответа модели.

Обновлять установленный код через hermes update внутри опубликованного образа не следует: его дерево приложения принадлежит образу. Если нужны изменения из ветки разработки или дополнительные системные зависимости, подготовьте новую сборку отдельно, закрепив исходную ревизию. Не превращайте ручные исправления внутри запущенного контейнера в единственный экземпляр своего решения.

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

Если запуск или постоянная работа не получились

При Permission denied не применяйте chmod -R 777. В data лежат секреты и история. Сначала выясните, какой пользователь пишет файл и кому файл принадлежит. Для существующей установки изменение владельца всего дерева требует проверки, какие другие процессы используют этот каталог. В одноразовой тестовой установке проще исправить причину до передачи реальных данных.

При отсутствии ответа сопоставьте провайдера, выбранную модель и способ входа. Отказ авторизации, лимит провайдера и сетевой сбой - разные причины. Не меняйте сразу ключ, модель, Compose и права каталога: после нескольких одновременных изменений трудно определить, что помогло. Исправьте найденную причину и повторите ту же контрольную задачу.

Если значение переменной из Docker не совпадает с поведением Hermes, проверьте сохранённую конфигурацию и его собственный data/.env. Документация и комментарий служебной подготовки образа расходятся в описании приоритета переменных; для данной схемы ключи хранятся в Hermes, а в Compose передаются только UID/GID. Это избавляет от двух копий одного токена. Не выводите секретный файл целиком ради проверки одного параметра.

Для браузерных инструментов официальная инструкция предлагает увеличить shared memory. В Compose это можно оформить параметром shm_size: "1g" в сервисе gateway, затем применить изменение через up -d. Значение - пример из документации, а не универсальный размер под любую задачу. Если VPS исчерпал оперативную память, увеличение этого лимита само по себе её не добавит.

Для установки, которая уже работает и не совпадает с этим примером, зафиксируйте digest, версию, архитектуру и путь data. Сверьте процедуру с документацией той ревизии или передайте эти сведения администратору. Не начинайте её перенастройку с блока новой установки.

Просматривайте только нужный участок журналов. Ошибка может содержать текст запроса, путь документа или другие рабочие сведения. Перед обращением за помощью удалите токены, личные данные и содержимое клиентских сообщений. Полный архив data для разбора обычной ошибки отправлять не нужно.

Чек-лист

• Используется выбранный официальный образ с записанным digest; версия работающего Hermes зафиксирована.
• Один gateway подключает постоянный каталог к /opt/data; UID/GID соответствуют его владельцу, рабочие документы лежат в постоянных путях.
• Модель и канал общения настроены; контрольное обращение разрешённого пользователя получает ответ.
• Публичные порты и Docker socket не добавлены в показанную конфигурацию; доступы соответствуют конкретной задаче.
• После рестарта сохраняется контрольный файл; запуск Docker после перезагрузки VPS и ответ gateway проверены отдельно.
• Полный каталог данных скопирован при остановленной записи; есть защищённая копия вне VPS и проверенный порядок восстановления.
• Новая версия применяется заменой digest и пересозданием сервиса; для возврата сохранены прежний образ, Compose и данные той же версии.