Hermes WebUIをCLIの作業環境へ重ねる設計

サーバ側エージェントのためのブラウザインターフェース、Hermes WebUIをCLIの作業環境へ重ねる設計

Hermes WebUI は Hermes Agent のブラウザベースのインターフェースである。README は Hermes Agent を、サーバ上で動作し、通常はターミナルかメッセージングアプリから操作する自律エージェントだと説明している。WebUI は軽量でダークテーマのウェブアプリで、CLI とのほぼ完全な互換性を目標とする。README によれば、ターミナルでできることはすべて UI からもできる。ビルドステップもフレームワークもバンドラもなく、Python と素の JavaScript だけである。リポジトリの説明では、ウェブまたはスマートフォンから Hermes Agent を使う最良の方法とされている。

3パネル構成は左にセッションとナビゲーション、中央にチャット、右にワークスペースのファイル表示を置く。モデル、プロファイル、ワークスペースはcomposer footerから操作し、セッションや設定はHermes Control Centerに集約する。READMEがいうCLIとのほぼ同等という範囲は、WebUI独自のエージェントではなく、既存のHermesをプロセス内で使う設計から生じている。

最短の起動経路は`git clone https://github.com/nesquena/hermes-webui.git hermes-webui`、`python3 bootstrap.py`だ。常駐運用では`./ctl.sh start`、`status`、`logs --lines 100`、`restart`、`stop`が使え、PIDは`~/.hermes/webui.pid`、ログは`~/.hermes/webui.log`に置かれる。`bootstrap.py`や`start.sh`で起動したプロセスを`ctl.sh stop`では止められない点は、障害対応時の具体的な落とし穴になる。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第1項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第1節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

標準ライブラリのサーバと素の JS フロントエンド、Hermes WebUIをCLIの作業環境へ重ねる設計

サーバは Web フレームワークではなく、Python 標準ライブラリの HTTP サーバである。バックエンドは api/ に置かれ、server.py がルーティングの外郭と認証ミドルウェアを担い、routes.py がすべての GET と POST ハンドラを if/elif ディスパッチで処理する。デコレータは使われていない。認証、設定の自動検出、セッションモデル、SSE ストリーミング、アップロード、ワークスペースのファイル操作は別モジュールに分かれる。フロントエンドの static/ は素の JS ファイル群で、ui.js が DOM ヘルパとツールカード、workspace.js がファイル操作と git 検出、messages.js が SSE 処理、panels.js がコントロールセンター、commands.js がスラッシュコマンドの補完を担当する。状態はデフォルトでリポジトリ外の ~/.hermes/webui/ に保存される。

最短の起動経路は`git clone https://github.com/nesquena/hermes-webui.git hermes-webui`、`python3 bootstrap.py`だ。常駐運用では`./ctl.sh start`、`status`、`logs --lines 100`、`restart`、`stop`が使え、PIDは`~/.hermes/webui.pid`、ログは`~/.hermes/webui.log`に置かれる。`bootstrap.py`や`start.sh`で起動したプロセスを`ctl.sh stop`では止められない点は、障害対応時の具体的な落とし穴になる。

3パネル構成は左にセッションとナビゲーション、中央にチャット、右にワークスペースのファイル表示を置く。モデル、プロファイル、ワークスペースはcomposer footerから操作し、セッションや設定はHermes Control Centerに集約する。READMEがいうCLIとのほぼ同等という範囲は、WebUI独自のエージェントではなく、既存のHermesをプロセス内で使う設計から生じている。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第2項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第2節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

3 パネル構成、コンポーザーフッター、コントロールセンター、Hermes WebUIをCLIの作業環境へ重ねる設計

レイアウトは 3 パネル構成である。左サイドバーがセッションとナビゲーション、中央がチャット、右パネルがワークスペースのファイル閲覧だ。モデル、プロファイル、ワークスペースのコントロールはコンポーザーフッターに置かれ、作成中は常に表示される。円形のコンテキストリングがトークン使用量を示す。設定とセッションツールは Hermes コントロールセンターにまとめられ、サイドバー下部から起動する。外観は Theme（system、dark、light）と Skin（ares、slate、poseidon、catppuccin、nous など）の 2 軸に分かれ、data-skin 属性と CSS 変数で実装され、ダークモードは .dark クラスで解決される。

最短の起動経路は`git clone https://github.com/nesquena/hermes-webui.git hermes-webui`、`python3 bootstrap.py`だ。常駐運用では`./ctl.sh start`、`status`、`logs --lines 100`、`restart`、`stop`が使え、PIDは`~/.hermes/webui.pid`、ログは`~/.hermes/webui.log`に置かれる。`bootstrap.py`や`start.sh`で起動したプロセスを`ctl.sh stop`では止められない点は、障害対応時の具体的な落とし穴になる。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第3項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第3節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

起動方法: bootstrap、start.sh、ctl.sh、Hermes WebUIをCLIの作業環境へ重ねる設計

