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

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

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

デタッチと再アタッチ

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

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

名前付きセッション

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

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

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

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

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

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

リモートモードは 2 つあり、PK-Herdr での作業の進め方で比較しています。tmux スタイルの方法では、サーバーに SSH してそこで pk-herdr を実行します。もうひとつは、ローカルマシンから SSH 越しにアタッチする方法です:

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

このモードでは、ローカルの PK-Herdr はシンクライアントです。SSH 越しに接続し、リモートの PK-Herdr サーバーを起動またはアタッチして、UI をローカルターミナルにストリーミングします。クライアントがローカルで動くため、PK-Herdr は画像クリップボードの貼り付けのようなローカルデスクトップ機能をリモートセッションにブリッジできます。画像をリモートの一時ファイルにコピーし、そのパスを貼り付けます。

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

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

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

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

pk-herdr --remote workbox

リモートアタッチは x86_64 と aarch64 の Linux および macOS ホストをサポートします。PK-Herdr はリモートのプラットフォームを確認し、リモートの PATH 上にある一致する pk-herdr を優先し、次に ~/.local/bin/pk-herdr を確認します。一致するバイナリがない場合、対話的な実行では ~/.local/bin/pk-herdr へのインストールを提案します。非対話的な実行はホストを変更せずに失敗します。~/.local/bin がリモートの PATH にない場合、PK-Herdr はインストール後に警告します。

ネイティブ Windows の pk-herdr --remote は Windows ベータの範囲外です。Windows からはサーバーに SSH してそこで pk-herdr を実行してください。

デフォルトでは、pk-herdr --remote はあなたの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。PK-Herdr が生成するブリッジ設定を使わず素の ssh を使うには [remote].manage_ssh_config = false を設定してください。

デフォルトでは、実行中のリモートサーバーの置き換えや再起動が必要な場合、リモートアタッチは通常の再起動/停止フローを使います。対応する実行中リモートサーバーで実験的なライブハンドオフにオプトインするには --handoff を渡します:

pk-herdr --remote workbox --handoff

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

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

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

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

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

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

pk-herdr --remote workbox --session agents

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

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

ダイレクトターミナルアタッチは Windows ベータでは Unix 専用です。

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

pk-herdr agent attach reviewer

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

pk-herdr terminal attach term_abc123

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

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

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

pk-herdr terminal attach term_abc123 --takeover

シングルプロセスの逃げ道

バックグラウンドのサーバー/クライアント分離なしで PK-Herdr を実行するには --no-session を使います:

pk-herdr --no-session

これは主にデバッグや互換性のための逃げ道です。デフォルトの永続セッションモードが通常の使い方です。