Hermes Agent：ヘッドレスサーバー＋リモートデスクトップの設定

リモートデスクトップアクセスに対応したヘッドレスHermesサーバー

目次

ヘッドレスサーバーで Hermes エージェントを実行し、別のマシンのデスクトップクライアントから接続するには、2つのサーバープロセスと1つのクライアント接続が必要です。

このアーキテクチャは、Hermes バックエンドを2つのサーバーサイドプロセスと1つのクライアントサイドのインターフェースに分離します。hermes serve バックエンドは API およびダッシュボードの接続を処理し、hermes gateway run プロセスはメッセージングチャネルを独立して管理します。デスクトップクライアントはゲートウェイではなく、serve バックエンドに接続します。

flowchart LR subgraph Server["HEADLESS SERVER"] serve["hermes serve
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["DESKTOP PC"] desktop["hermes desktop
(WebSocket connection)"] end desktop <--->|WebSocket| serve gateway -.->|Shares ~/.hermes/| serve

サーバーには2つのプロセス、クライアントには1つのアプリがあります。両方のサーバープロセスは同じ ~/.hermes/ 設定、スキル、メモリ、セッションを共有します。Cron ジョブはゲートウェイが実行されているサーバー上で実行されます。

Hermes Agent headless server architecture

インストール、プロバイダー設定、初期設定については、Hermes AI Assistant — Install, Setup, Workflow, and Troubleshooting から始めましょう。

ヘッドレスサーバーの設定

1. 認証の設定

信頼された LAN 環境では、Basic Auth で十分な保護が提供されます。環境ファイルに認証情報を追加します。

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

.env ファイルは ~/.hermes/ 内の config.yaml と同じ場所に配置されます。Hermes は設定を CLI の上書き、次に config.yaml、次に .env、最後に組み込みのデフォルト値の順で解決します。シークレット（秘密鍵）は .env に保存します。

2. バックエンドの起動

すべてのインターフェースで serve バックエンドを実行します。

hermes serve --host 0.0.0.0 --port 9119

バックエンドはポート 9119 で待機し、デスクトップクライアントからの WebSocket 接続を受け付けます。以下のステータスチェックで実行中であることを確認します。

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# 期待される出力: true  "basic"

3. systemd サービスとして実行

再起動後も存続する永続的なサーバーのために、ユーザーレベルの systemd サービスをインストールします。ユニットファイルを /etc/systemd/user/hermes-serve.service に作成します。

[Unit]
Description=Hermes Agent Serve Backend

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

デーモンをリロードし、サービスを有効化して起動します。

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

サービスのステータスを確認します。

systemctl --user status hermes-serve

4. ゲートウェイの起動

ゲートウェイはメッセージングチャネル（Telegram、Discord、Slack など）を処理する別のプロセスです。独立して起動します。

hermes gateway run

ゲートウェイと serve バックエンドは2つの別々のプロセスです。ゲートウェイはセッションを管理し、cron ジョブを実行して、メッセージをルーティングします。serve バックエンドは、デスクトップおよびウェブダッシュボード接続のための API サーフェスを提供します。これらは同じホームディレクトリを共有しますが、独立して実行されます。

ゲートウェイのコマンドおよびサブコマンドの完全なリストについては、Hermes Agent CLI cheat sheet を参照してください。 主なインターフェースがモバイルメッセージングである場合は、同じゲートウェイプロセス上のボイスファーストなワークフローのために、Hermes Voice Control from Your Phone と組み合わせて設定してください。

5. バックエンドの確認

バックエンドが応答し、認証がアクティブであることを確認します。

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

期待される出力:

true
"basic"

認証が有効でない場合、レスポンスは auth_required に対して false を示します。.env ファイルに正しい変数が含まれており、設定変更後にサービスが再起動されていることを確認してください。

デスクトップクライアントからの接続

オプション A: Hermes デスクトップアプリ

公式サイト から Hermes Desktop をインストールします。アプリを起動し、Settings → Gateway → Remote gateway に移動して、サーバーアドレスを入力します。

http://<server-ip>:9119

サーバーで設定したユーザー名とパスワードでサインインします。

または、環境変数を使用してリモート URL を設定することもできます。

HERMES_DESKTOP_REMOTE_URL=http://<server-ip>:9119 hermes desktop

オプション B: ウェブダッシュボード

ブラウザで http://<server-ip>:9119 を開き、Basic Auth の認証情報でサインインします。ウェブダッシュボードは、デスクトップのインストールを必要とせずに、Hermes バックエンドへのブラウザベースのインターフェースを提供します。

オプション C: CLI

デスクトップ PC のターミナルから、デスクトップアプリの設定または HERMES_DESKTOP_REMOTE_URL 環境変数を使用してリモート URL を設定します。CLI サーフェスは、デスクトップアプリと同じ WebSocket チャネルを介して接続します。

ネットワークとセキュリティの考慮事項

シナリオ 推奨事項
信頼された LAN --host 0.0.0.0 + Basic Auth
インターネットに公開 Tailscale を使用（--host <tailscale-ip>）または OAuth プロバイダー
ファイアウォール サーバーでポート 9119 TCP を開く

信頼されるローカルネットワークでは、0.0.0.0 での Basic Auth で十分です。サーバーがインターネットに公開されている場合は、0.0.0.0 の代わりに Tailscale IP にバインドするために Tailscale を使用するか、より強力な認証のために OAuth プロバイダーを設定してください。バックエンドが外部接続を受け付ける必要がある場合、常にサーバーのファイアウォールでポート 9119 TCP を開いてください。

プロセスの重要な区別

2つのサーバープロセス間の分離を理解することで、一般的な設定ミスを防ぐことができます。

  • hermes serve — デスクトップアプリとウェブダッシュボードが接続するバックエンド。API サーフェスと WebSocket 接続を処理します。
  • hermes gateway run — Telegram、Discord、Slack、およびその他のメッセージングチャネルを処理するプロセス。セッションを管理し、cron ジョブを実行して、メッセージをルーティングします。
  • これらはサーバー上の 2つの別々のプロセス です。~/.hermes/ の設定、スキル、メモリ、セッションを共有しますが、独立して実行されます。
  • Cron ジョブはゲートウェイが実行されているサーバー上で実行されます。
  • プロファイル、スキル、メモリはサーバー側で設定されます。クライアントは既に設定されたバックエンドに接続します。

プロファイルを優先した設定と、異なる本番環境の役割に調整されたスキルについては、Hermes AI Assistant Skills for Real Production Setups を参照してください。

トラブルシューティング

デスクトップがサーバーに接続できない

  1. バックエンドの実行を確認: systemctl --user status hermes-serve
  2. ポートが開いていることを確認: ss -tlnp | grep 9119
  3. サーバーからテスト: curl -s http://localhost:9119/api/status
  4. クライアントマシンからテスト: curl -s http://<server-ip>:9119/api/status
  5. クライアントのテストが失敗した場合は、ファイアウォールルールを確認: sudo ufw status または sudo iptables -L

認証が失敗する

  1. .env ファイルの権限が正しいことを確認: ls -la ~/.hermes/.env （600 である必要があります）
  2. シークレットが生成されていることを確認: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
  3. 設定変更後にサービスを再起動: systemctl --user restart hermes-serve

ゲートウェイがメッセージに反応しない

ゲートウェイはバックエンドとは別々のプロセスです。デスクトップは接続できるがメッセージングプラットフォームが機能しない場合:

  1. ゲートウェイのステータスを確認: hermes gateway status
  2. 停止している場合はゲートウェイを起動: hermes gateway start
  3. ログを確認: hermes logs gateway -f

参考文献

この記事は、セルフホスト型アシスタント、検索アーキテクチャ、ローカル LLM インフラストラクチャ、および観測性をカバーする AI Systems クラスタの一部です。

購読する

システム、インフラ、AIエンジニアリングの新記事をお届けします。