起動方法は 3 つ文書化されている。python3 bootstrap.py は Hermes Agent を検出し、無ければ公式インストーラを試し、WebUI の依存関係を持つ Python 環境を探すか作成し、サーバを起動して /health を待ち、--no-browser が渡されなければブラウザを開き、初回オンボーディングウィザードに入る。./start.sh はシェルランチャーだ。セルフホストの VM やホームラボ向けに、ctl.sh は fuser や pkill を必要とせずにデーモンのライフサイクルコマンド（start、status、logs、restart、stop）をラップし、PID を ~/.hermes/webui.pid に、ログを ~/.hermes/webui.log に書く。停止方法は起動方法ごとに異なる。bootstrap.py はフォアグラウンドで動き Ctrl-C で止まり、ctl.sh stop は自分が起動したプロセスしか管理しない。bootstrap はネイティブ Windows に未対応で、Linux、macOS、WSL2 が必要だ。コミュニティ管理のネイティブ Windows セットアップが別途文書化されており、コミュニティ計測のメモリ使用量はネイティブ約 330 MB に対して WSL2 と Docker で約 1080 MB と報告されている。

3パネル構成は左にセッションとナビゲーション、中央にチャット、右にワークスペースのファイル表示を置く。モデル、プロファイル、ワークスペースはcomposer footerから操作し、セッションや設定はHermes Control Centerに集約する。READMEがいうCLIとのほぼ同等という範囲は、WebUI独自のエージェントではなく、既存のHermesをプロセス内で使う設計から生じている。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第4項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第4節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

チャットは WebUI のプロセス内で実行される、Hermes WebUIをCLIの作業環境へ重ねる設計

デフォルトでは WebUI は Hermes Agent をプロセス内で実行し、HERMES_HOME の設定を直接読む。チャットのために外部の Hermes や OpenAI 互換 API サーバに接続することはない。README は HERMES_API_URL が Tasks/cron のヘルスプローブでのみ読まれ、チャットのルーティングには使われないと明言している。外部エンドポイントを使う場合の選択肢は 2 つある。Settings で base_url を指定したカスタムの OpenAI 互換プロバイダを追加するか、HERMES_WEBUI_CHAT_BACKEND=gateway を設定して Hermes Gateway API サーバ経由でチャットをルーティングするかだ。完全なエージェントループ委任はまだ未実装で、issue #1925 で追跡されている。設定のほとんどは start.sh が自動検出する。エージェントディレクトリ、Python 実行ファイル、状態ディレクトリ、デフォルトワークスペース、ポートが見つけられ、HERMES_WEBUI_* 環境変数で上書きできる。

最短の起動経路は`git clone https://github.com/nesquena/hermes-webui.git hermes-webui`、`python3 bootstrap.py`だ。常駐運用では`./ctl.sh start`、`status`、`logs --lines 100`、`restart`、`stop`が使え、PIDは`~/.hermes/webui.pid`、ログは`~/.hermes/webui.log`に置かれる。`bootstrap.py`や`start.sh`で起動したプロセスを`ctl.sh stop`では止められない点は、障害対応時の具体的な落とし穴になる。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第5項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第5節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

Docker、Nix、リモートアクセス、Hermes WebUIをCLIの作業環境へ重ねる設計

amd64 と arm64 のプレビルド Docker イメージがリリースごとに GHCR へ公開される。単一コンテナの compose ファイルはエージェントをプロセス内で実行し、5 分の順調な道と説明されている。2 コンテナと 3 コンテナの compose ファイルはエージェントとダッシュボードを分離する。compose ファイルはデフォルトで名前付きボリュームを使い、UID/GID の不一致を構造的に避ける。文書化された既知の制限（#681）として、2 コンテナ構成で WebUI から起動したツールはエージェントコンテナではなく WebUI コンテナ内で実行される。Nix flake パッケージと NixOS サービスモジュールが宣言的なインストールを提供する。リモートアクセスはデフォルトで 127.0.0.1 にバインドされる。文書化された経路は SSH トンネル（ssh -N -L 8787:127.0.0.1:8787 user@host）か、サーバとスマートフォンを Tailscale ネットワークに参加させ、HERMES_WEBUI_HOST=0.0.0.0 と HERMES_WEBUI_PASSWORD を設定してアクセスする方法だ。

3パネル構成は左にセッションとナビゲーション、中央にチャット、右にワークスペースのファイル表示を置く。モデル、プロファイル、ワークスペースはcomposer footerから操作し、セッションや設定はHermes Control Centerに集約する。READMEがいうCLIとのほぼ同等という範囲は、WebUI独自のエージェントではなく、既存のHermesをプロセス内で使う設計から生じている。（この節ではHermes WebUIをCLIの作業環境へ重ねる設計の第6項目として扱う。）

Hermes WebUIをCLIの作業環境へ重ねる設計の第6節では、READMEに記載された固有の入口と制約をこの節の確認対象として扱う。

編集部の結論

Hermes WebUIは、既存のHermes Agentとモデルをサーバー側に置いたまま、ブラウザでセッションとワークスペースを扱いたい利用者に向く。`python3 bootstrap.py`または`./ctl.sh start`の違い、8787番ポート、SSHトンネル、WebUIと`hermes-agent`の同時更新を先に確認するべきだ。別バージョンの組合せは未テストかつ未サポートなので、そこを許容できない運用には向かない。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes