logo
n min

🤖

VirtualBox + VSCode での開発環境を劇的に効率化!SSH接続とワンクリック起動自動化ガイド.

投稿日

更新日

はじめに

Windows上でVirtualBoxを使いLinux環境で開発を行っている皆さん、こんなお悩みはありませんか?

  • 「VMを起動して、VSCodeを開いて、SSH接続して…毎回の準備が面倒!」
  • 「VSCodeでせっかく開発プロファイルを作ったのに、SSH接続するとデフォルトで開いてしまう…」
  • 「VMのGUIは使わないのに、リソースもウィンドウも無駄に感じる…」

この記事では、そんなお悩みを解決し、開発フローを大幅に効率化する方法をご紹介します。ホストOSのVSCode系エディタからゲストOS(Linux Mint想定ですが、他のLinuxディストリビューションでも応用可能)にスムーズに接続し、最終的にはデスクトップのショートカット一つでVMの起動(ヘッドレス)、SSH接続、VSCodeの起動までを自動化することを目指します。

📌 前提条件

  • ホストOS:Windows 11
  • ゲストOS:VirtualBox上のLinux(記事内ではLinux Mint 22を例としますが、Ubuntuなど他のDebian系ディストリビューションでも同様の手順で設定可能です)
  • エディタ(ホストOS):VSCodeまたはその派生エディタ(以下、VSCodeと表記)
  • VirtualBox Guest AdditionsがゲストOSにインストール済みであること。

⚠️ 免責事項

  • 本記事の内容は、特定の検証環境(研究室の開発環境)に基づいており、お使いの環境では同様に動作しない可能性があります。
  • 作業を実施する際は、万が一に備え、仮想マシンのスナップショット作成やファイルのバックアップなど、各自の環境に応じた安全対策を行ってください。
  • 記事内の情報は執筆時点のものです。各種ツールやソフトウェアのバージョンアップにより、内容が古くなったり手順が変更されたりする可能性があります。
  • 必要に応じて、VirtualBox、VSCode、SSH、お使いのLinuxディストリビューションなどの公式ドキュメントも併せてご参照ください。

☁️ 1. VSCodeからゲストOSへSSH接続する準備

まずは、ホストOSのVSCodeからゲストOSのLinux環境へSSHで接続できるように設定します。

1.1. VirtualBox ネットワーク設定の変更

SSH接続を受け付けるために、VirtualBoxのネットワーク設定でポートフォワーディングを設定します。

  1. VirtualBox マネージャーを開き、対象の仮想マシン(例:Linux Mint)を選択し、シャットダウンします。
  2. 仮想マシンの「設定」を開き、「ネットワーク」セクションへ進みます。
  3. 「アダプター1」(または利用するアダプター)で以下のように設定します。
    • 割り当て: NAT
      • NATを選択することで、ゲストOSはホストOSのIPアドレスを共有して外部ネットワークに接続しつつ、ポートフォワーディングでホストOSからゲストOSへの特定の通信を許可できます。
    • 「高度」を展開し、「ポートフォワーディング」ボタンをクリックします。
    • ルールを新規追加(右側の + ボタン)し、以下のように設定します(ゲストIPは空欄でも構いません)。
      名前プロトコルホストIPホストポートゲストIPゲストポート
      SSHTCP222222
      • ホストポート 2222: ホストOS側でSSH接続を待ち受けるポートです。他のサービスと重複しない任意の番号に変更可能です。
      • ゲストポート 22: ゲストOSのSSHサーバーが待ち受ける標準ポートです。

1.2. ゲストOSでのSSHサーバーの構築と自動起動設定

次に、ゲストOS(Linux Mint)にSSHサーバーをインストールし、起動と自動起動の設定を行います。

  1. 対象の仮想マシンを起動します。
  2. ゲストOSのターミナルを開き、以下のコマンドを実行してOpenSSHサーバーをインストールします。
    Guest OS
  3. SSHサービスを起動し、OS起動時に自動で起動するように設定します。
    Guest OS
  4. SSHサービスのステータスを確認します。active (running) と表示されていれば正常です。
    Guest OS
  5. 自動起動が有効になっているか確認します。enabled と表示されていればOKです。
    Guest OS

1.3. ゲストOSのファイアウォール設定 (UFW)

ゲストOSでファイアウォール(UFW: Uncomplicated Firewall)が有効になっている場合、SSH接続を許可する設定が必要です。

  1. SSHが使用するポート(デフォルトは22)への接続を許可します。

    Guest OS
  2. 設定をリロード(再読み込み)します。

    Guest OS
  3. ファイアウォールの状態とルールを確認します。22/tcp (または 22) が ALLOW IN Anywhere となっていればOKです。

    Guest OS
    • もし ufw がインストールされていない場合は、sudo apt install ufw でインストール後、sudo ufw enable で有効化してください。

