Hermes の管理画面

管理画面は、導入した Hermes Agent をブラウザから扱うための操作盤です。YAML を書き換えたり CLI のコマンドを打ったりしなくても、設定を変え、API キーを管理し、セッションの様子を見られます。

手早く使い始める

hermes dashboard

これでローカルにウェブサーバーが立ち上がり、ブラウザで http://127.0.0.1:9119 が開きます。管理画面はすべて手元の端末の中で動き、データが localhost の外へ出ることはありません。

オプション

# Custom port
hermes dashboard --port 8080

# Bind to all interfaces (use with caution on shared networks)
hermes dashboard --host 0.0.0.0

# Start without opening browser
hermes dashboard --no-open

複数のプロファイルを扱う

管理画面は端末ごとの操作盤です。1つのサーバーが、その端末にある プロファイルすべてを管理します。横の欄にあるプロファイルの 切り替え（プロファイルが2つ以上あるときに現れます）で、管理のページが読み書きする プロファイルが決まります。設定、API キー、スキル、 MCP、モデル、そしてチャットのタブが、すべてこれに従います。管理画面自身のもの以外の プロファイルを選んでいるあいだは、琥珀色の帯が管理中のプロファイル名を出すので、 どこに書き込まれるのか分からなくなることはありません。

選んだプロファイルは URL に入るので（?profile=<name>）、 http://127.0.0.1:9119/skills?profile=worker のような深い場所へのリンクを開くと切り替えが 選ばれた状態になり、再読み込みしても保たれます。

プロファイルの別名から管理画面を起動すると、2つ目のサーバーを立てるのではなく、 端末共通の管理画面へ回されます。

worker dashboard
# → already running: opens the browser at ?profile=worker
# → not running:     starts the machine dashboard with "worker" preselected

これをやめて、そのプロファイル専用のサーバーを動かしたいときは --isolated を渡します （一本化する前の振る舞いです。プロファイルごとの管理画面を、あえて別々の認証で 公開したいときに役立ちます）。

チャットのタブも切り替えに従います。範囲を絞ったチャットは、選ばれた プロファイルの HERMES_HOME を持たせて PTY の子プロセスを立ち上げるので、そのプロファイルの モデル、スキル、記憶、セッションの履歴で会話が進みます。プロファイルを 切り替えると、端末のセッションは新しく始まります。

切り替えに引きずられず、プロファイルごとに残るものもあります。ゲートウェイの プロセス（hermes -p <name> gateway … で管理してください）、プロファイルごとの セッションのデータベース、そして定時実行の管理役（定時実行のページはすでに プロファイルをまたいで集め、独自の絞り込みを持っています）です。

前もって要るもの

既定の hermes-agent の導入には、HTTP まわりの部品も PTY の補助も入っていません。どちらも任意の追加分です。管理画面には FastAPI と Uvicorn（web の追加分）が要ります。チャットのタブにはさらに、疑似端末の後ろで TUI を立ち上げるための ptyprocess（POSIX では pty の追加分）が要ります。両方まとめて入れるには次のようにします。

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

web の追加分が FastAPI と Uvicorn を、pty が ptyprocess（POSIX）または pywinpty（Windows そのもの。ただし埋め込みの TUI 自体は今も WSL が要ります）を引き入れます。cd ~/.hermes/hermes-agent && uv pip install -e ".[all]" は両方の追加分を含むので、メッセージ連携や音声なども使いたいならこれがいちばん楽です。

必要なものがないまま hermes dashboard を実行すると、何を入れればよいか教えてくれます。画面側がまだ組み立てられておらず、npm が使えるときは、最初の起動時に自動で組み立てられます。

チャットのタブは hermes dashboard を起動すればいつでも付いてきます。ブラウザに埋め込まれたチャットの区画（PTY と WebSocket 越しに TUI を動かしています）は、追加のフラグなしにつねに使えます。

ページ

状況

最初のページには、導入したものの今の様子がまとめて出ます。

• エージェントの版と公開日
• ゲートウェイの状況 — 動いているか止まっているか、PID、つながっている基盤とその状態
• 動いているセッション — 直近5分に動きのあったセッションの数
• 最近のセッション — 直近20件のセッションを、モデル、メッセージ数、トークンの使用量、会話の冒頭とあわせて一覧にします

状況のページは5秒ごとに自動で更新されます。

資源のひっ迫を知らせる帯

動かしている端末のメモリやディスクが足りなくなってきたとき、管理画面の上に 帯が現れます（状況の定期取得と同じ情報を使うので、余計な通信は発生しません）。

• 「エージェントのメモリがほとんど残っておらず、再起動するかもしれません」 — ゲートウェイの

30秒ごとの心拍で測った、システムの空きメモリが*要注意*（128 MiB 未満または 15% 未満）か *危険*（64 MiB 未満または 5% 未満）まで下がったときです。

• 「エージェントが不意に再起動しました。メモリ不足の可能性が高いです」

— 前回の起動時に、メモリがひっ迫した状態できれいに終われなかったことが 生存記録に残っている場合です（OOM で落とされた疑い）。

• ディスクの警告 — ~/.hermes の置かれた区画がほぼ満杯です

（空きが 512 MB を切ると*要注意*、256 MB を切ると*危険*）。

いちばん重い警告だけがそのつど出ます（ディスク危険 > メモリ危険 > OOM による再起動 > ディスク要注意 > メモリ要注意）。閉じた記録はそのときのゲートウェイの起動の あいだだけ有効です。1つ閉じると次のものが出て、ゲートウェイの再起動や段階の上昇 （要注意 → 危険）でまた開きます。心拍が古くなっているときは、当てにならない警告を出すより 何も出しません。

チャット

チャットのタブには、Hermes の TUI（hermes --tui で出るものと同じ画面）がまるごとブラウザに埋め込まれています。端末の TUI でできることは、スラッシュコマンドも、モデルの選択も、ツール呼び出しの札も、Markdown の流し込みも、確認・権限・承認の問いかけも、見た目の着せ替えも、そっくり同じように動きます。管理画面が本物の TUI を動かし、その ANSI 出力を xterm.js の WebGL 描画で、升目がぴたりと合うように描いているからです。

しくみはこうです:

• /api/pty が、管理画面のセッションの合鍵で認証された WebSocket を開きます
• サーバーが POSIX の疑似端末の後ろで hermes --tui を立ち上げます
• 打鍵は PTY へ送られ、ANSI の出力がブラウザへ流れ戻ります
• xterm.js の WebGL 描画が升目を整数のピクセルに合わせて描き、マウスの追従（SGR 1006）、全角文字（Unicode 11）、罫線の記号もそのまま描かれます
• ブラウザの窓の大きさを変えると、@xterm/addon-fit によって TUI も追従します

既にあるセッションを再開する: セッションのタブで、どれかのセッションの横にある再生の印（▶）を押します。すると /chat?resume=<id> へ移り、--resume を付けて TUI が立ち上がり、履歴がまるごと読み込まれます。

セッションの切り替え（右の細い欄）: チャットのタブは、端末の横の細い欄に、ChatGPT のような会話の一覧を持っています。ページを離れずに会話を行き来できます。この欄はモデルの選択を上に、セッションの一覧をそのすぐ下に積み、画面の大半は端末が占めます。一覧には、選んでいるプロファイルの最近のセッションが並びます。題名（なければ冒頭のメッセージ）、最後に動いてからの時間、メッセージ数、そして CLI 以外のセッションでは元になった経路です。どれかの行を押せばその場で再開でき（端末がその会話の履歴を持って立ち上げ直されます）、今開いているものは強調されます。新しいチャットで新しいセッションが始まり、更新の操作で一覧を取り直せます。この欄は切り替え専用で、削除・改名・書き出し・まとめての片付けはセッションのタブにあります。画面が狭いときは、横から滑り出す区画に畳まれます。

前もって要るもの:

• Node.js（hermes --tui と同じです。TUI の一式は最初の起動時に組み立てられます）
• ptyprocess — pty の追加分で入ります（cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"、あるいは [all] でも両方入ります）
• POSIX のカーネル（Linux、macOS、WSL2）。/chat の端末の区画だけは POSIX の PTY が要ります。Windows そのものの Python には同じものがないので、Windows に直接入れた場合、管理画面のほかの部分（セッション、作業、指標、設定の編集）は動きますが、/chat のタブにはその機能のために WSL2 を使うよう促す帯が出ます。

