Запуск и настройка Hermes Agent Web Dashboard: локальный доступ, профили и диагностика

Графический веб-интерфейс Hermes Agent Web Dashboard предназначен для администрирования инсталляции агента через браузер вместо прямого редактирования конфигурационных файлов. Панель позволяет управлять ключами доступа, переключать профили, проверять сессии и запускать встроенный терминал без изменения системного окружения вручную.

Базовый запуск и системные зависимости

По умолчанию панель управления запускается на интерфейсе обратной петли (loopback):

hermes dashboard

Команда запускает локальный HTTP-сервер и открывает адрес http://127.0.0.1:9119. Если порт занят другим локальным сервисом, порт можно переопределить ключом --port:

hermes dashboard --port 9120 --no-open

Флаг --no-open предотвращает автоматическое открытие вкладки в браузере, что стандартно для фонового запуска или скриптов автоматизации.

Базовый пакет hermes-agent не включает веб-стек по умолчанию. В окружениях Linux, macOS и WSL2 недостающие компоненты устанавливаются в виртуальное окружение агента:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

Пакет web устанавливает FastAPI и Uvicorn, а pty добавляет ptyprocess для POSIX-систем. Для сборки статического интерфейса панели требуется установленный Node.js (при наличии npm фронтенд компилируется автоматически при первом старте).

Границы платформ: нативный Windows и WSL2

Согласно руководству по Windows (Native), нативная сборка для Windows поддерживает страницы конфигурации, метрик, задач и базы сессий. Однако вкладка встроенного терминала /chat требует псевдотерминала POSIX PTY. В нативной среде Windows этот вызов не поддерживается, поэтому для полноценной интерактивной сессии в браузере необходимо запускать агент внутри WSL2.

Также важно разделять процессы: веб-панель управления и шлюз обмена сообщениями (messaging gateway для Telegram, Discord и других платформ) — это независимые демоны. Запуск веб-интерфейса не активирует платформенный шлюз автоматически.

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

Панель управления работает на уровне всей машины и централизованно администрирует все созданные профили. Переключатель профилей в боковом меню меняет рабочий контекст через параметр URL ?profile=<имя>.

1. Разделы Config и API Keys: Страница Config редактирует параметры config.yaml, а изменения сохраняются кнопкой Save. Страница API Keys обновляет переменные в ~/.hermes/.env: ключи устанавливаются и удаляются индивидуально для каждой отдельной переменной, без общей кнопки сохранения или пакетной валидации всех полей.
2. Согласованность провайдера и модели: Выбранная модель и учетные данные должны строго соответствовать одному провайдеру. При использовании стороннего OpenAI-совместимого сервиса сверяйтесь с официальными параметрами поставщика: например, актуальные поля, идентификаторы моделей и настройки подключения описаны в руководстве BetterToken. Сторонний провайдер предоставляет только независимый API-доступ к моделям и не хостит саму панель Hermes или сетевые туннели.
3. Проверка работоспособности через Sessions: Для ручной проверки отправьте короткую инструкцию только для чтения. Учтите, что тестовый запрос может тарифицироваться провайдером. Успехом инференса считается получение содержательного ответа в интерфейсе и фиксация расхода токенов в метаданных сессии или на стороне провайдера. Само по себе появление новой строки в списке на вкладке Sessions лишь фиксирует создание записи и не является подтверждением успешного ответа модели.

Безопасный удаленный доступ

По умолчанию веб-сервер слушает исключительно 127.0.0.1. При привязке к внешним интерфейсам (--host 0.0.0.0) автоматически активируется защитный шлюз (auth gate). Если провайдер аутентификации не настроен, агент завершает работу с ошибкой (fail-closed). Устаревший флаг --insecure больше не отключает проверку подлинности. Публичная или внешняя сетевая привязка требует обязательной аутентификации согласно документации Hermes Agent.

Рекомендуемый способ подключения к удаленному серверу без открытия внешних портов — локальная переадресация через SSH-туннель (замените user@your-server на адрес и пользователя вашего сервера):

ssh -N -L 9119:127.0.0.1:9119 user@your-server

Если локальный порт 9119 на вашей рабочей станции уже занят другим процессом, используйте вариант с альтернативным локальным портом:

ssh -N -L 9120:127.0.0.1:9119 user@your-server

При таком подходе сервер Hermes на удаленной машине продолжает работать только на локальном интерфейсе 127.0.0.1, трафик шифруется туннелем, а на рабочей станции панель открывается по адресу http://127.0.0.1:9119 (или http://127.0.0.1:9120 при переопределении локального порта).

Пошаговая диагностика неполадок

При возникновении ошибок важно изолировать слой сбоя, а не проверять всю цепочку целиком.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

1. Сетевой уровень (HTTP): Доступность GET /api/status доказывает только то, что процесс Uvicorn запущен и отвечает на HTTP-запросы. Этот эндпоинт открыт и не гарантирует успешного прохождения авторизации или готовности интерактивного чата.
2. Слой PTY и интерфейса: Ошибка Connection closed может иметь несколько причин. В нативной среде Windows одной из диагностических причин является отсутствие поддержки POSIX PTY (в этом случае запуск переносят в окружение WSL2). В других средах данный симптом не сводится к PTY и требует проверки системных журналов и соединения сокета. Ошибки сборки стилей или белого экрана требуют проверки версии Node.js и повторной сборки зависимостей.
3. Каналы сокетов и авторизация: Встроенный терминал браузера использует маршрут /api/pty, тогда как удаленный Desktop-клиент подключается через /api/ws. Если клиент сообщает о доступности бэкенда, но сессия не отвечает, проверьте соединение соответствующего канала: к сбоям могут приводить отсутствие или истечение сессионного тикета, а также блокировка защитой от DNS-rebinding из-за несовпадения заголовка Host с адресом привязки.
4. Слой провайдера модели: Задержки генерации или сообщения об ошибках после отправки реплики в активном терминале чаще всего относятся к уровню API (валидность ключа в .env, доступность эндпоинта провайдера, лимиты и баланс). Однако ошибки провайдера не доказывают, что сам сервер панели полностью исправен: при сбоях может также потребоваться проверка состояния рантайма и сессии.