リモート開発と管理

このガイドでは2つの内容を扱います。1つはローカルのVelaTermを他のデバイスに開放する方法、もう1つは遠隔マシンに接続してそこでセッションを開発・管理する方法です。

1. 2つのエントリポイント、2つの方向

遠隔機能はすべてタイトルバーの右側（テーマ切り替えの隣）にあります：

地球アイコンはRemote Access (Browser)です。この機能を使うと、スマートフォンやタブレット、別のコンピュータがブラウザからあなたのVelaTermを利用できるようになります。矢印アイコンはConnect to Remote Serverで、このマシンがクライアントとして動作し、別のマシンで開発を行うために接続します。サーバーが起動しているときは地球アイコンが緑色に点灯します。

2. このマシンを開放する（Remote Access）

2.1 サーバーを起動する

地球アイコンをクリックし、ポート（デフォルトは8799。使用中の場合は変更してください）とアクセスパスワードを設定したら、「Start Server」をクリックします：

どのデバイスもアクセスするにはアクセスパスワードが必要です。このパスワードはサーバーが起動している間のみ有効で、停止したら次回新しいものを設定してください。

2.2 デバイスを接続する

起動すると、パネルにステータス、証明書のフィンガープリント、自動生成されたペアリングリンクが表示されます：

接続するには、pairing linkを自分のデバイスに送信します（AirDropや自分宛てのメッセージなど、使える方法を使ってください）。ブラウザでそのリンクを開き、アクセスパスワードを入力します。このリンクには暗号化されたペアリング情報が含まれており、ブラウザとマシン間の通信はエンドツーエンドで暗号化されます。知っておくべき2つの点があります：

• このリンクは鍵のようなものです。自分のデバイス同士でのみ共有してください。リンクが漏洩した疑いがある場合は「Regenerate link」をクリックしてください。古いリンクは即座に無効になり、新しいリンクを使用するまで接続されているすべてのデバイスが切断されます。
• 初回接続時には、ブラウザが信頼できない証明書について警告を表示します。これは自己署名証明書の場合によくあることです。ブラウザが表示するフィンガープリントとパネル内の「Certificate fingerprint」とを比較してください。一致していれば、自分のマシンと通信していることになります。

複数のネットワークインターフェース（有線、Wi-Fi、VPN）がある場合、パネルには優先されるアドレスが表示され、残りのアドレスは「1 more url」としてまとめられます。接続するデバイスと同じネットワーク上のアドレスを選択してください。

スマートフォンで同じリンクを開くと、自動的にモバイルレイアウト（2段階のナビゲーションとターミナルキーバー）に切り替わります。特別な設定は不要です。

2.3 ブラウザ側の体験

接続されたデバイスが見るログインページとメインUIは次のとおりです：

ブラウザクライアントはデスクトップ版と同じライブセッションを共有します。ツリー構造やターミナル出力が同じで、両方の側で入力が可能であり、リアルタイムで相手の操作が確認できます。ウィンドウの配置（開いているタブや分割）は各クライアントごとに独立しています。

ターミナルのサイズには「所有者」という概念があります。1つのセッションが複数のクライアントで開かれている場合、サイズは所有者に従い、他のクライアントでは縮小されたミラー表示が行われ、「Mirror … click to fit this window」というバーが表示されます（上のスクリーンショットのターミナル右上）。このバーをクリックすると、現在のウィンドウのサイズを自分で調整できます。

2.4 デバイス管理

パネルの「Paired devices」リストには、接続されているすべてのデバイスが表示されます：

デバイスをブロックするには、その横にある「Block」をクリックして確認します。するとそのデバイスは即座に切断され、再接続することはできません（新しいペアリングリンクが必要になります）。他のデバイスには影響しません。デバイス名はクライアント側から自動的に報告されるため、それを識別子としてではなく単なるラベルとして扱ってください。一度にすべてのデバイスを切断したい場合は「Regenerate link」を使用してください。

2.5 サーバーを停止する