ブラウザのタブを閉じると、サーバー側で PTY はきれいに片付けられます。開き直すと新しいセッションが立ち上がります。

自前のバックエンドではなく、別の端末で動いている管理画面に Hermes デスクトップ版をつなぎたい場合は、後述の離れたバックエンドの節を参照してください。

Hermes デスクトップ版を離れたバックエンドにつなぐ

Hermes デスクトップ版はふだん自分でローカルのバックエンドを立ち上げますが、離れた端末（仮想サーバー、自宅のサーバーなど）で動いている管理画面につなぐこともできます。設定 → ゲートウェイ → リモートゲートウェイからです。「デスクトップ版はバックエンドの準備ができたと言うのにチャットが動かない」という報告のいちばん多い原因がここにあります。デスクトップ版の準備確認は、実際のチャットの接続に必要なものより少ないことしか確かめていないからです。

デスクトップ版の「離れたバックエンドの準備ができた」という確認は GET /api/status を叩くだけで、これは誰でも見られる入口です。その端末で*何らかの*管理画面が動いていれば、すぐに応答が返ります。実際のチャットの接続は /api/ws（と /api/pty）への別の WebSocket で、この接続には、状況の確認がまったく触れない2つの関門があります。

1. 認証を通っていること。 管理画面が loopback 以外のアドレスに割り当てられていると、認証のしくみが働きます。利用者名とパスワード（同梱の利用者名とパスワードのしくみ）で守ってください。デスクトップ版は一度ログインすれば、そのセッションを使い捨ての引換券で WebSocket にも使い回します。しくみを何も設定していないと、loopback 以外に割り当てた管理画面は起動の時点で止まります。
2. 割り当てたアドレスがその接続元を許し、Host の見出しと一致すること。 loopback に割り当てている場合（127.0.0.1）は loopback からの接続しか受けないので、離れた端末は認証情報に関係なくソケットの層で弾かれます。loopback 以外のアドレス（--host 0.0.0.0）に割り当てて、接続元の IP を見る関門が離れた端末を通すようにしてください。デスクトップ版に入れる URL は、割り当てたのと同じホスト名で管理画面に届く必要があります。DNS の付け替えを防ぐ関門が、Host の見出しの一致を求めるからです。

離れた管理画面の準備

利用者名とパスワードを決めてから、届くアドレスに割り当てて管理画面を動かします。systemd のサービスなら次のようにします。

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/path/to/venv/bin/python -m hermes_cli.main dashboard \
    --host 0.0.0.0 --port 9119 --no-open

~/.hermes/.env の中身はこうです。

HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=<32+ random bytes; openssl rand -base64 32>

そのうえでデスクトップ版にリモート URL（たとえば http://VM_IP:9119）を入れ、その利用者名とパスワードでサインインします。設定できる項目のすべては利用者名とパスワードのしくみの節を参照してください。

/api/status で関門が働いていて "basic" も出ているのに、サインインしたあとでもデスクトップ版がつながらない場合は、基本的な準備より先の問題です。そのときは、やり直した同じ時間帯の desktop.log（設定 → ゲートウェイ → ログを開く）と管理画面側のログの両方を取り、/api/ws の切断コードを探してください（4403 = 要求の関門がチャットの WebSocket を弾いた。Host や接続元の食い違いなど。4401 = WebSocket の引換券が認証を通らなかった）。

設定

config.yaml を入力欄で編集するページです。150以上ある設定の項目はすべて DEFAULT_CONFIG から自動で拾われ、タブに分かれた分類にまとめられます。

• model — 既定のモデル、プロバイダ、基点となる URL、推論の設定
• terminal — 端末の実体（local/docker/ssh/modal）、制限時間、シェルの好み
• display — 見た目、ツールの進み具合、再開時の表示、待機表示の設定
• agent — 折り返しの上限、ゲートウェイの制限時間、サービスの等級
• delegation — サブエージェントの上限、推論のかけ具合
• memory — 記憶のしくみの選択、文脈への差し込みの設定
• approvals — 危ないコマンドの承認のしかた（賢く／手動／なし）
• そのほかにも — config.yaml のどの節にも、対応する入力欄があります

取りうる値が決まっている項目（端末の実体、見た目、承認のしかたなど）は選択式になります。真偽の値は切り替えの形になり、それ以外は文字の入力欄です。

操作:

• 保存 — その場で config.yaml に書き込みます
• 既定に戻す — すべての項目を既定値に戻します（保存を押すまでは書き込まれません）
• 書き出し — 今の設定を JSON で取り出します
• 読み込み — JSON の設定ファイルを渡して、今の値を置き換えます

API キー

API キーや認証情報を置いている .env を管理します。キーは分類ごとにまとめられます。

• LLM のプロバイダ — OpenRouter、Anthropic、OpenAI、DeepSeek など
• ツールの API キー — Browserbase、Firecrawl、Tavily、ElevenLabs など
• メッセージの基盤 — Telegram、Discord、Slack のボットの合鍵など
• エージェントの設定 — API_SERVER_ENABLED のような、秘密ではない環境変数

キーごとに次のものが出ます。

• 今設定されているかどうか（値は伏せた形で少しだけ見えます）
• 何のためのものかの説明
• そのプロバイダの登録・鍵の発行ページへのリンク
• 値を入れたり更新したりする欄
• 取り除くための削除ボタン

込み入ったもの、めったに使わないものは、既定では切り替えの裏に隠れています。

セッション

エージェントのセッションを見て回るページです。行ごとに、セッションの題名、元になった基盤の印（CLI、Telegram、Discord、Slack、定時実行）、モデル名、メッセージ数、ツールの呼び出し回数、最後に動いてからの時間が出ます。今動いているセッションには脈打つ印が付きます。

• 絞り込み — 会話 / 自動 / すべてのタブで一覧の範囲を切ります。*会話*（既定）は人との会話を見せ、自動のものの雑音（定時実行、ツール、API、ACP のセッション）を隠します。*自動*はそれだけを見せ、*すべて*は全部見せます。さらに元の経路を1つに絞る選択欄もあります（Telegram だけ、など）。検索も今の絞り込みに従います。
• 検索 — FTS5 を使って、すべてのメッセージの中身を全文検索します。結果には該当箇所が強調されて出て、開くと最初に一致したメッセージまで自動でたどり着きます。
• 統計 — 上の帯に、セッションの総数、保管されている中で動いているものの数、書庫に入れた数、メッセージの総数、そして経路ごとの内訳が出ます。
• 展開 — セッションを押すと、そのメッセージの履歴がすべて読み込まれます。メッセージは役割（利用者、アシスタント、システム、ツール）ごとに色分けされ、Markdown として構文の色付きで描かれます。
• ツールの呼び出し — ツールを呼んだアシスタントのメッセージには、関数名と JSON の引数が畳めるかたまりで出ます。
• 改名 — セッションの題名をその場で付けたり消したりできます（鉛筆の印）。
• 書き出し — セッション（付帯情報とメッセージの履歴すべて）を JSON で取り出せます（下向き矢印の印）。
• 片付け — 見出しにある「古いセッションを片付ける」のボタンで、N 日より前に終わったセッションを消します。
• 削除 — ゴミ箱の印で、セッションとそのメッセージの履歴を取り除きます。

ログ

エージェント、ゲートウェイ、エラーの記録を、絞り込みと追いかけ表示つきで見られます。

• ファイル — agent、errors、gateway の記録を切り替えます
• 水準 — 記録の水準で絞ります。ALL、DEBUG、INFO、WARNING、ERROR
• 出どころ — どの部品からかで絞ります。all、gateway、agent、tools、cli、cron
• 行数 — 何行表示するかを選びます（50、100、200、500）
• 自動更新 — 5秒ごとに新しい行を取りに行く、追いかけ表示の切り替えです
• 色分け — 記録の行は重さで色が付きます（エラーは赤、警告は黄、詳細は薄く）

集計

セッションの履歴から計算した、使用量と費用の集計です。期間（7日、30日、90日）を選ぶと次のものが見られます。

