このページの翻訳は LLM によって生成されています。誤りに気づいた場合は GitHub で issue を開いてお知らせください。

マシンへの接続

Preview build 2026-09-29-8e78f929d8f0, published from 8e78f929d8f0. Stable docs remain at /docs/.

ローカルの作業とリモートのエージェントを、1 つの Herdr ウィンドウにまとめられます。SSH マシンを一度保存すれば、別のクライアントを開かずに、そのワークスペースと Local を切り替えられます。エージェント一覧には接続中のマシンが含まれ、作業場所や回答待ちのエージェントを確認できます。

各マシンは独自の Herdr サーバー、セッション、プロセスを保持します。1 台への接続が切れても、ほかの接続は切れません。

Herdr は、帯域が限られた接続で画面更新の通信量を減らすため、SSH 圧縮を要求します。互換性のある古い Herdr サーバーでも動作し、キー入力などの入力の届け方は変わりません。Herdr の -C オプションは SSH 設定の Compression no を上書きします。SSH が外部の ControlMaster を通じて既存接続を再利用する場合、その接続では元の圧縮設定が維持されます。

SSH 認証の復旧

Linux と macOS で remote.manage_ssh_config=true の場合、マシン追加、サイドバー、API 操作は承認済み OpenSSH 接続を共有します。herdr machine status [<label-or-id>] [--json] は認証を求めず、現在の接続状態を確認します。reachable はリモート Herdr が利用可能という意味で、各 TUI の接続状態ではありません。ターミナルで herdr machine reconnect <label-or-id> を実行すると、SSH 認証後に保存済みマシンを検証します。インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行し、再起動は不要です。! auth、! error、失敗後の再接続ステータスをクリックすると、最新のエラーと CLI コマンドが通知に表示されます。認証ポップアップは開きません。マシン行の展開・折りたたみは変更されません。

共有接続の ControlPersist 600 はアイドル状態の 10 分を表すもので、MFA の有効期間ではありません。通信中の接続は維持されますが、企業ポリシー、SSH サーバー、ネットワークによってはそれより早く終了します。ローカル Windows の復旧はまだ対応していません。管理対象外の SSH 接続の認証は利用者の責任です。共有 ControlPath を使わずに ssh を実行するだけでは、Herdr の承認にはなりません。ホスト鍵の検証は緩和されず、未知または変更されたホスト鍵は引き続き Attention です。

接続前の確認

リモートマシンへの通常の SSH アクセスが必要です。最初に確認してください:

ssh workbox

workbox は SSH config のホスト名です。ssh://you@server:2222 のような接続先も使えます。

複数マシンへの接続は Linux、macOS、Windows のクライアントに対応し、x86_64 または aarch64 の Linux と macOS サーバー、および x86_64 の Windows サーバーに接続できます。対話型セットアップでは確認後に完全なリモートパッケージをインストールまたは更新できます。バックグラウンド再接続ではインストール済みのパッケージだけを探します。SSH 設定、認証、カスタムバイナリについては SSH 越しのリモートアタッチを参照してください。

マシンを追加する

インストールや置き換えの前に確認できるよう、対話型ターミナルで実行します:

herdr machine add workbox

対話型ターミナルでは、Herdr は実行中のセッションを検出します。1 つだけならそれを選択し、複数ある場合は Up/Down と Enter で選べます。Esc または Ctrl+C でキャンセルします。問い合わせに成功しても実行中のセッションがなければ、セットアップは default を使います。Herdr がインストールされていない場合は、default 用にインストールするか確認します。インストール済みバイナリがセッションを報告できない場合はエラーを表示します。セッションを明示的に選ぶには --remote-session <name> を指定してください。

デフォルトセッションはサイドバーに workbox と表示されます。これは user@ プレフィックスを除いた SSH ホストです。別の名前にするには --label "Build machine" を追加します。1 つのプロファイルは 1 つのリモートセッションを対象とし、そのホストの全セッションをまとめるものではありません。非対話型コマンドでは、--remote-session がない限り default を使います。

検出を省略して特定のセッションを使うには、--remote-session を追加します:

herdr machine add workbox --remote-session agents

--label がない場合、このマシンは workbox/agents と表示されます。デフォルト名がすでに使われている場合、machine add は --label の指定を求めます。

Windows サーバーでは、SSH ユーザーが所有する Herdr プロセスで使われている実行ファイルも確認します。再利用前に機能を検証するため、SSH の PATH が古いインストールを指していても、互換性のある実行中ビルドを利用できます。

Herdr はインストール済みバイナリと実行中サーバーをそれぞれ確認し、対象のバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればクライアントとサーバーのバージョンは一致しなくても構いません。未インストールや非互換の場合は、承認付きのセットアップを行います。実行中サーバーの置き換えが必要なら、サーバーとペインのプロセスを停止する前に確認し、その後に互換サーバーを起動します。デフォルトの回答は No です。インストールと置き換えの両方が必要な場合は、1 回の確認で承認します。machine add は実験的なライブハンドオフを使いません。セットアップをキャンセルした場合や失敗した場合、プロファイルは保存されません。

