SSH でリモートノードを操作する

Remote Nodes を使うと、デスクトップ環境のないマシン上の OcHub 状態を 1 台の OcHub Desktop から操作できます。リモート側に必要なのは OpenSSH だけです。 ochcli が未インストールなら、確認後に Desktop から SSH 経由で導入できます。 AI コーディングツール、設定、認証情報はリモート環境に残ります。

特に WSL、Linux 開発マシン、リモートワークステーションで便利です。API エンドポイントを変えるたびに SSH ログインして設定ファイルを探す代わりに、OcHub で 対象マシンを選び、リモート側にすでに存在する接続へ切り替えられます。

リモートノードを使う理由

実行環境と認証情報の境界を保ちながら、1 つの画面から操作できます。

• 開発マシン上の Claude Code、Codex、OpenCode などを手作業で編集せず切り替える。
• 接続前にオンライン状態、ochcli バージョン、プラットフォームを確認する。
• 適用前に、どのリモート設定が変更されるかをプレビューする。
• リモート OcHub Gateway の起動・停止と診断を行う。
• 既存の OpenSSH エイリアス、SSH Agent、ProxyJump、Keychain、ハードウェアキーを使う。

OcHub を閉じてもツールがローカルへ移動することはありません。切り替えは選択した リモートノード上のネイティブ設定を書き換えるため、ツールはその後もリモートで動作します。

現在リモート管理できるもの

現在の Remote Nodes は次をサポートします。

workspace selector は既存の product page 全体に作用します。database、tool config、 session、path、network request は選択中 node のものです。一方、desktop language、 tray/login、theme、「Finder で開く」などは意図的に操作側 computer に残ります。

OcHub は任意の Shell 実行や自動 Gateway tunnel を提供しません。古い node とは広告済み capability の範囲で接続できますが、完全な workspace には新しい remote ochcli が必要です。 CLI がない場合や古い場合は理由を明示し、接続行から managed version を install / upgrade できます。

必要条件

次を準備してください。

• 操作側コンピューターに OcHub Desktop 0.4.22 以降。
• 操作側で system ssh と ssh-keyscan が利用可能。
• リモート側で到達可能な OpenSSH Server が稼働。
• リモート user の home directory が書き込み可能であること。Desktop から managed ochcli を install するか、既存の manual installation を利用できます。
• 対話的なパスワード入力なしで成功する SSH key または Agent 認証。OcHub は BatchMode=yes を使用します。
• 接続を切り替える場合、リモート OcHub DB に少なくとも 1 つ Provider が存在。

操作側から、OcHub と同じ経路を先にテストします。

ssh -V
ssh -o BatchMode=yes devbox ochcli remote probe

devbox は SSH エイリアスに置き換えます。2 番目のコマンドはパスワードや passphrase を要求せず、node、runtime、version、policy、capability を返す必要があります。

リモートへ ochcli をインストールする

通常は事前に SSH login して install する必要はありません。後述の手順で SSH node を 追加し、「OcHub CLI がインストールされていません」と表示されたら Install を選びます。 OcHub は OS と CPU を検出し、Desktop 側で公式 executable を download・署名検証して、 host key 確認済み SSH 経由で upload します。sudo は使わず、current SSH user の directory だけに書き込み、新しい port も開きません。完了後は Owner を起動し、実際の remote protocol で version を確認して stable absolute path を保存します。

古い CLI、実行権限のない CLI、architecture が違う CLI では同じ action が Upgrade として 表示されます。Desktop が release を取得できない場合や platform が未対応の場合だけ、以下の manual fallback を使ってください。

最新リリースからリモート環境用の headless CLI archive をダウンロードします。実行ファイルは ochcli ひとつです。 Linux または WSL では managed node としてインストールします。

tar -xzf OcHub_*_linux_x86_64_cli.tar.gz
chmod +x ochcli
./ochcli node install

ochcli version
ochcli node status
ochcli remote probe

installer は user-owned directory に version を保持し、stable な current entry を atomic に切り替え、~/.local/bin/ochcli を公開します。利用可能なら launchd または systemd user service を登録します。systemd のない WSL では background owner を使い、 WSL restart 後は次の SSH session が再起動します。

非対話 SSH の PATH に ~/.local/bin を含めてください。node 追加時に managed ochcli の絶対 path を指定する方法も「ochcli not found」の確実な対処です。

