永続化とリモートアクセス

Preview build 2026-09-08-62431dbd033b, published from 62431dbd033b. Stable docs remain at /docs/.

Herdr はペインをバックグラウンドサーバーで動かし続けます。ターミナルクライアントはデタッチして、あとで再接続できます。

ローカル、SSH、herdr --remote の各ワークフローについては Herdr での作業の進め方を参照してください。

デタッチと再アタッチ

ctrl+b q でクライアントをデタッチします。ペインとエージェントは動き続けます。再度 herdr を実行すると再アタッチします。セッションとそのペインを停止するには herdr server stop を使います。

サーバーの完全停止後に Herdr が再起動すると、保存されたセッションの形を復元します。デタッチ、サーバー再起動、画面履歴リプレイ、エージェントネイティブのセッション復元、ライブハンドオフでそれぞれ何が生き残るかはセッション状態と復元を参照してください。

名前付きセッション

独立した Herdr サーバーが欲しいときは名前付きセッションを使います。

herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
herdr session delete side-project

名前付きセッションは独自のペイン、タブ、ワークスペース、ソケット、ランタイム状態を持ちます。グローバル設定ファイルは共有されます。

スクリプトでは --json を使ってください:

herdr session list --json
herdr session stop work --json
herdr session delete side-project --json

保存済み SSH マシン

Local と複数の SSH マシンを 1 つのウィンドウで使うには、マシンへの接続を参照してください。セットアップ、切り替え、再接続、設定、リモート自動化を説明しています。保存済みマシンを削除してもクライアントが切断されるだけで、リモートセッションは停止しません。

SSH 越しのリモートアタッチ

Herdr での作業の進め方でリモート接続の方法を比較しています。サーバーに SSH してそこで herdr を実行する tmux スタイルの方法、保存済み SSH マシンで複数の接続先をまとめる方法、ローカルマシンから単独のセッションに接続する方法があります:

herdr --remote workbox
herdr --remote ssh://you@server:2222

このモードでは、リモートサーバーがペインを動かし、ターミナル内容とセッション状態を SSH 越しに送信します。ローカルの Herdr がサイドバー、メニュー、テーマを含む UI を描画します。クライアントがローカルで動くため、Herdr は画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートセッションにブリッジできます。画像をリモートの一時ファイルにコピーし、そのパスを貼り付けます。

デフォルトでは、herdr --remote はそのアタッチにローカルの Herdr キーバインドを使います。リモートサーバーの設定が異なっていても、ローカルの操作感覚を維持できます。ローカルキーバインドを編集したら、UI の reload config でデタッチせずに反映できます。リモートサーバーの設定を使いたい場合は --remote-keybindings server を使います。ローカルのカスタムコマンドキーバインドは送信されません。それらのコマンドはリモートホスト上で実行されてしまうからです。

繰り返し接続する相手は SSH config を使ってください:

Host workbox
  HostName server.example.com
  User you
  Port 2222

その後はこれでアタッチできます:

herdr --remote workbox

リモートアタッチは、Linux、macOS、Windows のローカルクライアントから、x86_64 と aarch64 の Linux および macOS ホストへの接続をサポートします。Herdr はリモートのプラットフォームを確認し、リモートの PATH 上にある互換性のある herdr を優先してから、一般的な直接インストール、Homebrew、mise、Nix プロファイルのパスを確認します。両方が安定したエンドポイント世代に対応していれば、ローカルとリモートのバージョンは一致しなくても接続できます。互換性のあるバイナリがない場合、対話的な実行では ~/.local/bin/herdr へのインストールを提案します。非対話的な実行はホストを変更せずに失敗します。~/.local/bin がリモートの PATH にない場合、Herdr はインストール後に警告します。Windows をリモートホストとして使うことはできません。