• 要約の札 — トークンの総数（入力／出力）、使い回しの当たった割合、見積もりまたは実際の総費用、そしてセッションの総数と1日あたりの平均
• 日ごとのトークンの図 — 入力と出力のトークンを日ごとに積み上げた棒の図で、指を乗せると内訳と費用が出ます
• 日ごとの内訳の表 — 日付、セッション数、入力トークン、出力トークン、使い回しの当たった割合、その日の費用
• モデルごとの内訳 — 使ったモデルごとに、セッション数、トークンの使用量、見積もりの費用を並べた表

定時実行

エージェントへの指示を繰り返し走らせる、予約した作業を作って管理します。

• 作成 — 名前（任意）、指示、cron の書き方（0 9 * * * など）、そして届け先（手元、Telegram、Discord、Slack、メール）を入れます
• 作業の一覧 — 作業ごとに、名前、指示の冒頭、予定の式、状態の札（有効／一時停止／エラー）、届け先、前回の実行時刻、次回の実行時刻が出ます
• 一時停止・再開 — 作業を有効と一時停止のあいだで切り替えます
• 編集 — あらかじめ埋まった小窓を開き、指示、予定、名前、届け先を変えます
• 今すぐ実行 — ふだんの予定とは別に、その場で走らせます
• 削除 — 予約した作業を消します

プロファイル

プロファイルを作って管理します。設定もスキルもセッションも別々に持つ、切り離された Hermes です。

• プロファイルの札 — それぞれにモデルとプロバイダ、スキルの数、ゲートウェイの状態、説明、そして印（使用中、既定、別名）が出ます
• 作成 — 名前と、任意で「既定から複製」「まるごと複製」「同梱のスキルなし」の選択、説明、モデルを入れます。専用のプロファイル作成ページ（/profiles/new）では、モデル・MCP・スキルまで含めた一式の流れが使えます
• スキルとツールの管理 — そのプロファイルに絞ったスキルのページへ移ります（横の欄のプロファイル切り替えも合わせて動きます）
• 使用中にする — これから始まる CLI とゲートウェイの実行が拾う、既定のプロファイルを切り替えます（hermes profile use と同じです）。管理画面が管理する対象は*変わりません*。そちらはプロファイルの切り替えの仕事です
• モデル・説明・SOUL の編集 — その場で編集して、そのプロファイルへ書き込みます
• 改名・削除 — 名前付きのプロファイルだけです

スキル

入れてあるスキルとツール群を見て回り、検索し、有効・無効を切り替え、拠点から新しいものを入れられます。スキルは ~/.hermes/skills/ から読み込まれ、分類ごとにまとめられます。

• 検索 — 入れてあるスキルとツール群を、名前・説明・分類で絞り込みます
• 分類の絞り込み — 分類の丸い札を押して一覧を絞ります（MLOps、MCP、Red Teaming、AI など）
• 切り替え — スキルを1つずつ有効・無効にできます。変更は次のセッションから効きます。
• ツール群 — 別の表示で、内蔵のツール群（ファイル操作、ウェブ閲覧など）を、有効かどうか、準備に何が要るか、どのツールを含むかとあわせて見られます
• 拠点を見る — 3つ目の表示では、すべての出どころにまたがってスキルの拠点を検索し（hermes skills search と同じです）、見つけたものを識別子で入れながら導入の記録をその場で流し、入れてあるスキルをまとめて新しくする「すべて更新」のボタンも用意されています。

MCP

MCP のサーバーを CLI なしで管理します。hermes mcp が読むのと同じ config.yaml の mcp_servers のかたまりです。

自分の MCP サーバー:

• 追加 — HTTP/SSE のサーバー（URL）か stdio のサーバー（コマンドと引数）を登録します。stdio のサーバーには KEY=VALUE の形の環境変数も付けられます
• 有効・無効 — サーバーを消さずに切り替えます。無効にしたサーバーも設定に残るので、あとで戻せます。次のゲートウェイの再起動から効きます。
• 接続の確認 — サーバーにつなぎ、ツールを一覧し、切ります。エージェントが頼りにする前に、つながることを確かめられます
• 取り除く — 設定からサーバーを消します
• 秘密らしい形の環境変数の値は、一覧では伏せられます

目録: Nous が認めた MCP サーバー（同梱の optional-mcps/ の 目録）を見て、どれでも一押しで入れられます。API キーが要るものは その場で入力を求められ、値は .env へ書かれます。hermes mcp catalog / hermes mcp install が使うのと同じ目録です。

Webhook

動的な Webhook の購読を管理します。 先にメッセージの設定で Webhook の基盤を有効にしておく必要があり、そうでないときは その旨がページに出ます。

• 作成 — 名前、説明、拾う出来事の条件、届け先、任意で直接届ける方式、そしてエージェントへの指示を入れます。作ると、経路の URL と一度きりの HMAC の秘密がページに出るので、写し取ってください。
• 有効・無効 — 購読を切り替えます。無効にした経路も購読のファイルには残りますが、ゲートウェイは届いた出来事を拒みます（403）。ゲートウェイはこのファイルを動いたまま読み直すので、次の出来事から効きます。再起動は要りません。
• 一覧 — 購読ごとに、URL、拾う出来事、届け先が出ます
• 削除 — 購読を取り除きます

紐付け

メッセージ連携の利用者を CLI なしで承認・取り消しできます。離れた場所の管理者が、 紐付けたゲートウェイに Telegram や Discord などの利用者を迎え入れるときの入口です。 hermes pairing と同じことがすべてできます。

• 保留中の申請 — それぞれに基盤、コード、利用者、経過時間が出て、承認のボタンが付きます
• 承認済みの利用者 — それぞれに基盤と利用者が出て、取り消しのボタンが付きます
• 保留中をすべて消す — 残っている紐付けのコードをまとめて捨てます

経路

Hermes をどのメッセージの基盤にもブラウザからつなげます。hermes setup gateway と まったく同じことができます。このページには、対応するすべての経路（Telegram、 Discord、Slack、Matrix、Mattermost、WhatsApp、Signal、BlueBubbles/iMessage、 メール、SMS/Twilio、DingTalk、Feishu/Lark、WeCom、WeChat、QQ Bot、Yuanbao、それに API サーバーと Webhook の受け口）が、今の接続の状態とあわせて並びます。

• 設定 — 経路ごとの入力の形が開き、その経路に必要な項目だけが出ます（ボットの合鍵、アプリの合鍵、サーバーの URL、許可の一覧など）。秘密はパスワードの入力欄として描かれ、伏せた形で保存されます。空のままにすると今の値が残ります。必須の項目には印が付き、内容が確かめられます。「準備の手引き」のリンクから、その基盤の認証情報の説明へ行けます。
• 有効・無効 — 経路を切り替えます。認証情報はディスクに残り、有効かどうかだけが変わります。
• 接続の確認 — その経路が設定済みか、有効か、ゲートウェイから見て実際につながっているかを確かめます。
• ゲートウェイの再起動 — 認証情報は ~/.hermes/.env に、有効かどうかは config.yaml に書かれます。ゲートウェイは次の再起動で、有効な経路それぞれにつなぎます。その再起動はこのページから直接かけられます。

システム

導入したもの全体に関わる操作を1か所にまとめた盤です。

