🤖HermesBlog
Hermes Feature Guides · パート 168/9/2026

Docker + Hermes Agent: Two Ways to Play

Event Hooks — Auto-Trigger at Key Moments — easy-to-understand guide based on official docs (updated 2026-08-09)

hermes-feature-16-hooks

Docker + Hermes Agent: 2つの活用方法

DockerがHermes Agentとどう関わるのか、疑問に思ったことはありませんか？そんなあなたは正しい場所に来ています。実はこの2つを組み合わせる方法は2通りあり、docker run と打ち込む前に、その違いを知っておく価値があります。

2つのDockerモード

  1. HermesをDocker内で実行 — エージェント自体がコンテナ内に存在します。このガイドの主な焦点です。
  2. ターミナルバックエンドとしてのDocker — Hermesはホストマシン上で実行されますが、実行されるすべてのコマンドは、単一の永続的なDockerサンドボックス内で行われます。このサンドボックスは、Hermesプロセスが生きている限り、ツール呼び出し、/new、さらにはサブエージェントをまたいでも存続します。

この記事では、オプション1について説明します。重要なポイントは、すべてのデータ（設定、APIキー、セッション、スキル、メモリ）がホスト上の単一ディレクトリに保存され、コンテナ内の /opt/data にマウントされることです。イメージ自体はステートレスなので、セットアップを失うことなく、いつでも新しいバージョンをプルできます。

クイックスタート: 初回セットアップ

これが初めての場合は、データディレクトリを作成し、コンテナをインタラクティブに起動してセットアップウィザードを実行します。

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

これでウィザードが起動し、APIキーの入力を求められ、~/.hermes/.env に書き込まれます。これは一度だけ実行すればOKです。ついでに、チャットシステム（Telegram、Discordなど）を設定して、ゲートウェイの会話の場を用意しておくと良いでしょう。

⚠️ 注意: これらのインストールコマンドには、ブラウザベースのVPSコンソールの使用を避けてください。一部のプロバイダー（Hetznerなど）は特殊文字を壊してしまいます — : が ; になったり、@ が誤ってレンダリングされたり、貼り付けたAPIキーが静かに破損する可能性があります。コピー＆ペーストで安全にコマンドを入力するには、常にSSHで接続してください。 ブラウザコンソールを使用する必要がある場合は、コマンドを手動で入力し、すべての :、@、=、/ を再確認してください。

プロのヒント: コンテナ内で hermes setup --portal を一度実行すると、リフレッシュトークンがマウントされた ~/.hermes ボリュームに永続化されます。

ゲートウェイモードでの実行

設定が完了したら、バックグラウンドで永続的なゲートウェイとしてコンテナを実行します。

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

ポート8642は、ゲートウェイのOpenAI互換APIサーバーとヘルスチェックエンドポイントを公開します。チャットプラットフォームのみを使用する場合はオプションですが、ダッシュボードや外部ツールからゲートウェイにアクセスしたい場合は必須です。

新機能: 監視付きゲートウェイ

大きな変更点があります。公式Dockerイメージ内では、gateway run は現在s6-overlayによって自動的に監視されています。ゲートウェイがクラッシュした場合、コンテナを失うことなく数秒以内に再起動します。ダッシュボード（有効な場合）も一緒に監視されます。

docker logs に、アップグレードを確認する1行のブレッドクラムが表示されます。以前の動作（コンテナ終了 = ゲートウェイ終了）を選択するには、--no-supervise を渡すか、HERMES_GATEWAY_NO_SUPERVISE=1 を設定します。これはCIスモークテストに役立ちます。本番環境では、監視付きのデフォルトが厳密に優れています。

ツールループのハードストップ

無人ゲートウェイの重要な設定の1つ: tool_loop_guardrails.hard_stop_enabled はデフォルトで false です。これは、人間が警告を確認できるインタラクティブセッションでは問題ありません。しかし、無人デプロイメントでは、警告だけではループにはまったエージェントを止められない可能性があります。サーキットブレーカー動作が必要な場合は、プロファイルの config.yaml で有効にします。

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

APIサーバーの公開

APIサーバーは API_SERVER_ENABLED=true で有効になります。コンテナ内の 127.0.0.1 の外に公開するには、API_SERVER_HOST=0.0.0.0 と API_SERVER_KEY（最低8文字 — openssl rand -hex 32 で生成）も設定します。

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

セキュリティに関する注意: インターネットに公開されたマシンでポートを開くことはリスクを伴います。影響を完全に理解していない限り、行わないでください。

ダッシュボードの実行

組み込みのWebダッシュボードは、同じコンテナ内のゲートウェイと一緒に、監視付きのs6-rcサービスとして実行されます。HERMES_DASHBOARD=1 を設定するだけです。

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-supervise が短いバックオフの後に自動的に再起動します。その出力は docker logs <container> に送られます。

ログの出力先

完全なルーティングマップ（プロファイルごとのゲートウェイ、ダッシュボード、起動時レコンサイラー、コンテナ全体の docker logs）については、ドキュメントの専用セクションを参照してください。簡単に言うと、最終的にはすべて docker logs に出力されますが、明確なプレフィックスが付いているので、何が何だか区別できます。

まとめ

Dockerを使用すると、Hermes Agentをクリーンでアップグレード可能な方法で実行できます。コンテナはステートレスで、データはホスト上に安全に保存され、新しいs6監視により、ゲートウェイがクラッシュしても稼働し続けます。シンプルなセットアップでも、フルのダッシュボード + APIサーバーの組み合わせでも、上記のコマンドで数分でセットアップできます。

📖 公式ドキュメント

この記事は Hermes Agent の公式ドキュメントに基づいています：公式ドキュメント › user-guide/features/hooks

← すべての記事に戻る