1.4. SSH接続の確認 (ホストOSから)

ホストOS(Windows)のターミナル(コマンドプロンプトやPowerShell)から、ゲストOSへSSH接続できるか確認します。

Host OS
  • your_guest_username はゲストOSのユーザー名に置き換えてください。
  • -p 22222 は、VirtualBoxのポートフォワーディングで設定したホストポートです。
  • 初回接続時にはフィンガープリントの確認を求められるので yes と入力し、その後ゲストOSのユーザーパスワードを入力します。ログインできれば成功です。

1.5. VSCodeでのSSH接続設定

VSCodeから簡単にSSH接続できるように設定します。

  1. ホストOSのVSCodeを起動します。

  2. Remote - SSH拡張機能のインストール: もしインストールしていなければ、VSCodeの拡張機能マーケットプレイスから「Remote - SSH」(ms-vscode-remote.remote-ssh)を検索してインストールします。

  3. SSH Configファイルの設定: SSH接続の設定をSSH Configファイルに記述します。このファイルは通常、ホストOSのユーザーディレクトリ配下の .ssh フォルダ(例: C:\Users\[ユーザー名]\.ssh\config)にあります。ファイルがない場合は新規作成してください。 以下の内容を追記または新規作成します。

    .ssh/config
    • your_ssh_alias: 任意の接続名(例: vbox-mint)。VSCodeの接続先一覧に表示されます。
    • your_guest_username: ゲストOSのユーザー名。
    • Port 22222: VirtualBoxのポートフォワーディングで設定したホストポート。
  4. VSCodeからSSH接続:

    1. VSCodeの左下にある緑色の「リモートウィンドウを開きます」アイコン(通常 >< のような形)をクリックします。
    2. ドロップダウンメニューから「ホストに接続する (Connect to Host...)」を選択します。
    3. 先ほどSSH Configファイルで設定した your_ssh_alias が表示されるので、それを選択します。
    4. 初回接続時は接続先のOSの種類を聞かれる場合があります。「Linux」を選択してください。
    5. 新しいVSCodeウィンドウが開き、ゲストOSのユーザーパスワードの入力を求められます。パスワードを入力して接続できれば成功です。ウィンドウの左下に SSH: your_ssh_alias と表示されます。

    これで、ホストOSのVSCodeからゲストOSのファイルシステムにアクセスし、ターミナルもゲストOSのものを直接利用できるようになりました。

ここまでの設定での課題点:

  • 毎回SSH接続時にパスワード入力が必要(これはSSHキー認証で改善可能ですが、この記事では扱いません)。
  • VSCodeで特定の開発プロファイル(拡張機能のセットなど)を使って接続したい場合、一手間かかることがある。
  • ゲストOSをVirtualBoxマネージャーから手動で起動する必要があり、GUIウィンドウが表示される。

次のセクションでは、これらの課題を解決するための自動化手順に進みます。


🤖 2. 起動と接続の自動化

目標は、デスクトップのショートカットをワンクリックするだけで、以下の処理を自動で行うことです。

  1. VirtualBoxのゲストOSをヘッドレスモード(GUIなし)で起動。
  2. ゲストOSのSSHサーバーが起動するまで待機。
  3. 指定したVSCodeプロファイルとワークスペースで、ゲストOSへSSH接続した状態でVSCodeを起動。

2.1. VBoxManage コマンドラインツールの利用準備

VirtualBoxをコマンドラインから操作するために、VBoxManage.exe へのパスを通します。

  1. Windowsの「設定」→「システム」→「バージョン情報」と進み、「システムの詳細設定」をクリックします。
  2. 「環境変数」ボタンをクリックします。
  3. 「システム環境変数」の「Path」を選択し、「編集」をクリックします。
  4. 「新規」をクリックし、VirtualBoxのインストールディレクトリ(通常は C:\Program Files\Oracle\VirtualBox)を追加します。
  5. OKを押して全てのダイアログを閉じ、設定を反映させるためにPCを再起動するか、新しいコマンドプロンプト/PowerShellウィンドウを開きます。
  6. コマンドプロンプトまたはPowerShellで VBoxManage --version を実行し、バージョン情報が表示されればパスが通っています。
  7. 自動化スクリプトで使用するVMの名前を確認しておきます。
    Host OS
    表示されたリストから、対象のVMの名前(例: "Linux Mint 22""MyLinuxVM"など、引用符も含めて)を控えておきます。以降、このVM名を Your_VM_Name とします。

2.2. ゲストOSのSSH準備完了通知の設定