• ホスト — 今の端末の様子: OS とカーネル、アーキテクチャ、ホスト名、Python と Hermes の版、CPU のコア数と使用率、メモリ、Hermes の置き場所のディスク使用量、稼働時間、負荷の平均。（CPU・メモリ・ディスクは psutil が入っているときに取れます。素性の項目はつねに出ます。）Hermes の版には更新の状態の札（最新／N コミット遅れ）と更新を確認のボタンが付きます。git で入れたものに更新があるときは、今すぐ更新のボタンから確認の小窓が開き、いくつのコミットを取り込むかを示してから、裏側で hermes update を走らせます。Docker や Nix で入れた場合は管理画面からその場で更新できないので、代わりに正しい外部のコマンドが表示されます。
• Nous Portal — ログインの状態、使っている推論のプロバイダ、そしてツールのゲートウェイの経路表（どのツールが Portal 経由でどれが手元で動くか）と、契約を管理するリンク。hermes portal を読み取り専用で写したものです。
• スキルの世話役 — 裏で動くスキルの手入れの状態（動作中／一時停止、間隔、前回の実行）と、一時停止・再開、今すぐ実行のボタン。hermes curator と同じものです。
• ゲートウェイ — メッセージのゲートウェイの起動・停止・再起動と、今の状態（動作中／停止、PID、状態）
• 記憶 — 外部の記憶のしくみを選ぶ（あるいは内蔵だけにする）ほか、内蔵の MEMORY.md / USER.md を初期化します
• 認証情報の持ち回り — エージェントが順に使い分ける API キーを（プロバイダごとに）足したり外したりします。一覧では伏せられ、生の値はエージェントにしか渡りません。
• 運用 — doctor、安全性の点検、控えの作成、控えからの復元、スキルの更新、システムプロンプトの大きさの内訳の表示、支援用の情報の書き出し、退役した設定の移行を実行します。それぞれ裏側の処理として走り、その記録がページに流れます。
• 保存点 — /rollback の影の置き場所の大きさを見て、片付けます
• シェルのフック — 設定されたフックを、同意と実行可能かの状態とあわせて並べ、フックを作り（出来事、コマンド、対象の条件、制限時間、そして同意を与えるかの選択）、外せます。フックは任意のコマンドを走らせるので、作成の欄には安全上の注意が付き、同意を与えたあとでなければ動きません。

シェルのフックを作るところ（同意の確認と、任意のコマンドが走るという注意に注目してください）:

/reload スラッシュコマンド

管理画面を入れた変更では、対話式の CLI に /reload というスラッシュコマンドも加わりました。管理画面から（あるいは .env を直に書き換えて）API キーを変えたあと、動いている CLI のセッションで /reload を打てば、再起動せずにその変更を取り込めます。

You → /reload
  Reloaded .env (3 var(s) updated)

これは ~/.hermes/.env を、動いているプロセスの環境に読み直します。管理画面から新しいプロバイダの鍵を足して、すぐ使いたいときに便利です。

REST の API

管理画面は、画面側が使っている REST の API を公開しています。自動化のために、これらの入口を直に呼ぶこともできます。

GET /api/status

エージェントの版、ゲートウェイの状態、基盤ごとの状態、動いているセッションの数を返します。

応答にはさらに、参考として2つの資源のかたまりが載ります（ components / overall の健全性の判定には影響しません）。

• memory — ゲートウェイの30秒ごとの心拍と

生存記録から絞り出したものです。項目は pressure（ok / elevated / critical / unknown）、gateway_rss_mb、system_total_mb、system_available_mb、 swap_used_mb、sampled_at、boot_id、last_boot_unclean、 last_boot_suspected_oom。ひっ迫の度合いは、システムの空きメモリが 128 MiB（または 15%）を切ると elevated、64 MiB（または 5%）を切ると critical です。これは、 そのあときれいに終われなかったときに OOM で落とされた疑いとして印が付くのと 同じ水準です。150秒より古い（あるいは未来の日付の）心拍は、 数値はそのままに pressure だけ unknown に落とされるので、止まったゲートウェイの 最後の値が今の値のふりをすることはありません。

• disk — ~/.hermes の置かれた区画を shutil.disk_usage() でその場で測ったものです。

項目は pressure、free_mb、total_mb、used_percent、 sampled_at。ひっ迫の度合いは、空きが 512 MB を切る（または使用率が 85% 以上で 残りが 4 GB 未満）と elevated、空きが 256 MB を切る（または使用率が 95% 以上で 残りが 1 GB 未満）と critical です。

どちらの採取も安全側に倒してあります。測定に失敗しても、状況の入口ごと失敗させるのではなく そのかたまりを {"pressure": "unknown"} に落とします。/api/status は誰でも見られるので、 数値は粗くしてあります（MB 単位、パーセントも整数）。

GET /api/sessions

直近20件のセッションを、付帯情報（モデル、トークン数、時刻、冒頭）とあわせて返します。

GET /api/config

今の config.yaml の中身を JSON で返します。

GET /api/config/defaults

設定の既定値を返します。

GET /api/config/schema

設定の項目それぞれについて、型、説明、分類、そして当てはまる場合は選べる値を書いた定義を返します。画面側はこれを使って、項目ごとに正しい入力の部品を描いています。

PUT /api/config

新しい設定を保存します。本文は {"config": {...}} です。

GET /api/env

分かっている環境変数をすべて、設定済みかどうか、伏せた値、説明、分類とあわせて返します。

PUT /api/env

環境変数を設定します。本文は {"key": "VAR_NAME", "value": "secret"} です。

DELETE /api/env

環境変数を取り除きます。本文は {"key": "VAR_NAME"} です。

GET /api/sessions/\{session_id\}

1つのセッションの付帯情報を返します。

GET /api/sessions/\{session_id\}/messages

メッセージの履歴を、件数を区切ったページで返します。ツールの呼び出しと時刻も含みます。既定では最新の500件を時系列で返します。細かく分けたいときは limit（最大500）、offset、order=oldest|latest を使ってください。

GET /api/sessions/search

メッセージの中身を全文検索します。問い合わせの引数は q です。一致したセッションの ID を、強調した抜粋とあわせて返します。

DELETE /api/sessions/\{session_id\}

セッションとそのメッセージの履歴を消します。

GET /api/logs

記録の行を返します。問い合わせの引数は file（agent/errors/gateway）、lines（行数）、level、component です。

GET /api/analytics/usage

トークンの使用量、費用、セッションの集計を返します。問い合わせの引数は days（既定は30）です。応答には日ごとの内訳とモデルごとの合計が入ります。

GET /api/cron/jobs

設定されている予約の作業を、状態、予定、実行の履歴とあわせてすべて返します。

POST /api/cron/jobs

新しい予約の作業を作ります。本文は {"prompt": "...", "schedule": "0 9 * * *", "name": "...", "deliver": "local"} です。

POST /api/cron/jobs/\{job_id\}/pause

予約の作業を一時停止します。

POST /api/cron/jobs/\{job_id\}/resume

一時停止した予約の作業を再開します。

POST /api/cron/jobs/\{job_id\}/trigger

予定とは別に、予約の作業をその場で走らせます。

DELETE /api/cron/jobs/\{job_id\}

予約の作業を消します。

GET /api/skills

すべてのスキルを、名前、説明、分類、有効かどうかとあわせて返します。

PUT /api/skills/toggle

スキルの有効・無効を切り替えます。本文は {"name": "skill-name", "enabled": true} です。

GET /api/tools/toolsets

すべてのツール群を、名札、説明、含むツールの一覧、有効・設定済みかどうかとあわせて返します。

管理用の入口

MCP、経路、Webhook、紐付け、システムの各ページを支えているものです。どれも /api/ のほかの部分と同じ認証のしくみの後ろにあります。

認証（関門のある形）

管理画面を公開のアドレスや loopback 以外のアドレス（127.0.0.1 / localhost 以外のすべて）に割り当てると、Hermes Agent は認証の関門を働かせます。どの要求も、確かめられたセッションの合鍵を持っていなければログインのページへ送り返されます。同梱のしくみは3つあります。

• 利用者名とパスワード — 自前で立てた／構内の／自宅の管理画面に認証を付ける、いちばん手軽な方法です。外部の身元のしくみは要りません。信頼できるネットワークの中か VPN の後ろでだけ使ってください。インターネットへの公開には向きません。
• OAuth（Nous Portal） — ホスト型の導入や、インターネットから届く管理画面向けで、離れた Hermes デスクトップ版からの接続にもこれをお勧めします。ログインのたびに Nous のアカウントで確かめられるので、インターネットに面した用途に耐えるのはこのしくみです。
• 自前の OIDC — 標準の OpenID Connect を使って、自分の身元のしくみ（Keycloak、Auth0、Okta、Google、OIDC の橋渡しを介した GitHub など）を持ち込むためのものです。Nous Portal は関わりません。規格に沿った OIDC のサーバーを前に立てるなら、インターネットへの公開にも耐えます。

loopback に割り当てた、運用者自身のための管理画面には何も起きません。認証もログインのページもありません。

関門が働く条件