デフォルトでは、herdr --remote はユーザーの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してリモートセットアップとブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Linux と macOS クライアントは接続再利用用のプライベートなアタッチ単位コントロールソケットも使いますが、Windows OpenSSH では使いません。Herdr が生成する設定やコントロールソケットを使わず通常の ssh を使うには [remote].manage_ssh_config = false を設定してください。

リモート接続は通常の OpenSSH 認証を使います。非対話型シェル、スクリプト、CI、モバイルターミナルなどで鍵のパスフレーズを入力できない場合は、先に ssh-agent へ鍵を追加してください:

ssh-add
herdr --remote workbox

認証に失敗したら、まず ssh workbox で通常の SSH 接続を確認してください。

バージョンが違うだけでは、実行中のリモートサーバーを置き換えたり再起動したりしません。必要な互換性や独立したバックグラウンド起動に未対応のサーバーは、停止前に確認します。保存済みマシンには画面配信とヘルスチェックの能力も必要です。マシンへの接続を参照してください。デフォルトの回答は No で、停止するとペインのプロセスも終了します。この一度限りの更新で、対応サーバーのプロセスを実験的なライブハンドオフで維持したい場合は --handoff を渡します:

herdr --remote workbox --handoff

先にサーバーへ SSH してそこで herdr を実行した場合、Herdr は完全にサーバー上で動きます。このモードは便利でシンプルですが、通常のターミナルテキスト貼り付けを超えてローカルデスクトップのクリップボードにはアクセスできません。

ローカルとリモートのプラットフォームが一致する場合、直接インストールでは Herdr は現在のローカルバイナリをコピーできます。Homebrew、mise、Nix のインストールの場合、またはプラットフォームが異なる場合は、https://herdr.dev/latest.json から現在のクライアントバージョンに一致するリリースアセットをダウンロードします。

ローカルビルドやカスタムバイナリの場合は、リモートアタッチの前に HERDR_REMOTE_BINARY にローカルファイルパスを設定してください。

HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox

リモートの名前付きセッション

リモートホスト上の名前付きセッションにアタッチするには、--remote と一緒に --session を使います:

herdr --remote workbox --session agents

ダイレクトターミナルアタッチ

完全な Herdr アタッチはワークスペース UI 全体を開きます。ダイレクトアタッチは、サーバーが所有するターミナルをひとつだけ、現在のターミナルに開きます。

ダイレクトターミナルアタッチは Linux と macOS で利用でき、ネイティブ Windows では利用できません。

エージェントターゲットでアタッチ:

herdr agent attach reviewer

ターミナル ID でアタッチ:

herdr terminal attach term_abc123

ダイレクトアタッチは、現在レンダリングされているターミナル状態をストリーミングし、その後ライブの ANSI フレームを流します。入力はそのターミナルに直接送られます。

ctrl+b q でデタッチします。リテラルの ctrl+b は ctrl+b ctrl+b で送ります。

ひとつのターミナルの入力とリサイズを所有できる書き込み可能なダイレクトアタッチクライアントはひとつだけです。既存の所有者を置き換えるには --takeover を使います:

herdr terminal attach term_abc123 --takeover

描画済みターミナルデータだけが必要な外部ブリッジには、読み取り専用のオブザーバーを使えます:

herdr terminal session observe w1:p1 --cols 120 --rows 40

base64 の ANSI データを含む terminal.frame を改行区切り JSON で出力し、サーバーがストリームを閉じると terminal.closed を出力します。複数のオブザーバーが同じターミナルを監視でき、入力、リサイズ、スクロール、所有権を取得することはありません。

対話型ブリッジには書き込み可能なコントローラーを使います:

herdr terminal session control w1:p1 --takeover --cols 120 --rows 40

同じフレームを出力し、標準入力から改行区切り JSON コマンドを読み取ります。terminal.input はテキストまたは base64 データ、terminal.resize は表示サイズ、terminal.scroll はビューポートのスクロール、terminal.release はコントローラーの終了を扱います。入力とリサイズを所有できるコントローラーは 1 つだけです。