ゲストOSが起動しSSH接続の準備が整ったことをホストOSに伝える仕組みを構築します。これにはVirtualBoxのGuest Properties機能を利用します。

  1. 対象の仮想マシンを起動します。

  2. ゲストOS側: SSH準備完了通知スクリプトの作成 ゲストOSのホームディレクトリなどに、SSHサービスの起動を確認してGuest Propertyを設定するスクリプトを作成します。例えば、~/bin/set-ssh-ready.sh として以下の内容で作成します。~/bin ディレクトリがない場合は作成してください。

    • set-ssh-ready.sh

      set-ssh-ready.sh
    • スクリプトに実行権限を付与します。

      Guest OS
  3. ゲストOS側: systemdサービスファイルの作成 上記スクリプトを、ネットワークとSSHサービスが起動した後に実行するためのsystemdサービスユニットファイルを作成します。 sudo nano /etc/systemd/system/set-ssh-ready.service などでエディタを開き、以下の内容を記述します。your_guest_username は実際のゲストOSのユーザー名に置き換えてください。

    • set-ssh-ready.service

      Guest OS
      • 重要: ExecStart のパスは、実際のスクリプトの場所とユーザー名に合わせてください。
      • After ディレクティブに sshd.service も追加しておくと、ディストリビューションによってSSHデーモンのサービス名が異なる場合に対応しやすくなります。
  4. ゲストOS側: systemdサービス有効化と確認

    • systemdに新しいサービスファイルを認識させ、自動起動を有効にします。

      Guest OS
    • ゲストOSを再起動します: sudo reboot

    • 再起動後、サービスが一度実行されたか(inactive (dead)status=0/SUCCESS ならOK)、Guest Propertyが設定されたかを確認します。

      Guest OS
      • もし緑色で active (running) になっていなかったり、Value: true が表示されない場合は、スクリプトのパス、実行権限、サービスファイルの内容、Guest Additionsのインストール状態などを確認してください。
  5. ホストOS側: Guest Propertyの確認 ホストOSのコマンドプロンプトやPowerShellから、ゲストOSのプロパティが正しく設定されているか確認します。Your_VM_Name は実際のVM名に置き換えてください。

    Host OS

2.3. ホストOS側: VSCodeワークスペースファイルの作成 (任意)

特定のプロジェクトフォルダをVSCodeで開くように、ワークスペースファイルを作成しておくと便利です。これはSSH接続後に開きたいゲストOS上のフォルダを指定します。

  1. ホストOSの任意の場所(例: C:\Users\[ユーザー名]\Documents\VSCodeWorkspaces)に、 .code-workspace という拡張子でファイルを作成します(例: my-linux-project.code-workspace)。

  2. ファイルに以下のJSON形式で内容を記述します。

    • my-linux-project.code-workspace
      my-linux-project.code-workspace
    • uri のパスや remoteAuthority は、ご自身の環境に合わせて正確に設定してください。
    • tasks 内のVMシャットダウンタスクは、VSCodeのコマンドパレット (Ctrl+Shift+P) から Tasks: Run Task を選択し、Shutdown Guest VM を実行することで、VMをシャットダウンできます。これはホストOS側のコマンドとして実行される点に注意してください。

2.4. ホストOS側: 自動起動用PowerShellスクリプトの作成

VMの起動、SSH準備待機、VSCodeの起動を連続して行うPowerShellスクリプトを作成します。

  1. ホストOSの任意の場所(例: C:\Users\[ユーザー名]\Scripts)に、 .ps1 という拡張子でスクリプトファイルを作成します(例: launch-linux-dev-env.ps1)。

  2. 以下のスクリプトを参考に、ファイルに内容を記述します。<...> のプレースホルダー部分はご自身の環境に合わせて必ず変更してください。

    • launch-linux-dev-env.ps1

      launch-linux-dev-env.ps1
  3. デスクトップにショートカットを作成:

    1. デスクトップで右クリックし、「新規作成」→「ショートカット」を選択します。
    2. 「項目の場所を入力してください」の欄に以下のように入力します。<Path_To_Your_Script_File.ps1> は上記で作成したPowerShellスクリプトのフルパスに置き換えてください。
      例: powershell.exe -ExecutionPolicy Bypass -File "C:\Users\YourUser\Scripts\launch-linux-dev-env.ps1"
    3. 「次へ」をクリックし、ショートカットに任意の名前(例: Linux開発環境起動)を付けて「完了」します。

2.5. 起動テストと確認

  1. 作成したデスクトップショートカットをダブルクリックして実行します。
  2. PowerShellのウィンドウが開き、ログメッセージが表示されながら処理が進みます。
    • VMが起動(ヘッドレスなのでVirtualBoxのGUIは表示されません)。
    • SSH準備完了の待機。
    • VSCodeが起動。
  3. VSCodeが起動し、指定したプロファイルで、かつゲストOSへSSH接続された状態(左下に SSH: your_ssh_alias と表示)で、指定したワークスペースが開かれれば成功です。初回接続やプロファイルが新しい場合は、パスワード入力や確認ダイアログが表示されることがあります。