herdr で UI を開きます。ローカルクライアントがすでに開いていれば、追加や有効化したマシンは通常 1 秒以内に表示され、選択を変えずにバックグラウンドで接続します。マシン切り替え中の変更は、切り替えの完了後に反映します。セットアップ終了後もリモートサーバーは動き続けます。

マシンを切り替える

サイドバーでマシンまたはそのワークスペースを選びます。選択中のマシンだけがペイン入力とターミナルサイズを受け取り、表示するターミナル内容とグラフィックスを送信します。ほかの接続済みマシンは、ペイン画面を送らずにワークスペース情報、エージェント状態、通知を更新し続けます。

各マシンの横の矢印をクリックすると、現在のワークスペースを切り替えずに一覧を折りたためます。再接続中のマシンでも操作できます。

キーボードでは prefix+w を押し、ワークスペース移動キー（デフォルトは Up/Down）で接続済みマシンのワークスペースをサイドバー順に選びます。Enter で移動を確定し、Esc またはプレフィックスキーで切り替えずにキャンセルします。縮小・展開サイドバーとも、折りたたまれたマシン内の選択行を表示します。デスクトップでは両端で折り返し、モバイルの切り替え画面では先頭と末尾で止まります。切断中のマシンは飛ばします。

別マシンのワークスペースをハイライトしたら、他のキー操作の前に Enter で切り替えてください。現在のマシンでペイン、タブ、ワークスペース、カスタムコマンドの操作が誤って実行されるのを防ぎます。クリックすると、デスクトップでのリモート移動のプレビューはキャンセルされます。展開サイドバーはマシンごとの worktree グループの折りたたみ状態を反映します。

起動時は SSH 接続を待たずに Local を開きます。Local を選ぶと、リモートの応答を待たずに未完了の切り替えをキャンセルします。Local 自体が再接続中なら、準備ができた時点で選択を再開します。Local の新しい画面とターミナル設定が届くと入力できます。応答しないマシンがほかのマシンの入力を妨げることはありません。同じサーバーに接続した複数のクライアントは、それぞれ別のタブを表示できます。同じタブを表示した場合のサイズについてはクライアントとサーバーを参照してください。

接続が切れると、最後のワークスペースとエージェント状態を暗く表示します。これはキャッシュであり、現在の状態ではありません。新しい接続と対応する画面が届くまで、そのペインへの入力や移動は無効です。再接続しても、使用中のマシンから選択を奪いません。

名前の変更、無効化、削除

ラベルやホスト名から推測せず、一覧からプロファイル ID を取得します:

herdr machine list
herdr machine rename <profile-id> --label "New name"
herdr machine disable <profile-id>
herdr machine enable <profile-id>
herdr machine remove <profile-id>

スクリプトでは machine list に --json を追加できます。

名前の変更は表示ラベルだけを更新し、再接続しません。無効化はプロファイルを残し、削除はプロファイルを忘れます。どちらもクライアントからそのマシンだけを切断し、到達不能なホストでも操作できます。リモートセッションとエージェントは動き続けます。

表示中のマシンを削除または無効化すると Local に戻ります。Local が利用できない場合は、別のリモートを選ばず、その状態を表示して再接続します。有効な保存済みマシンがあれば、Local が失敗または再起動してもクライアントを使い続けられます。

接続の問題

Reconnecting: ネットワーク中断、スリープ、SSH 障害の後は自動で再試行します。失敗が続くと待機間隔は最大 2 分まで延び、短時間だけ接続に成功してもリセットされません。1 分間安定して接続できると、次の中断では再び短い間隔で再試行します。SSH 接続はアプリケーションの通信を監視し、通信がない間はヘルスチェックを行うため、切れた接続が Online のままになりません。Local はリモート用のプローブではなく、ネイティブ接続の終了や失敗を検知します。
Attention: 認証、ホスト鍵の承認、互換サーバーの準備などが必要です。ほかのマシンは利用できます。! auth は認証失敗、! error は別の問題を示します。バッジをクリックするとエラーと CLI コマンドを表示します。折りたたみ時はどちらも ! です。
保存済みマシンのファイルエラー: カタログを読み取れない、または内容が不正な場合、現在の接続は変更しません。通知を表示して自動で読み取りを再試行します。

両端のインストールがブリッジのアイドル終了に対応している場合、Linux と macOS への保存済みマシン接続は、どちらの方向にも通信がない状態が 1 分続くとリモートブリッジを終了します。スリープ時間も含み、復帰時に期限を確認します。正常なアイドル接続ではヘルスチェックを交換するため、継続的な出力を見るためにキーを入力する必要はありません。ブリッジ終了後もリモートサーバー、セッション、ペインのプロセスは動き続けます。古いインストールとは、この追加機能なしで接続できます。