ツールに既存の実設定がある場合は、接続前にリモート OcHub DB へインポートします。

ochcli app list
ochcli provider import-live --app codex
ochcli provider list --app codex

codex は対象 App ID に変更します。追加の接続を作成する場合は ochcli provider add --help を使います。Secret はデスクトップ経由ではなく リモートマシン上で入力してください。

2 つ目の daemon binary は不要です。同じ managed ochcli が persistent Owner を 実行し、通常の最初の Remote Nodes session が必要に応じて起動します。

SSH 接続を準備する

操作側コンピューターの SSH config に具体的な alias を追加します。

Host devbox
    HostName 192.0.2.40
    User alice
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30

OcHub は ~/.ssh/config とその Include を読みます。Windows では WSL 内の /home/<user>/.ssh/config ではなく、%USERPROFILE%\.ssh\config です。具体的な Host alias は追加ダイアログに表示されます。wildcard だけの block は既定値として 使われますが、独立したマシンとしては表示されません。

ProxyJump、SSH Agent、system keychain、ControlMaster、hardware key は system OpenSSH が処理します。OcHub を開く前に次が成功することを確認してください。

ssh -o BatchMode=yes devbox ochcli remote probe

ノードを追加して接続する

1. OcHub sidebar で Remote nodes を開きます。
2. Add を選びます。操作側の SSH config から具体的な alias が一覧になります。
3. alias を選んで Add、または左下の Add manually を選びます。
4. 手動追加では表示名、SSH target、key scan 用の実 hostname/IP、port、リモート ochcli path を入力します。
5. OcHub が ssh-keyscan を実行し、key type と SHA256 fingerprint を表示します。 cloud console や管理者など信頼できる経路と照合します。
6. 一致した場合だけ Trust and connect を選びます。

承認した key は private permission の ~/.ochub/ssh/known_hosts に保存されます。通常の ~/.ssh/known_hosts も引き続き利用されます。OcHub が StrictHostKeyChecking=no を暗黙に使うことはありません。

接続一覧には online 状態、ochcli version、platform、最終接続時刻が表示されます。 sidebar 上部の workspace selector で This Mac と保存済み remote node を切り替えます。

失敗は CLI 未インストール、node/Desktop の upgrade 必須、SSH authentication、host key 変更、timeout、system library 非互換などの分類で表示されます。Details には対処方法、 SSH exit code、raw diagnostics が表示され、長い生エラーは接続行に出ません。自動復旧できる CLI 問題には Install または Upgrade も表示されます。

選択中 node が offline、SSH handshake timeout、または capability negotiation 失敗に なった場合、各 page はその node の cache を直ちに消去し、remote write を無効にします。 OcHub が This Mac で同じ操作を自動実行することはありません。Provider、gateway、 settings、sync、tools、update を続ける前に node を再接続してください。

workspace 切り替え後、page 内の path は選択中 node の pathです。Tools の /srv/backup/OcHub.sql、Settings の data directory、sync/backup file は remote で 解決され、操作側の HOME は使いません。file picker、web/Finder を開く操作、 desktop preference は local のままです。

リモートノードを 1 click で更新する

node が managed update capability を広告すると、接続行に ochcli version と update action が表示されます。OcHub は node version と target platform を取得し、署名済み headless.json release manifest を確認します。dialog では次を選べます。

• Automatic：node が対象 release asset へ到達できれば direct download、できなければ desktop relay。
• Download on node：remote node 自身が署名済み executable を download。
• Relay through this computer：Desktop が対象 binary を download・verify し、SSH 経由で node へ stream。

relay でも desktop だけを信用しません。node が expected Node ID、target、byte count、 SHA-256、release signature を再検証します。どちらも stable current entry を atomic に切り替え、Owner を restart して version を health check します。失敗時は previous version を自動復元します。node 上で手動 rollback もできます。

ochcli --yes node rollback

update install は policy で既定有効です。無効にする場合は allowUpdateInstall = false を設定して再接続してください。managed updater より前の node は接続行の Upgrade で最初の managed install を実行できます。以後は direct/relay update dialog を使います。managed install と self-update は現在 macOS と Linux（WSL を含む）をサポートします。

リモートの Provider を切り替える