関門が働くのは、割り当てたアドレスが 127.0.0.1、::1、localhost のいずれでもないとき、かつそのときだけです。0.0.0.0（や RFC1918 の私設アドレス、LAN のアドレス）に割り当てると働きます。古い --insecure のフラグではもう無効にできません。後方互換のために受け付けはしますが、警告を出して無視されます。

失敗したら閉じる作り

関門が働く条件なのに DashboardAuthProvider が1つも登録されていない場合（Nous の差し込みも自作の差し込みもない場合）、hermes dashboard ははっきりしたエラーを出して起動を断ります。「既定では拒むが実際は何でも通す」といった逃げ道はありません。設定を誤った関門つきの管理画面が、そのまま立ち上がることはないのです。

hermes dashboard --host 0.0.0.0 を対話的に（本物の端末で）実行していて、まだ何のしくみも設定していないとき、Hermes はただ失敗するのではなく、その場で設定するかを聞いてきます。利用者名とパスワードを選べば（config.yaml に dashboard.basic_auth が書かれ、数秒で動き始めます）、OAuth を選べば hermes dashboard register を案内されます。対話的でない呼び出し（Docker/s6、CI、流し込みでの実行）はこの問いかけを飛ばして上記の「失敗したら閉じる」エラーに当たるので、人が見ていない導入が認証なしで立ち上がることはありません。

既定のしくみ: Nous Research

同梱の plugins/dashboard_auth/nous の差し込みはつねに入っていて、自動で読み込まれます。クライアント ID が設定されると、nous という名前の DashboardAuthProvider を自分で登録します。

ログインのたびに Nous Portal で確かめられ、Nous のアカウントで守られているので、管理画面をインターネットへ公開するのに耐えるのは、この Nous のしくみです。

管理画面を登録する

Nous のしくみを使うには、OAuth のクライアント ID（agent:{id} の形）が要ります。手に入れ方は2つあります。

• CLI — hermes dashboard register。 管理画面を動かす端末で実行してください。今の Nous のログインを解決し（ログインしていなければ先に hermes setup を実行してください）、自前の管理画面用の OAuth クライアントを Portal に登録して、HERMES_DASHBOARD_OAUTH_CLIENT_ID を ~/.hermes/.env に書き込んでくれます。任意のフラグとして --name（人が読む名札。なければ自動で付きます）と --redirect-uri（インターネットに面した端末向けの、公開の HTTPS の戻り先）があります。

hermes dashboard register
# ✓ Registered dashboard "swift_falcon"
# …writes HERMES_DASHBOARD_OAUTH_CLIENT_ID to ~/.hermes/.env

• 画面 — ローカルダッシュボードのページ。 Nous Portal の /local-dashboards を開くと、自前の管理画面をブラウザから登録・命名・管理・取り消しできます。出てきた agent:{id} のクライアント ID を HERMES_DASHBOARD_OAUTH_CLIENT_ID（環境変数）か dashboard.oauth.client_id（config.yaml）に写してください。CLI から登録した管理画面を取り消すのも、ここです。

設定

この差し込みは2か所を読み、環境変数に空でない値が入っているときはそちらが勝ちます。

config.yaml — こちらが正式な置き場所です。

dashboard:
  oauth:
    client_id: agent:01HXYZ…             # required to engage the gate

環境変数 — 運用者による上書きです。

Hermes Agent の決まり（~/.hermes/.env は API キーと秘密のためのものです）に従い、手元での開発、構内の導入、自分で直に面倒を見る導入では、この値は config.yaml に書くことをお勧めします。環境変数の道が用意されているのは、ホスティング基盤の秘密の注入が、イメージの中の config.yaml を誰も編集せずに導入ごとの client_id を押し込めるようにするためで、それが本来の用途です。

環境変数が空のときは設定されていないものとして扱われるので、用意だけされて中身の入っていない基盤側の秘密が、正しい config.yaml の値をうっかり覆い隠すことはありません。

どちらからも client_id が得られない場合、差し込みは具体的な理由を報告し、管理画面が「失敗したら閉じる」で出すエラーが、何を直せばよいかを正確に教えてくれます。

Refusing to bind dashboard to 0.0.0.0 — the auth gate engages on
non-loopback binds, but no auth providers are registered.

Bundled providers reported these issues:
  • nous: HERMES_DASHBOARD_OAUTH_CLIENT_ID is not set (and
    dashboard.oauth.client_id in config.yaml is empty). …

Configure an auth provider before exposing the dashboard:
  • Password: set dashboard.basic_auth.username + password_hash in config.yaml
  • OAuth: run `hermes dashboard register` (Nous Portal) or install a
    DashboardAuthProvider plugin.
There is no unauthenticated public-bind option — to keep it local, bind
127.0.0.1 and tunnel in (SSH / Tailscale).

実際にやってみる: Nous Research

ログイン済みの Hermes から、Nous で守られた管理画面まで3手順です。

1. ログインして管理画面を登録する。 hermes dashboard register は今の Nous のログインを使って OAuth のクライアントを用意し、HERMES_DASHBOARD_OAUTH_CLIENT_ID を ~/.hermes/.env に書き込みます。

hermes setup            # if you're not already logged into Nous Portal
hermes dashboard register
# ✓ Registered dashboard "swift_falcon"
# …writes HERMES_DASHBOARD_OAUTH_CLIENT_ID to ~/.hermes/.env

2. 届くアドレスで管理画面を動かす。 loopback 以外への割り当てで OAuth の関門が働き、今書き込んだ client_id が nous のしくみを目覚めさせます。

hermes dashboard --host 0.0.0.0 --port 9119 --no-open

3. ログインする。 http://<host>:9119/ を開くと /login へ送られます。Sign in with Nous Research を押して Portal で認証すると、認証済みの管理画面に戻ってきます。関門が働いているかは、どの端末からでも確かめられます。

curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["nous"]

そのあと GET /api/auth/me は、確かめられたセッション（provider: nous）を返します。インターネットに面した端末では、--redirect-uri https://hermes.example.com/auth/callback を付けて登録し、HERMES_DASHBOARD_PUBLIC_URL を設定して OAuth の戻り先が公開の URL になるようにしてください（公開 URL の上書きを参照）。

利用者名とパスワードのしくみ（OAuth の身元基盤なし）

OAuth の身元基盤を結線したくない場合 —「管理画面にとりあえずパスワードを掛けたい」という自前の導入 — 同梱の plugins/dashboard_auth/basic の差し込みが、OAuth の転送ではなく利用者名とパスワードで認証する basic という名前の DashboardAuthProvider を登録します。

これは OAuth のしくみとまったく同じ関門に差し込まれます。loopback 以外への割り当てで関門が働き、ログインのページは（「◯◯でログイン」のボタンではなく）認証情報の入力欄を描き、ログインから先のすべて — セッションの合鍵、裏での更新、WebSocket の引換券、ログアウト、監査の記録 — は OAuth の道とまったく同じです。セッションは、このしくみが自分で作る、状態を持たない HMAC で署名した合鍵なので、データベースも外部の身元基盤も要りません。パスワードのハッシュには標準ライブラリの scrypt を使います（外部の部品は要りません）。

設定

Nous のしくみと同じく、config.yaml（正式な置き場所）を読み、環境変数に空でない値があればそちらが勝ちます。username と、password_hash（こちらが望ましい）か password のどちらかがそろったときだけ働き、そうでなければ何もしないので、OAuth を使う人にも loopback で使う人にも影響しません。

config.yaml:

dashboard:
  basic_auth:
    username: admin
    # Preferred — no plaintext at rest. Compute with:
    #   python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))"
    password_hash: "scrypt$16384$8$1$…$…"
    # ...or a plaintext password (hashed in-memory at load; less safe at rest):
    # password: "s3cret"
    secret: "<32+ random bytes, base64 or hex>"  # token-signing key
    session_ttl_seconds: 43200                    # optional; access-token lifetime (default 12h)

環境変数による上書き:

/auth/password-login の入口は接続元の IP ごとに回数が制限され（既定は毎分10回まで。超えると HTTP 429）、知らない利用者のときも間違ったパスワードのときも同じ 401 Invalid credentials を返すので、利用者名を探る手掛かりには使えません。

実際にやってみる: 利用者名とパスワード

