camilbenameur/remote-devbox

remote-devbox は何をしますか？

あなたはdevboxのセットアップ（または修復）を行っています。devboxは、ユーザーのコンピュータ上のClaude Desktopアプリがインターフェースのみを担当し、Claude CodeセッションがLinuxサーバー上で実行される環境です。以下のフェーズを順番に進めてください。各フェーズには、あなたが行うこと、ユーザーのみが行えること、および正常に動作したことを確認する方法が記載されています。

<skill> はこのファイルが含まれているフォルダを意味します。

ユーザーが得られるもの

• デスクトップアプリの Code タブはそのままに、すべてのセッションがSSH経由でdevbox上で実行されます：シェル、テスト、インストール、Python、Node、Chrome。コンピュータはインターフェースの描画のみを行います。
• ユーザーのサブスクリプションが使用され、APIクレジットは使用されません。デスクトップアプリはセッションのサインインを渡して更新します。devbox上で ANTHROPIC_API_KEY を設定しないでください：課金がAPIに移行します。
• MCPサーバーとして2つのブラウザ：chrome（ユーザーのアカウントにログインした共有Chrome）とplaywright（セッションごとに独立した空のChrome）。仮想スクリーンにより、ユーザーのプライベートネットワーク上の任意のウェブブラウザで共有Chromeを表示できます（noVNC）。
• コンピュータの電源がオフでも継続するセッション：devbox-relay は切断されたDesktopセッションをバックグラウンドで再開し、devbox-rc はclaude.ai/codeまたは電話アプリから開始されたセッションをホストします。
• コンピュータと同じグローバル CLAUDE.md、スキル、メモリ、プラグインフック。

メカニズムが必要な場合は references/how-it-works.md を、問題が発生した場合はすぐに references/troubleshooting.md を参照してください。

あなたの基本ルール

• ユーザーが行うこと：支払いと注文、すべてのパスワードとサインイン（プロバイダー、Tailscale、GitHubデバイスコード、Claude /login、共有Chromeのウェブサイト）、デスクトップアプリの設定でのクリック、Tailscale管理コンソール。ユーザーには正確なリンクまたはコマンドを一度に1つずつ提供し、待機してください。パスワード、カード番号、またはワンタイムコードを自分で入力しないでください。
• 何かを注文する前に、計画、価格、契約内容を説明し、承諾を得てください。
• セットアップスクリプトは冪等です：失敗した場合はエラーを読み、原因を修正し、再度実行してください。
• devboxでは、sudoにパスワードは必要ありません。ただし、スクリプト自体が行わないシステム変更（パッケージ、サービス、ファイアウォール、sshd、ユーザー）を行う前に、ユーザーに確認してください。
• ユーザーの稼働中のdevboxで作業する場合、devbox-* サービスを停止したり、~/.claude を編集したり、~/.local/bin のバイナリを置き換えたりする前に、必ずその旨を伝えてください：ユーザーのセッションが実行中である可能性があります。

フェーズ0：コンピュータの確認

1. プラットフォーム。Windows：<skill>/client/windows/ のスクリプト（Windows PowerShell 5.1で問題ありません）。macOSまたはLinux：<skill>/client/unix/。
2. Windowsのみ：OpenSSHクライアント9.4以降（ssh -V）。デスクトップアプリに必要です。古い場合：winget install Microsoft.OpenSSH.Preview。
3. Claude Desktopアプリがインストールされサインインしており、ユーザーのプランにClaude Codeが含まれていること。
4. git config --global user.name と user.email が設定されていること（スクリプトがdevboxにコピーします）。
5. ユーザーに希望するオプション部分を尋ねてください：gatehaul（GitHub Codespacesで大規模ビルドを実行、-Gatehaul / --gatehaul）、共有ログイン済みChrome（デフォルトでオン）、メモリコピー。

フェーズ1：サーバーの選択と注文

references/providers.md を使用してください。要件：KVM仮想マシン、Ubuntu 24.04、x86_64推奨（arm64でも動作しますが、エンドツーエンドでテストされていません）、最低8 GBのRAM（複数の並列セッションとChromeを使用する場合は16〜24 GB）、80 GBのディスク、およびプロバイダーからのウェブコンソール（SSHがロックされた場合の救済パスです）。

ユーザーが比較できるように支援し、ブラウザが使える場合は注文ページを開いてあげてください。ユーザーがプランを選択し、支払い、確認します。プロバイダーが注文時にSSHキーを要求する場合は、最初にそれを表示します：

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -ShowKey

bash <skill>/client/unix/setup-devbox.sh --show-key

ユーザーにパブリックIPと初期ユーザー（多くの場合 root；OVHとOracleでは ubuntu）を尋ねてください。

フェーズ2：サーバーのブートストラップ

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -HostAddress <IP> -InitialUser root

bash <skill>/client/unix/setup-devbox.sh --host <IP> --initial-user root

ユーザーが入力できるターミナルで実行してください（デスクトップアプリのターミナルパネル、またはユーザーに実行を依頼してください）。ユーザーからの3つの入力が必要です：