バックグラウンド接続がプロンプトに回答したり、サーバーのインストール、更新、再起動、ハンドオフを行ったりすることはありません。認証以外の Attention の場合は、Herdr が表示する単独接続用のコマンドを対話型ターミナルで実行してください。例:

herdr --remote workbox

プロファイルの接続先を使います。名前付きセッションを選んだ場合だけ --session <name> も指定します。セットアップ後、開いているクライアントは自動的に再試行します。machine reconnect は Herdr をインストール・更新しません。バージョンが違うという理由だけで実行中サーバーを止めないでください。

認証に失敗したら、まず通常の SSH を確認します。パスフレーズ付きの鍵は、非対話型のバックグラウンド接続を始める前に ssh-add で読み込んでください。

リモートペイン内で Git 認証や SSH 署名を使うには、信頼できるホストについて SSH 設定で ForwardAgent yes を有効にしてください。Herdr が転送を有効にすることはありません。セッションがエージェント付きで起動した場合、更新済みの Linux と macOS サーバーはペインに安定したエージェントアドレスを与えるため、--remote または保存済みマシンが再接続した後も、既存ペインと新規ペインの両方で転送されたエージェントを利用できます。動作中の継承エージェントや先行接続は、後から接続したクライアントや一時的なセットアップ確認より優先されます。それが消えた場合は、別の稼働中アタッチがエージェントを提供できます。

これにはローカルクライアントだけでなく、更新済みのリモートサーバーが必要です。エージェントなしで開始したローカルセッションでは SSH_AUTH_SOCK を変更しません。サーバー更新前、またはセッションに初めてエージェントが提供される前に作成されたペインは元の環境を維持するため、安定したアドレスを継承するには一度作り直す必要があります。互換性のある古いサーバーやエージェント転送なしの接続も、通常どおりアタッチできます。

設定と自動化

UI はデフォルトでクライアントのローカルテーマ、サイドバー設定、キーバインドを使います。選択中サーバーが公開するカスタムコマンドとプラグインは、そのサーバーで実行します。Herdr はローカルのプラグイン、設定、実行ファイル、シークレットを SSH ホストにコピーしません。リモートにコマンドがなければエラーを表示します。クライアント設定を編集したら UI の reload config を使います。設定を参照してください。

複数のマシンがある場合、デフォルトの Agent 行に machine トークンを表示します。既存のカスタム行は維持されるため、ラベルが必要なら machine を追加してください。サイドバーの行レイアウトではマシンラベルの条件付き色も設定できます。

ワークスペース、タブ、ペインの ID とエージェント名はサーバーごとに独立しています。2 台に同じ w1:p1 や reviewer が存在する場合があります。UI でマシンを選んでも、既存ペイン内の CLI は継承したセッションとソケットを使い続けます。リモート自動化では herdr --machine <label-or-id> agent list で ID を取得し、操作時にも同じプレフィックスを指定します。CLI は保存済みプロファイルの SSH 接続先とセッションを直接使うため、TUI を開く必要はありません。--machine を省略した場合の動作は変わりません。対応コマンド、更新要件、パスの扱いは CLI リファレンスを参照してください。

更新と保存データ

保存するのは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態だけです。パスワード、秘密鍵、エージェントのチケット、SSH 制御ソケットはカタログに保存しません。認証は OpenSSH が扱います。

Herdr は、--machine コマンドを繰り返し実行するときに検出を省略できるよう、各マシンのリモート OS と解決済み実行ファイルパスを別途記憶します。既存のプロファイルでは、初回使用時に不足情報を学習します。このキャッシュは任意です。キャッシュファイルがない、不正、または書き込み不能でもコマンドの動作は妨げられません。コマンドは引き続き実行中サーバーの互換性を確認します。キャッシュした実行ファイルがない、または API 転送に対応しなくなった場合、最初の読み取り専用確認中に再検出します。リモートの状態をすでに変更した可能性があるコマンドを自動的に再実行することはありません。

クライアントとサーバーは同一バージョンを要求せず、互換性を合意します。保存済みマシンへの接続には、サーバーの surface_interest と health_check 能力も必要です。未対応の古いサーバーは、単独接続できても明示的に更新するまで Attention になります。そのほかの未対応メソッドは、該当する操作だけを無効にします。

互換クライアントを更新しても、リモートサーバーを置き換えたりエージェントを停止したりしません。新しいサーバー機能が必要なら、そのサーバーを明示的に更新します。通常の置き換えでは、サーバーとペインのプロセスを停止する前に確認します。

ライブハンドオフは実験的なオプトイン機能です。単独接続のセットアップで対応サーバーを置き換える場合、herdr --remote に --handoff を明示的に追加できます。通常の接続や認証の修復には不要です。更新とセッション状態と復元で、それぞれの操作が何を維持するか確認してください。