何もない状態から、信頼できるネットワークでパスワードの掛かった管理画面まで3手順です。

1. ~/.hermes/.env に認証情報を書く。 平文を残さないようパスワードをハッシュにし、再起動を越えてセッションが残るように、変わらない署名の秘密も決めます。

# Compute a scrypt hash of your chosen password:
HASH=$(python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('choose-a-strong-password'))")

cat >> ~/.hermes/.env <<EOF
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH=$HASH
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

2. 届くアドレスで管理画面を動かす。 loopback 以外への割り当てで関門が働き、利用者名とハッシュが basic のしくみを目覚めさせます。

hermes dashboard --host 0.0.0.0 --port 9119 --no-open

3. ログインする。 http://<host>:9119/ を開くと /login へ送られ、そこには（「◯◯でログイン」のボタンではなく）認証情報の入力欄が出ます。admin と自分のパスワードを入れれば、認証済みの管理画面に着きます。関門が働いているかは、どの端末からでも確かめられます。

curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["basic"]

そのあと GET /api/auth/me は、確かめられたセッション（provider: basic）を返します。これは VPN の後ろに置いてください。上の注意を参照してください。公開の端末には、Nous Research か自前の OIDC のしくみを使ってください。

パスワードのしくみを自分で書く

basic は拡張の口に対する実装の1つにすぎません。どんな差し込みでもパスワードのしくみを登録できます。DashboardAuthProvider を継承したクラスに supports_password = True を立て、complete_password_login(*, username, password) -> Session を実装してください（拒むときは InvalidCredentialsError を、後ろの保管先が落ちているときは ProviderError を投げます）。パスワードだけのしくみなら、OAuth の start_login / complete_login は NotImplementedError のままで構いません。LDAP のバインドや、認証情報のデータベース、そのほか転送を伴わない認証の方式はこの道を通ります。入力欄も、経路も、合鍵も、更新も、枠組みのほうが引き受けてくれます。

自前の OIDC のしくみ

自分で身元のしくみを運用している場合、同梱の plugins/dashboard_auth/self_hosted の差し込みが、標準の OpenID Connect を使って管理画面をそこに認証させます。身元基盤ごとのコードも要らず、Nous Portal も関わりません。規格に沿った OIDC のサーバーで確かめられていて、どれでも動きます。

> Authentik · Keycloak · Zitadel · Authelia · Auth0 · Okta · Google · …

Nous のしくみと同じく自動で読み込まれ、設定されたときにだけ自分を登録するので、loopback の管理画面では何もしません。

設定

issuer と client_id（クライアントの秘密を持たない、PKCE を使う公開のクライアント）を設定します。差し込みは身元基盤の authorization_endpoint、token_endpoint、jwks_uri を {issuer}/.well-known/openid-configuration から取ってくるので、接続先の URL を自分で書き込む必要はありません。

config.yaml — こちらが正式な置き場所です。

dashboard:
  oauth:
    provider: self-hosted
    self_hosted:
      issuer: https://auth.example.com/application/o/hermes/   # required
      client_id: hermes-dashboard                              # required
      scopes: "openid profile email"                           # optional (this is the default)

環境変数 — 運用者による上書きです（空でない値が入っていれば config.yaml より優先され、空の値は設定されていないものとして扱われます）。

身元基盤の側では、認可コード + PKCE（S256）で動く公開のアプリケーション／クライアントを登録し、管理画面の戻り先を許可する URI に加えてください。戻り先は <dashboard public URL>/auth/callback です（中継の後ろで公開 URL をどう決めるかは公開 URL の上書きを参照）。

何を確かめているか

このしくみは、OpenID Connect の ID トークン（RS256/ES256）を、見つけてきた jwks_uri に照らして確かめます。iss と aud の主張は、設定した issuer と client_id に固定されます。標準の OIDC の主張は、管理画面のセッションに次のように対応します。

身元を決めるのは ID トークンのほうで、アクセストークンは中身を読まないものとして扱われます（OIDC の仕様は、これが JWT であることを求めていません）。接続先の URL は HTTPS であることが求められます（手元で開発する身元基盤のために、loopback の http:// は許されます）。また、見つけてきた設定が掲げる issuer は、こちらが設定したものと一致していなければなりません（末尾のスラッシュの違いは大目に見られます）。身元基盤が更新用の合鍵を出す場合は、標準の refresh_token の付与を使って裏で認証をやり直します。ログアウトでは、掲げられていれば身元基盤の RFC 7009 の revocation_endpoint を呼びます。

> 秘密を持つクライアント（client_secret のあるもの）にはまだ対応していません。ブラウザに面した管理画面ではふつうそうするように、公開 + PKCE のクライアントを設定してください。

実際にやってみる: Keycloak

Keycloak は、手元で試すのにいちばん立ち上げやすい自前の OIDC サーバーの1つです。開発向けの起動なら単一のコンテナで動き（データベースはメモリ上）、お手本のような OIDC の探索を掲げます。この道筋をたどれば、何もない状態から管理画面へのログインまで数分です。

1. 用意した realm つきで Keycloak を動かす。 この realm の書き出しを realm-hermes.json として保存してください。hermes という realm、PKCE を使う公開のクライアント（hermes-dashboard）、そして試験用の利用者を定義していて、起動時にまとめて読み込まれるので、管理画面で押すものは何もありません。

{
  "realm": "hermes",
  "enabled": true,
  "clients": [
    {
      "clientId": "hermes-dashboard",
      "name": "Hermes Agent Dashboard",
      "enabled": true,
      "publicClient": true,
      "standardFlowEnabled": true,
      "protocol": "openid-connect",
      "redirectUris": ["http://localhost:9119/auth/callback"],
      "webOrigins": ["http://localhost:9119"],
      "attributes": { "pkce.code.challenge.method": "S256" }
    }
  ],
  "users": [
    {
      "username": "testuser",
      "enabled": true,
      "emailVerified": true,
      "email": "testuser@example.com",
      "firstName": "Test",
      "lastName": "User",
      "credentials": [
        { "type": "password", "value": "testpassword", "temporary": false }
      ]
    }
  ]
}

そのファイルを読み込み用のディレクトリに載せて起動します（Keycloak 26 以降）。

docker run --rm -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -v "$PWD/realm-hermes.json:/opt/keycloak/data/import/realm-hermes.json:ro" \
  quay.io/keycloak/keycloak:26.0 \
  start-dev --import-realm

立ち上がると、この realm は http://localhost:8080/realms/hermes/.well-known/openid-configuration で標準の OIDC の探索を掲げます（issuer は http://localhost:8080/realms/hermes です）。管理の画面は http://localhost:8080/（admin / admin）にあります。

2. 管理画面をそこに向ける。 自前の OIDC の差し込みは loopback の http:// の issuer を許すので（loopback 以外の issuer には HTTPS が要ります）、手元の Keycloak はそのまま使えます。

export HERMES_DASHBOARD_OIDC_ISSUER="http://localhost:8080/realms/hermes"
export HERMES_DASHBOARD_OIDC_CLIENT_ID="hermes-dashboard"
export HERMES_DASHBOARD_PUBLIC_URL="http://localhost:9119"
hermes dashboard --host 0.0.0.0 --port 9119 --no-open

HERMES_DASHBOARD_PUBLIC_URL は、OAuth の戻り先が http://localhost:9119/auth/callback であることを管理画面に伝えます。これが上の realm に 登録した戻り先の URI です。OAuth の関門を働かせているのは、 0.0.0.0（loopback 以外）への割り当てのほうです。

3. ログインする。 http://localhost:9119/ を開くと /login へ送られます。Sign in with Self-Hosted OIDC を押し、Keycloak で testuser / testpassword として認証すると、認証済みの管理画面に戻ってきます。横の欄には Logged in as Test User via self-hosted と出て、GET /api/auth/me は確かめられたセッション（provider: self-hosted、email: testuser@example.com）を返します。

> 別のホストやポートで動かしたり見たりする場合は、その出どころの > …/auth/callback を、Keycloak の管理画面でクライアントの有効な戻り先の URIに > 加えてください（Clients → hermes-dashboard → Settings）。同じやり方が > Authentik、Zitadel、Authelia などの OIDC サーバーでも通じます。違うのは issuer の > URL とクライアント登録の画面だけです。