1. ホストキーのフィンガープリント。 スクリプトがそれを表示し、yes/noを尋ねます。ユーザーにプロバイダーのウェブコンソールの ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub の出力と比較するよう伝えてください。
2. 初期パスワード（1回のみ）、キーを承認するため（注文時にキーが指定された場合はスキップされます）。
3. GitHubデバイスコード：gh auth login がコードとリンクを表示します。

スクリプトの内容：キー ~/.ssh/devbox_ed25519 を作成（パスフレーズなし、デスクトップアプリがプロンプトなしで接続する必要があります）、host/10-root-bootstrap.sh を実行（devユーザーとsudo、キーのみのSSH、linger、スワップ、Node、gh、Chrome、Tailscale、ufw、fail2ban、unattended upgrades、仮想スクリーンパッケージ）、Host devbox ブロックを ~/.ssh/config に追加、テスト、SSHをdevユーザーのみに制限、host/20-user-setup.sh を実行（uv、Claude Code CLI、オプションのgatehaul、MCPサーバー、~/.local/bin ツール、仮想スクリーンサービス、リレーサービスとフック）、その後Claude設定を同期（フェーズ6）。

確認：ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'。

フェーズ3：プライベートネットワーク、そしてパブリックSSHの閉鎖

1. ユーザー：コンピュータにTailscaleをインストールしてサインイン（winget install tailscale.tailscale、Mac App Store、またはtailscale.com/download）。
2. devbox上：ssh -t devbox sudo tailscale up --hostname=devbox。サインインリンクが表示されます：ユーザーが開きます。
3. ユーザー：Tailscale管理コンソール、Machines、devbox、Disable key expiry。そうしないと、devboxは180日後にネットワークから離脱し、プロバイダーコンソールのみが残ります。
4. ~/.ssh/config で、devbox ブロックの HostName を devbox（MagicDNS）または ssh devbox tailscale ip -4 のアドレスに設定します。ssh devbox true で確認します。
5. パブリックSSHを閉鎖：ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'。Tailscale経由ではないSSHセッションが開いている場合、スクリプトは拒否します：それらのセッションを先に閉じてください（パブリックIPで開かれたデスクトップアプリアプリのセッションを含む）。

ロックアウト時の救済：プロバイダーウェブコンソール、その後 sudo ufw allow OpenSSH。

フェーズ4：デスクトップアプリの接続

ユーザーがデスクトップアプリで行うこと：Code タブ、プロンプトボックスの下の環境メニュー、New environment、SSH（2026年後半のラベル、変更される可能性があります）：

フィールド	値
SSHホスト	devbox（~/.ssh/config から取得）
SSHキー	空
ワークツリーフォルダ	~/worktrees
セッションのフォルダ	~/dev/<project>

最初の接続時に、アプリはdevbox上の ~/.claude/remote/ に自身のエンジンをインストールし、ホストキーを表示します：フェーズ2と同じフィンガープリントです。この環境でのセッションはdevbox上で実行されます。SSHセッションにはブラウザペインはありません：代わりにポートを転送してください（「日常的な使用」を参照）。

フェーズ5：ログイン済みChrome

1. ssh devbox devbox-browser login（Chromeがデバッグポートなしで再起動します。GoogleはデバッグポートがあるChromeでのサインインをしばしば拒否するためです）。
2. ユーザーがtailnet上のマシンから http://devbox:6080/vnc.html を開きます。パスワード：ssh devbox devbox-browser password。Tailscaleを使用しない場合：ssh -N -L 6080:localhost:6080 devbox を実行し、http://localhost:6080/vnc.html を開きます。
3. ユーザーがエージェントに使用させたいサイトにサインインします。銀行や、注入された指示が金銭的損害をもたらす可能性のあるサイトは避けるようアドバイスしてください：すべてのセッションがこのブラウザを操作できます。
4. ssh devbox devbox-browser normal でエージェントに引き渡します（デバッグポート9222、ローカルのみ）。

確認：devboxセッションで、chrome MCPにユーザーがサインインしたサイトを開くよう依頼し、機密コンテンツを読まずにアカウントが表示されることを確認します。タスクバーのアイコンと画面の右クリックメニューでこのChromeを開きます。これはdevboxのデフォルトブラウザでもあります。

フェーズ6：ローカルClaude環境のミラーリング

目標：devbox上のセッションがコンピュータ上と同じように動作すること。

1. グローバルCLAUDE.mdとスキル：

   powershell -ExecutionPolicy Bypass -File <skill>\client\windows\sync-claude-config.ps1 -Memory
   

   bash <skill>/client/unix/sync-claude-config.sh --memory
   

   これにより、ローカルの ~/.claude/CLAUDE.md の先頭に <skill>/templates/host-header.md（devboxで異なる点：パス、ブラウザ、画面、継続性、sudoルール）が追加され、~/.claude/skills（.venv、node_modules、.git を除く）がマージされ、-Memory オプションでローカルプロジェクトフォルダ（-LocalDevDir、デフォルト ~/Documents/dev）の自動メモリがdevboxの ~/dev のメモリにコピーされます。ローカルのCLAUDE.mdまたはスキルが変更されたら、再実行してください。devbox上のコピーは上書きされるため、ヘッダーテンプレートを編集し、コピーを編集しないでください。