正常に動作しない場合の確認ポイント:

  • PowerShellスクリプト内の各パス(VM名、VSCode実行パス、ワークスペースパス)が正しいか。
  • PowerShellスクリプトの実行ポリシー(-ExecutionPolicy Bypass で一時的に許可していますが、恒久的な設定は Set-ExecutionPolicy コマンドで調べてください)。
  • VBoxManageコマンドがパスを通して正しく実行できるか。
  • ゲストOS側の set-ssh-ready.sh スクリプトと set-ssh-ready.service の設定、パーミッション、パスが正しいか。
  • ゲストOSのGuest Additionsが正しくインストールされ動作しているか。
  • VirtualBoxのネットワーク設定(ポートフォワーディング)が正しいか。
  • ゲストOSのファイアウォール設定が正しいか。
  • VSCodeのSSH Configファイルの内容が正しいか。
  • PowerShellウィンドウに表示されるエラーメッセージを確認する。

💬 最後に

ここまでの設定で、デスクトップのショートカット一つで開発環境が整うようになりました。

開発フローの改善例

  1. 作成したショートカットを実行。
  2. VSCodeが起動し、ゲストOSへのSSH接続が確立されます(初回やキー設定によってはパスワード入力)。
  3. VSCode内でコーディングを開始。
  4. VSCode内のターミナル(これはゲストOSのターミナルです)で開発サーバー(例: npm run dev, python manage.py runserver など)を起動します。
    • 開発サーバーがゲストOSの特定のポート(例: 3000, 8000)でリッスンする場合、VSCodeのRemote-SSH機能が自動的にそのポートをホストOSのlocalhostの同ポートにフォワーディングしてくれることが多いです。「ポート」タブで確認・手動設定も可能です。
  5. ホストOSのブラウザから http://localhost:3000http://localhost:8000 などでアクセスして動作確認。
  6. 開発終了後、VMをシャットダウンします。
    • VSCodeのコマンドパレット (Ctrl+Shift+P) から Tasks: Run Task を実行し、Shutdown Guest VM (2.3のワークスペースファイルで定義したタスク)を選択する。
    • または、後述のシャットダウン用ショートカットを利用する。

追加すると便利なTIPS

  • SSHキー認証の設定: 毎回のパスワード入力を省略するために、SSHキー認証を設定することを強く推奨します。ホストOSでSSHキーペアを作成し、公開鍵をゲストOSの ~/.ssh/authorized_keys に登録します。

  • 開発用サーバー起動タスクのカスタマイズ (.vscode/tasks.json): プロジェクトフォルダのルートに .vscode/tasks.json ファイルを作成することで、VSCodeから複数の開発サーバー起動などを一括で行うタスクを定義できます。 例えば、フロントエンドとバックエンドのサーバーを同時に起動するタスクは以下のように記述できます。(内容はプロジェクトに合わせて変更してください)

    • .vscode/tasks.json (ゲストOSのプロジェクトフォルダ内に配置)

      .vscode/tasks.json

      コマンドパレットから Tasks: Run TaskStart All Dev Servers で実行できます。

  • VMシャットダウン用ショートカット: VMを素早くシャットダウンするための専用ショートカットをデスクトップに作成します。

    1. 「デスクトップで右クリック」→「新規作成」→「ショートカット」
    2. 「項目の場所を入力してください」に以下のように入力します (Your_VM_Name は実際のVM名に置き換えてください)。
    3. 「次へ」をクリックし、ショートカットに任意の名前(例: VMシャットダウン)を付けて「完了」します。

Q&A

  • Q: VSCodeでRemote-SSH接続後、一部の拡張機能が動作しません。

    A: Remote-SSHでは、拡張機能は「UI拡張機能(ローカルで動作)」と「ワークスペース拡張機能(リモートのSSHサーバーで動作)」に分類されます。必要な拡張機能がリモート側(ゲストOS)にインストールされているか確認してください。拡張機能のサイドバーで、各拡張機能がどこにインストールされているか確認し、必要に応じて「SSH: your_ssh_alias にインストール」を選択してください。

  • Q: ゲストOS上のPythonインタープリターやNode.jsなどがVSCodeに認識されません。

    A: VSCodeのウィンドウがリモートサーバーに接続されていることを確認してください(左下に SSH: your_ssh_alias)。その上で、VSCodeのコマンドパレットから例えば Python: Select Interpreter や、Node.jsの場合は nvmnodenv 等でバージョンが正しく選択されているか、ゲストOSのターミナルで確認してください。VSCodeの設定 (settings.json) で明示的にパスを指定する必要がある場合もあります。


この記事は、私の環境における自動化の解答の一例です。 あなたの環境に合わせて、より良い方法を見つけて、よりよい開発ライフをお送りください!