公開 URL の上書き

既定では、管理画面は OAuth の戻り先の URL を要求から組み立て直します。X-Forwarded-Host + X-Forwarded-Proto + X-Forwarded-Prefix を使います（uvicorn が proxy_headers=True で動いているときで、関門が働いているときは start_server がこれを有効にします）。この3つの見出しを正しく渡す中継の後ろなら、何もしなくても動きます。

これらの見出しを確実に渡してくれない中継の後ろで動かす場合（手作りの nginx、構内の入口、経路の一部だけを中継する独自ドメインの導入など）は、dashboard.public_url（または HERMES_DASHBOARD_PUBLIC_URL）に、管理画面に届く完全な公開 URL を設定してください。

dashboard:
  public_url: "https://dashboard.example.com/hermes"
  trusted_proxies:
    - "172.20.0.5"

設定すると、OAuth の戻り先の URL はそのまま <public_url>/auth/callback になります。この道筋では X-Forwarded-Prefix は無視されます。運用者が公開 URL をはっきり宣言しているからです。これは意図してそうしています。上に前置きを重ねると、前置きがすでに public_url に入っている大多数の場合に、二重に付いてしまうからです。

public_url に書かれたホスト名は、HTTP の Host と WebSocket の Origin の値としても 完全一致で受け入れられます。ブラウザから見えるホスト名を保ったまま、 127.0.0.1 に割り当てた管理画面へ渡す中継のためです。 ワイルドカードや後方一致は許されないので、 dashboard.example.com.evil.test のような攻撃者のホストは、DNS の付け替えを防ぐ関門に 弾かれたままです。

loopback 以外の public_url を宣言すると、バックエンドが loopback に割り当てられていても、 つねに管理画面の認証の関門が働きます。先にパスワードか OAuth のしくみを 設定してください。それがないと、Hermes は起動の時点で止まります。手元の SPA の セッションの合鍵が、中継を通して離れた場所からの認証の手段になってしまうのを防ぐためです。 このとき Uvicorn は、中継の見出しの処理も有効にします。loopback の中継は 自動で信頼されます。TLS を終端するものが別のコンテナや別の端末からつないでくる 場合は、その正確な IP アドレスを dashboard.trusted_proxies に足してください。 アドレスが決まらない場合は、中継専用のネットワークに絞った CIDR を足します。

dashboard:
  public_url: "https://dashboard.example.com/hermes"
  trusted_proxies:
    - "172.20.0.0/24"

X-Forwarded-Proto と X-Forwarded-For を渡せるのは、ここに並べた相手だけです。 Hermes は loopback への信頼をつねに保ち、*、0.0.0.0/0、::/0 は 受け付けません。ネットワークごと信頼するということは、そこにいるコンテナや端末の どれもが中継の情報を渡せるということなので、中継の正確な IP か、中継だけのための ネットワークを選ぶほうが安全です。

# Backend remains reachable only on this machine.
hermes dashboard --host 127.0.0.1 --port 9119 --no-open

TLS を終端する中継を http://127.0.0.1:9119 に向け、 dashboard.public_url には同じ外向きの出どころを書いてください。

Tailscale Serve はこの形の一例です。https://<machine>.<tailnet>.ts.net というホスト名で tailnet の中だけの HTTPS を終端しつつ、loopback の管理画面へ中継できます。 その HTTPS の出どころをそのまま dashboard.public_url に使ってください。それでも loopback 以外のブラウザ向けの出どころとして扱われるので、管理画面の認証のしくみが要ります。 インターネットから届くようにする必要は ありません。

優先の順番はほかの管理画面の設定と同じで、環境変数が config.yaml に勝ちます。

http:// / https:// の書き出しがない値、ホストのない値、引用符・不等号・空白・制御文字を含む値は受け付けられません。形の壊れた値は黙って見出しからの組み立てに落ちるので、利用者を危ない URL へ送り出す代わりに、ログインの流れがそのまま動き続けます。

> 注: public_url が上書きするのは OAuth の戻り先の URL だけです。合鍵の Secure の印は今も request.url.scheme で決まり、X-Forwarded-Proto を使うのは、つないできた相手が loopback か trusted_proxies に並んでいるときだけです。中継が loopback にないときは、HTTPS の public_url を、TLS の終端と、範囲を絞った信頼できる中継の記述とあわせて使ってください。

OAuth の流れ

このしくみは Nous Portal の OAuth の取り決め v1 を実装しています。PKCE（S256）を使う認可コードの方式です。

1. 利用者がセッションの合鍵なしで / に来る → 関門が /login へ送ります。
2. ログインのページに「Continue with Nous Research」のボタンが出ます → /auth/login?provider=nous。
3. サーバーが PKCE の状態を短命の合鍵にしまい、利用者を https://portal.nousresearch.com/oauth/authorize?… へ送ります。
4. 利用者が Portal で認証し、/auth/callback?code=…&state=… に着きます。
5. サーバーが POST /api/oauth/token でコードをアクセストークンに交換し、Portal の JWKS（/.well-known/jwks.json）に照らして JWT の署名を確かめ、hermes_session_at の合鍵を置きます。
6. 利用者は /（あるいは next= の引数で指定された、もともと行きたかった深い場所）へ送られます。

アクセストークンの有効期間は15分です。取り決め v1 に更新用の合鍵はありません。 期限が切れると、SPA の取得の包みが 401 の返りを見つけ、ページごと /login へ移動してこの流れをやり直します。

置かれる合鍵

3つとも Path=/ です。セッションの合鍵は SameSite=Lax で、PKCE の合鍵は HTTPS 越しに置かれるときだけ SameSite=None です（表を参照）。Secure の印は、管理画面に HTTPS で届いているときに付きます（要求の URL の書き出しで判断し、proxy_headers=True の下では上流の TLS の終端から来る X-Forwarded-Proto を尊重します）。

ログアウト

横の欄の小さな表示に Logged in as <user_id…> via nous とログアウトの印が出ます。それを押すと /auth/logout へ送られ、管理画面の認証の合鍵がすべて消えて /login に戻ります。

監査の記録

ログインの開始、成功、失敗、そしてセッションの確認の失敗は、すべて JSON の1行として $HERMES_HOME/logs/dashboard-auth.log に書かれます。取り扱いに注意の要る項目（access_token、refresh_token、code、code_verifier、state、Authorization の見出し）は、記録する前に伏せられます。

自作のしくみ

Nous 以外の OAuth のしくみ（Google、GitHub、独自の OIDC など）を差し込むには、DashboardAuthProvider を登録する差し込みを作ります。

# ~/.hermes/plugins/dashboard-auth-myidp/__init__.py
from hermes_cli.dashboard_auth import DashboardAuthProvider, Session, LoginStart

class MyIdPProvider(DashboardAuthProvider):
    name = "myidp"
    display_name = "My Identity Provider"

    def start_login(self, *, redirect_uri): ...
    def complete_login(self, *, code, state, code_verifier, redirect_uri): ...
    def verify_session(self, *, access_token): ...
    def refresh_session(self, *, refresh_token): ...
    def revoke_session(self, *, refresh_token): ...

def register(ctx):
    ctx.register_dashboard_auth_provider(MyIdPProvider())

ログインのページには登録されたしくみがすべて並びます。複数を重ねておいて、利用者が /login で選ぶこともできます。

対話によらない認証（持参する合鍵）

人が対話でログインする道（セッションの合鍵と更新）とは別に、DashboardAuthProvider の抽象基底クラスは、supports_token = True と verify_token(token=...) によって、対話によらないサービス間のやり方にも対応しています。しくみがこれを選ぶと、届いた Authorization: Bearer <token> が確かめられ、通ればそのしくみが機械向けと印を付けた入口に対して、要求に TokenPrincipal が付きます（request.state.token_principal）。合鍵も転送も更新もありません。