2. セットアップが必要なスキル：同期された各スキルについて、Python環境（requirements.txt、pyproject.toml）、Nodeパッケージ、バイナリ、SKILL.md 内のWindowsパスを確認してください。devbox上で環境を再作成し、パスを修正してください。必要なシステムツール（例：ffmpeg）は、ユーザーに確認してからインストールしてください。
3. プラグイン：デスクトップアプリはSSHセッションにユーザーのプラグインをインストールしますが、フックはそこで実行されません。hooks/hooks.json を持つ有効なプラグインごとに、そのソースをdevbox上の同じコミットで ~/.claude/hooks-thirdparty/<plugin> にクローンし、そのフックをdevboxの ~/.claude/settings.json にマージします。${CLAUDE_PLUGIN_ROOT} はそのフォルダに置き換え、インタプリタはLinux用に修正します（python を python3 に）。jq でマージします。既存の devbox-relay guard SessionStartフックは保持してください。フックスクリプトを有効にする前に読んでください。
4. MCPサーバー：ローカルとdevboxで claude mcp list を比較します。Linuxで意味のあるユーザースコープのstdioサーバーを再追加してください。claude.aiコネクタはアカウントに従うため、何もする必要はありません。
5. プロジェクト：gh repo clone で ~/dev/<name> にクローンします。重要なコミットされていない、または無視されているローカルファイル（.env ファイルはユーザーの同意がある場合のみ）をコピーし、依存関係をインストールし、軽いテストを実行します。大規模なビルドは、インストールされている場合はgatehaulを介してCodespacesに属します。
6. ユーザーなしでの長い移行：移動するものが多い場合は、作業リストを作成し、references/setup-agent-prompt.md を使用して claude-task 経由でdevbox上で自律セッションを開始します。

フェーズ7：コンピュータの電源がオフでも継続するセッション

1. devbox上のCLIサインイン（リレーとリモートコントロールが使用します）：ssh -t devbox claude、次に /login；ユーザーがリンクを開いてコードを貼り付けます；/exit。
2. リレー：20-user-setup.sh によって既に有効化されています。ssh devbox devbox-relay test（すべてのケースがOK）と ssh devbox devbox-relay status で確認します。
3. リモートコントロールサーバー、2回の確認が必要なため手動で1回のみ：ssh -t devbox 'cd ~/dev && claude remote-control'、ユーザーが y を2回押し、次にCtrl+C。その後 ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'。claude.ai/codeまたは電話アプリで、フォルダとホスト名にちなんだ名前の環境（例：dev · <hostname>）がdevbox上でセッションを開始するようになります。自律的に進行させるべきセッションには、そこで Auto 許可モードを選択してください。claude.aiがデバイスを確認するためにユーザーに再度サインインを求める場合があります。
4. オプションの実際のテスト（ユーザーと一緒に）：許可質問で停止する小さなタスクをDesktopセッションで開始し、ユーザーがデスクトップアプリを終了し、約30分待って、再度開きます；ログ ~/dev/_relay/log.md にリレーが表示され、devbox上の claude agents に relay · <name> が表示され、再開された元のセッションはリレーされたと表示されます。

フェーズ8：最終確認

各行を実行して報告します：

ssh devbox 'claude --version; gh auth status 2>&1 | head -3; claude mcp list'
ssh devbox 'systemctl --user is-active devbox-vnc devbox-wm devbox-novnc devbox-panel devbox-chrome devbox-relay devbox-rc'
ssh devbox 'devbox-browser status; devbox-relay test | tail -1; free -h; df -h ~'
ssh devbox 'grep -c ANTHROPIC_API_KEY ~/.bashrc ~/.profile 2>/dev/null; sudo ufw status'

期待される結果：すべてのサービスが active（devbox-rc はフェーズ7後）、MCPサーバー chrome と playwright が接続済み、APIキーなし、ufwが tailscale0（および41641/udp）のみ許可。 その後、ユーザーに何が準備できたか、まだ何をする必要があるか、各部分にアクセスする方法を伝えてください。

日常的な使用（ユーザーに伝えること）

• 開発サーバーを表示する：devbox上で 127.0.0.1:<port> で実行し、コンピュータ上で ssh -N -L <port>:localhost:<port> devbox を実行し、http://localhost:<port> を開きます。
• tmuxでの長時間タスク：claude-task start <name> ~/dev/<project> "<prompt>" [--rc] [--mode auto]、次に claude-task list | show | send | stop；tmux attach -t ct-<name>（Ctrl+b d で離脱）。
• セッションを意図的にバックグラウンドに渡す：claude --resume <id> --fork-session --bg --remote-control "<name>" --permission-mode auto "<prompt>"。
• リレーアクティビティ：ssh devbox devbox-relay status、ログは ~/dev/_relay/log.md。
• ツールの更新：PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh。
• 電源がオフのサーバーでも通常は課金が発生します。