パネルの下部にある「Stop Server」をクリックします。ブラウザクライアントは切断されますが、既に実行中のセッションには影響しません。これらのセッションはデスクトップアプリ自体に属しているからです。

3. 外部に接続する（Connect to Remote Server）

タイトルバーにある接続ボタンをクリックすると、パネルにSSHモードとURLモードが表示されます。

3.1 SSHモード：遠隔環境に必要なのはSSHだけ

VelaTermコンポーネントがインストールされていない遠隔開発用マシン（通常はLinuxまたはmacOS）の場合です。接続すると、自動的に一連の処理が実行されます。遠隔マシンのOSとアーキテクチャを検出し、適合するvela-serverを転送して永続的なプロセスとして起動し、ローカルのポートフォワーディングを設定し、遠隔ウィンドウを開いて自動的にログインします。

user@host[:port]を入力して「Connect」をクリックします。知っておくべき詳細は次のとおりです：

**初回接続時のホストキー検証.**新しいホストは、検証用にSSHホストキーフィンガープリントを表示します。「Fingerprint matches, connect」と確認すると、そのホストはknown_hostsに記録され、以降そのホストに対しては再び確認画面が表示されません。既知のホストのフィンガープリントが変更された場合、パネルが赤色に変わります。その原因（OSの再インストール、別のマシンの使用、リンクの改ざんなど）を確認してから再確認してください。

**認証.**既存のSSH設定（ssh-agent、~/.ssh/config、キー）が透過的に再利用されます。公開鍵認証に失敗した場合のみパスワード入力画面が表示されます。「Remember password」を選択すると、パスワードはシステムキーチェーンに保存され（データベースには保存されません）、次回も再利用されます。

データモード: 「リモートデスクトップアプリのデータベースを使用する」。 チェックされていない場合（デフォルト）、リモートサーバーはそのマシンにインストールされているどのVelaTermデスクトップアプリとも完全に分離された独立したデータディレクトリ(~/.velaterm/data)を使用する。チェックされている場合は、リモートデスクトップのリリースビルドのデータベースが使用され、両側で同じセッショントリーが表示される。これは「そのマシンで日常的にVelaTermを実行しており、私が遠隔から同じプロジェクトを引き継ぐ」といった状況に適している。共有されるのはディスク上のデータベースファイルのみで、実行中のプロセスは共有されない（§4.1参照）。両端を同じバージョンに保つことが推奨される。

最近のホスト。 接続したホストが一覧表示される。いずれかをクリックしても入力欄のみが埋められ、自動接続は行われない。内容を確認したら「接続」をクリックする。鍵のアイコンは保存されたパスワードを意味し、×はそのホスト（および保存されたパスワード）を忘却する。

接続進行状況。 初回接続時にはサーバーバイナリ（数十MB）が転送される。ボタンには「準備中」/「転送中」とパーセンテージが表示される。再接続時には既にリモート側にあるサーバーが再利用され、はるかに高速になる。

3.2 URLモード：相手側で既にリモートアクセスが有効な場合

別のマシンのVelaTermでリモートアクセスが実行中であり（§2）、そのペアリングリンクを持っている場合に使用する。通常のブラウザでリンクを開くのと比べて、専用ウィンドウが提供され、キーチェーンによる自動ログインやアプリによる指紋認証が行われる。

ペアリングリンクを貼り付け、相手側で設定されたアクセスパスワードを入力し、「接続」をクリックする。初回接続時にはTLS証明書の指紋が確認される（相手側のパネルに表示される証明書の指紋と比較）。その後、指紋が変わらない限り直接接続される。パスワードの記憶も同様にシステムキーチェーンを介して行われる。

4. 接続解除、ウィンドウの閉じ方、そして何が残るか

4.1 3つの状態レイヤー

「接続を解除した後もデータが残るかどうか」は、どのレイヤーについて聞いているかによって異なる：

最初の2つのレイヤーは設計上安全である。考慮すべき唯一のレイヤーは3番目のレイヤーだ。リモートサーバープロセスが生存している限り、実行中のセッションも生存する。

4.2 ウィンドウを閉じることの意味