同梱の最初の使い手は drain のしくみ（plugins/dashboard_auth/drain）です。nous-account-service がエージェントごとの秘密を HERMES_DASHBOARD_DRAIN_SECRET で用意し、このしくみが届いた合鍵をそれと時間の一定な比較で確かめて、/api/gateway/drain を機械向けの入口として登録します。失敗したら閉じる作りで、弱い／短い秘密（256 ビット未満）は登録の時点で拒まれ、入口は無効のままです。環境変数が設定されていないときは何もしません。振る舞いのつまみ（scope、min_secret_chars）は config.yaml の dashboard.drain_auth の下にあります。

自作のしくみも、同じやり方で supports_token と verify_token を実装すれば、自分の機械向けの入口を公開できます。

関門が働いているか確かめる

# Quick env-var path.
HERMES_DASHBOARD_OAUTH_CLIENT_ID=agent:test \
  hermes dashboard --host 0.0.0.0

# Or the equivalent via config.yaml (recommended for local dev / on-prem):
#
#   dashboard:
#     oauth:
#       client_id: agent:test
#
# then just:
hermes dashboard --host 0.0.0.0

# Hit /api/status to see the gate state:
curl -s http://127.0.0.1:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["nous"]

管理画面の React で作られた状況のページにも、「Web server」の下に同じ項目が出ます。サインインすると、横の欄の認証の表示に今の身元が出ます。

Hermes デスクトップ版を離れたバックエンドにつなぐ

Hermes デスクトップ版は、別の端末（仮想サーバー、自宅のサーバー、Tailscale の後ろの小型機）で動く Hermes のバックエンドを動かせます。アプリの中では設定 → ゲートウェイ → リモートゲートウェイにあり、リモート URL とサインインの方法を聞かれます。（デスクトップ版そのもの — 導入、設定、チャット — については Hermes デスクトップ版のページを参照してください。）

離れた管理画面は、同梱の認証のしくみのどれかで守り、デスクトップ版はバックエンドが掲げているほうでサインインします。自分の端末の外から届くバックエンド（仮想サーバー、公開の端末、インターネットに面したもの）には、OAuth（Nous Portal）をお勧めします（hermes dashboard register で登録し、*Sign in with Nous Research* からサインインします）。同梱の利用者名とパスワードのしくみは、バックエンドが信頼できる構内網にあるか VPN 越しにしか届かないときにいちばん手早い選択肢ですが、インターネットへの直接の公開には向きません。管理画面を loopback 以外のアドレスに割り当てると認証の関門が働きます。一度サインインすれば、デスクトップ版はそのセッションをチャットの WebSocket にも自動で使い回すので、合鍵を写し取って貼り付ける必要はありません。

以下の手順では、信頼できるネットワークでいちばん早く立ち上がる利用者名とパスワードの道を使います。OAuth の道は既定のしくみ: Nous Research を参照してください。

バックエンド側（離れた端末）で

# 1. Set the dashboard login credentials in ~/.hermes/.env (secrets file, 0600).
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. Run the dashboard bound to a reachable address. The non-loopback bind
#    engages the auth gate; the username/password provider handles login.
hermes dashboard --no-open --host 0.0.0.0 --port 9119

平文を残したくないですか。代わりに HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH に scrypt のハッシュを入れてください。設定できるすべては利用者名とパスワードのしくみを参照してください。

管理画面を systemd のサービスとして動かす場合、そのユニットに EnvironmentFile=%h/.hermes/.env があれば ~/.hermes/.env は自動で拾われるので、起動の時点で認証情報が環境に入ります。

Hermes デスクトップ版で

設定 → ゲートウェイ → リモートゲートウェイ:

• リモート URL — http://<backend-host>:9119（前に中継を置くなら、/hermes のような経路の前置きも使えます）
• サインイン — アプリが利用者名とパスワードのゲートウェイだと気付いてサインインのボタンを出すので、それを押して手順1の認証情報を入れます
• 保存して接続し直す — デスクトップ版の外側を、離れたバックエンドへ切り替えます

バックエンドで HERMES_DASHBOARD_BASIC_AUTH_SECRET を設定してあれば、セッションは自動で更新され、再起動を越えて残ります。

環境変数による上書き

アプリの中の設定の代わりに、起動の前に環境変数でバックエンドを指すこともできます。HERMES_DESKTOP_REMOTE_URL を設定すると、アプリに保存された URL より優先されます（ゲートウェイの設定の区画に「env override」の札が出て、編集できなくなります）。サインインはそのまま、その区画から利用者名とパスワードで行います。

うまくいかないとき

• 「Remote gateway incomplete」 — リモート URL を入れていません。
• サインインが 401 や「Invalid credentials」で失敗する — 利用者名かパスワードが、バックエンドの HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD と合っていません。バックエンドは、知らない利用者のときも間違ったパスワードのときも同じ文言を返すので、両方を確かめてください。関門は curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' で確かめられます。true が返り、"basic" が含まれるはずです。
• 「サインイン」のボタンが出ず、代わりにセッションの合鍵を求められる — 利用者名とパスワードのしくみが働いていません（/api/status に "basic" が出ません）。利用者名とパスワード（またはそのハッシュ）が設定されていて、管理画面のプロセスがそれを読み込んでいるか確かめてください。
• 再起動のたびにサインアウトされる — HERMES_DASHBOARD_BASIC_AUTH_SECRET に変わらない値を設定してください。そうしないと、起動のたびに署名鍵が作り直されます。
• 接続を拒まれる・時間切れになる — バックエンドが届くアドレスではなく 127.0.0.1（既定）に割り当てられているか、ファイアウォールや VPN がポートを塞いでいます。0.0.0.0 か tailscale の IP に割り当てて、信頼できるネットワークにポートを開けてください。

CORS

ウェブサーバーは、CORS を localhost の出どころだけに限っています。

• http://localhost:9119 / http://127.0.0.1:9119（本番）
• http://localhost:3000 / http://127.0.0.1:3000
• http://localhost:5173 / http://127.0.0.1:5173（Vite の開発サーバー）

別のポートでサーバーを動かした場合、その出どころは自動で加えられます。

開発

管理画面の画面側に手を入れる場合は、次のようにします。

# Terminal 1: start the backend API
hermes dashboard --no-open

# Terminal 2: start the Vite dev server with HMR
cd web/
npm install
npm run dev

http://localhost:5173 の Vite の開発サーバーは、/api への要求を http://127.0.0.1:9119 の FastAPI のバックエンドへ中継します。

画面側は React 19、TypeScript、Tailwind CSS v4、そして shadcn/ui 風の部品で作られています。本番向けの組み立ての出力は hermes_cli/web_dist/ に置かれ、FastAPI のサーバーがそれを静的な SPA として配ります。

更新時の自動の組み立て

hermes update を実行すると、npm が使えるときは画面側も自動で組み立て直されます。これでコードの更新と管理画面がずれずに済みます。npm が入っていない場合、更新は画面側の組み立てを飛ばし、hermes dashboard が最初の起動時に組み立てます。

見た目と差し込み

管理画面には8つの見た目が同梱されていて、自分で作った見た目、差し込みのタブ、バックエンドの API の経路で広げられます。どれも置くだけで使え、リポジトリを写し取る必要はありません。

見た目をその場で切り替えるには、上の帯にある、言語の切り替えの隣のパレットの印を押します。選んだものは config.yaml の dashboard.theme に保存され、次にページを開いたときも復元されます。

フォントだけを変えるのも同じ選択画面からできます。見た目の一覧の下にあるフォントの節が、今使っている見た目の文字を上書きします。この選択は見た目を切り替えても残ります（config.yaml の dashboard.font）。見た目の既定を選べば、これを消してその見た目そのもののフォントに戻ります。

同梱の見た目は次のとおりです。

自分の見た目を作る、差し込みのタブを足す、外枠の差し込み口に入れ込む、差し込み固有の REST の入口を公開するといったことは、管理画面を広げるを参照してください。ひととおりの手引きとして、次を扱っています。

• 見た目の YAML の定義 — 配色、書体、配置、素材、componentStyles、colorOverrides、customCSS
• 配置の型 — standard、cockpit、tiled
• 差し込みの目録、SDK、外枠の差し込み口、ページごとの差し込み口（内蔵のページを置き換えずに部品を入れ込めます）、バックエンドの FastAPI の経路
• 見た目と差し込みを組み合わせた通しの道筋（Strike Freedom のコックピットの実演）
• 見つけ方、読み直し、うまくいかないときの手当て