1. workspace selector または Remote Nodes 一覧から対象 node を選びます。
2. 接続後、変更するリモート App を選びます。
3. 既存 Provider の Preview switch を選びます。
4. target node、SSH alias、current provider、target provider、config path、revision を確認します。
5. Apply change を選びます。
6. refresh するか、リモートのツールから短い request を送り、新しい接続を確認します。

適用直前に revision がもう一度確認されます。preview 後にツールや別 process が設定を 変更した場合、最新状態を上書きせず apply が拒否されます。node を refresh し、 現在値を確認してから新しい preview を作成してください。

mutation には idempotency key と remote operation journal もあります。apply 中に SSH が切断された場合は、再接続後に Recent operations を確認してから再試行します。 同じ write を盲目的に二重実行せず、保存済み結果を返せます。

Gateway と診断を操作する

接続した node page には remote Gateway 状態が表示されます。起動するとリモート Owner 上で動作し、停止はその node だけに影響します。WSL や開発マシン上の AI tool が同じ machine の loopback Gateway を使う構成に適しています。

SSH control session は Gateway を操作側へ自動公開しません。操作側からアクセスする 必要がある場合は、remote port を確認して別の明示的な tunnel を作成します。

ssh -N -L 8765:127.0.0.1:<remote-port> devbox

Run diagnostics は remote ochcli doctor と SSH session diagnostics をまとめます。 Recent operations は actor、time、operation ID、outcome を表示しますが、Provider Secret をデスクトップへコピーしません。

WSL の設定例

Windows 上の OcHub Desktop から WSL distribution を操作する場合：

1. WSL 内で OpenSSH Server をインストールして起動します。

   sudo apt update
   sudo apt install openssh-server
   sudo service ssh start

   systemd が有効なら最後の代わりに sudo systemctl enable --now ssh を使えます。

2. 前述の手順で WSL 内へ単一の ochcli を ochcli node install でインストールします。

3. Windows から WSL Linux user への key 認証を設定します。

4. alias を Windows の %USERPROFILE%\.ssh\config に追加します。

   Host wsl-dev
       HostName 127.0.0.1
       User <your-wsl-user>
       Port 22
       IdentityFile ~/.ssh/id_ed25519

5. PowerShell でテストします。

   ssh -o BatchMode=yes wsl-dev ochcli remote probe

6. OcHub の Remote Nodes dialog から wsl-dev を追加します。

Windows 側が port 22 を使用中なら WSL sshd を別 port にし、alias も合わせます。 WSL distribution または sshd が停止中なら node は offline になります。OcHub は Windows OpenSSH を使い、wsl.exe を自動起動しません。

Claude Code や Codex は Linux path、credential、session、process を含めて WSL 内に 置いたまま、Provider の切り替えだけを desktop の 2 click で行えるようになります。

セキュリティとリモートポリシー

Remote Nodes は HTTP/TCP の管理 listener を追加しません。SSH が transport encryption、 host authentication、user authentication を提供し、OcHub は SSH process の stdin/stdout 上で allowlist 済みの ochcli remote serve --stdio protocol を動かします。request は typed operation であり、shell command string ではありません。

既定 policy は status、diagnostics、Provider switching（新しい secret を含む）、 Gateway lifecycle、update install を許可します。backup restore は無効です。 remote node で確認します。

ochcli remote policy show
ochcli remote policy validate

任意の policy file は ~/.ochub/remote.toml です。read-only node の例：

schemaVersion = 1
enabled = true
allowWrite = false
allowGatewayLifecycle = false
allowBackupRestore = false
allowUpdateInstall = false

enabled = false で Remote Nodes session を拒否できます。通常の SSH account は Unix user と同じ権限を持ちます。policy が強い認可境界になるのは SSH key を OcHub forced command に制限した場合だけです。構成例と protocol の詳細は Remote Nodes design and security model を参照してください。

desktop から database restore または SQL/cc-switch import を行う場合は、 remote policy で backup restore を明示的に有効にします。update install は既定有効ですが、 設定に明示することもできます。

allowBackupRestore = true
allowUpdateInstall = true

desktop editor は暗号化 SSH session 経由で live secret を読み、local workspace と同じ 編集体験になります。変更していない mask placeholder は remote の元値を保持し、 ****** を書き戻しません。policy の変更は次の SSH control session から有効です。

トラブルシューティングと現在の制限

OcHub から node を削除しても、消えるのは操作側の接続記録だけです。リモートの Provider、tool config、~/.ochub、daemon、Gateway data は削除されません。