SSHモード：この接続によってリモートサーバーが起動され、あなたが所有しているため、ウィンドウを閉じるとどうするかが問われる。「サーバーを停止」を選ぶとリモート側でサーバーが停止し（実行中のセッションも終了する）。「実行を続ける」を選ぶとあなた側のみが接続を解除され、サーバーはそのまま稼働し続けるため、次にそのマシンに接続するとすべてのセッションがそのまま残る。外出中もエージェントに作業を続けてもらいたい場合は「実行を続ける」を選ぶ。

URLモード：あなたは既にそちらで実行中のプログラムのゲストとして接続している。ウィンドウを閉じると単に退出するだけで、相手側はそのまま続けており、戻ってきたときにはすべてが元通りになっている。

4.3 接続の切断と再接続

ネットワークの不具合が発生すると、リモートウィンドウの上部に赤い再接続バーが表示され、自動的に再試行が行われる。実行中のセッションには影響しない — SSHモードではリモートサーバーはSSHセッションから切り離されており、設計上ネットワーク切断にも耐えられる。

知っておくべき境界点が1つある。自動再接続はウィンドウからローカルのフォワードポートへの接続部分のみを対象とする。SSHトンネルプロセスやリモートサーバー自体が停止している場合、赤いバーは永遠に回転し続け、再接続機能も効果がない。メインウィンドウに戻って再度「接続」をクリックする必要がある。接続処理ではリモートサーバーがまだ生存しているかが検出され、生存していれば再利用され（セッションはそのまま）、死亡している場合のみ新しいサーバーが起動される。

また、リモートマシンがスリープ状態、ログアウト、または再起動するとSSHモードのサーバーとその実行中のセッションは終了する。セッショントリーはディスク上にあるため影響を受けない。

4.4 速参照

5. セキュリティモデルの概要

パスワード（SSHアカウントパスワード、リモートログインパスワード）は、明示的にオプトインした場合のみシステムキーチェーンに保存され、データベースには保存されない。LANブラウザからのアクセスは自己署名証明書を使用したTLSで行われ、ペアリングリンクにはエンドツーエンド暗号化用の資格情報が含まれ、サーバーはペアリングされていない平文の接続を拒否する。SSHホストキーとリモートTLS証明書の両方とも「初回使用時のみ信頼」方式を採用しており、既知で変更されていないものは直接接続され、新しいターゲットには1回の認証プロンプトが表示され、指紋が変更されている場合は赤い警告が表示される — 確認する前に調査する必要がある。個々のデバイスはいつでもブロックでき（§2.4）、ペアリングリンクも自由に再生成できる。

もう1つ：リモートウィンドウのタイトルバーに赤い「⚠ vX ≠ vY」というバッジが表示されている場合、あなたのクライアントUIとリモートサーバーは異なるバージョンになっている。機能が一致しない可能性があるため、両端を同じバージョンにアップグレードすること。

6. よくある質問

**接続はできているのにサイドバーが空のまま、または赤いバーが永遠に回り続けている？**おそらくSSHトンネルやリモートサーバーがなくなっているためです。ウィンドウ内での再接続では解決できません（§4.3）。メインウィンドウに戻り、再度接続してください。

**ポート8799が起動しない？**他のプログラムがそのポートを使用している可能性があります。パネルで別のポートを選択し、再度起動してください。

**ブラウザで証明書が信頼できないと表示される？**自己署名証明書の場合はこれは正常な動作です。フィンガープリントを確認して続行してください（§2.2）。ブラウザごとの警告を無視するには、ペアリングリンクからアクセスし、アプリが自動的に信頼処理を行います。

**離れている間もリモートエージェントを動作させたい？**SSHモードで「ウィンドウを閉じても実行を続ける」を選択すると、セッションはリモート側で継続します。後で再接続すれば、中断した場所からそのまま続けられます。

**スマートフォン上のターミナルが非常に小さい？**これはデスクトップの解像度に合わせてスケーリングされているためです。ターミナルの右上にある「このウィンドウに合わせてクリック」をタップすると、現在のデバイスでのサイズ調整が可能になります。