本文へスキップ

ドキュメント Hub

スクリプト

スクリプトとは、VMPalがHubに保存しておくシェルスクリプトまたはPowerShellスクリプトです。Mac、VM、またはVMの新しいクローンで実行できます。VMの新しいクローンは、クリーンなCIランナーのように使えるうえ、自分の環境とデータがそろっています。スクリプトはHubから実行するほか、AIエージェントやvmpalに実行させることもできます。

AIエージェントに頼む

スクリプトを書いて実行するいちばん簡単な方法は、コーディングエージェントに頼むことです。エージェントがスクリプトを書いてVMPalのHubに保存し、指定した場所で実行します。実行が失敗したときは、ログも読みます。そのためにエージェントは、VMPalのMCPツールか、ターミナルのvmpal scriptを使います。

  1. VMPalで設定 › AIエージェントを開き、このMacのコーディングエージェントによるすべての仮想マシンの管理を許可をオンにします。
  2. Claude Codeに追加、またはほかのエージェントのボタン(対応エージェント)をクリックし、エージェントを再起動します。
  3. たとえば、次のように頼みます。
    • 「WindowsのVMでこのアプリをビルドするVMPalのスクリプトを書いて、今すぐ実行して。」
    • 「テスト用のスクリプトを実行して、失敗した理由を教えて。」
    • 「ビルド用のスクリプトをUbuntuのVMの新しいクローンで実行するようにして、30分で止まるようにして。」

このページの残りでは、しくみを知りたい方のためにスクリプトの動作を説明します。

スクリプトを作成する

VMPalはスクリプトをHubに保存します。

  1. Hubを開きます。VMPalのウインドウのツールバーにあるHubをクリックするか、表示 › Hub(⌘2)を選択します。
  2. 新規スクリプトをクリックします。名前を付け、言語を選び、スクリプトを書いて、作成をクリックします。新しいスクリプトの先頭には、使える変数を記したコメントが入っています。
  3. 実行場所を選びます。サイドバーの実行場所の横にある選択… をクリックします。または、スクリプトのメニュー(スクリプトを右クリックするか、⋯をクリック)を開いて、実行場所を変更… を選択します。

Hubの一覧では、スクリプトをダブルクリックするかReturnキーを押すと編集でき、Deleteキーを押すと削除でき、上下にドラッグすると並べ替えられます。VMPalのVMの一覧では、スクリプトが実行されるVMにスクリプトマークが表示されます。マークをクリックすると、Hubでそのスクリプトを確認できます。

実行場所

スクリプトは、VMの新しいクローン、VM自体、またはMacで実行できます。複数を選ぶと、それぞれの場所で実行されます。

VMでの実行には、エージェントによる操作が必要です。そのためVMPalは、スクリプトを実行する各VMでこの設定をオンにします。

VMの新しいクローン

VMを選んだ場合のデフォルトです。クローンとは、まっさらなCIランナーのような、VMの使い捨てのコピーです。実行ごとに専用のクローンが作られ、実行後にVMPalが削除します。

  • 軽量:VMPalはクローンを一瞬で作成します。軽量なクローンにはAPFSが必要です。APFS以外のドライブにあるVMでは、VM自体で実行します。
  • VMはシャットダウンしておく必要があります。VMのシャットダウンを使ってください。ウインドウを閉じると、VMはシャットダウンされずに保存されます。
  • 実行はVMのシャットダウンを最大30分待ちます。それを過ぎると、VMPalは実行をスキップします。
  • クローンにはMacのものが何も渡されません。共有フォルダ、転送ポート、クリップボードは使えません。

VM自体

VM自体で実行するには、実行場所を選ぶときに、VMの下にある実行ごとに仮想マシンの新しいクローンを作成のチェックを外します。すると、サイドバーのVMの下に仮想マシン自体で実行と表示されます。

  • VMPalはVMをバックグラウンドで起動または再開します。サインイン画面では、VMPalが保存しているパスワードでサインインします。実行後もVMは動作したままです。
  • VMが一時停止している場合、実行はVMが再開されるまで待ちます。
  • 実行では、設定どおりに、VM自身の共有フォルダ、クリップボード、ネットワークを使います。

このMac

スクリプトは、自分のアカウントでMac上で実行されます。vmpalやAIエージェントがここでスクリプトを実行させられるかどうかは、このMacでのスクリプトの設定で決まります。

実行のしくみ

スクリプトは、実行場所のシェルで実行されます。

場所 言語 実行に使うもの
LinuxのVM シェル bash
macOSのVM シェル zsh
自分のMac シェル zsh、または#!行のインタプリタ
WindowsのVM PowerShell Windows PowerShell
  • シェルスクリプトはログインシェルとして、ホームフォルダから実行されます。
  • 実行にはrootではなくユーザのアカウントを使います。ログインシェルのファイルが読み込まれます。Linuxでは~/.profile(~/.bashrcではありません)、macOSと自分のMacでは~/.zprofile(~/.zshrcではありません)です。そのため、ツールはすべてのユーザ向けにインストールするか、これらのファイルでPATHを設定してください。
  • 実行が成功したかどうかは終了コードで決まります。終了ステータスが0なら成功、それ以外なら失敗です。
  • PowerShellは、プログラムが失敗しても処理を続けます。そのため、プログラムを実行するたびに$LASTEXITCODEを確認してください。
  • VMPalがMacからコピーするのはスクリプトだけです。コードそのものは、git cloneなどを使ってスクリプト自身が取得します。

実行する

サイドバーまたはスクリプトのメニューで今すぐ実行をクリックします。スクリプトは、選んだ各場所で実行されます。まだ場所を選んでいない場合は、VMPalが実行場所を尋ねます。

別の場所で実行するには、スクリプトのメニューでOptionキーを押しながら場所を選んで実行… を選択します。VMPalはまず実行場所を尋ねます。そこでスクリプトを実行し、以降もその場所で実行するようになります。

履歴

サイドバーの履歴には、各実行が一覧表示されます。実行の状態、かかった時間、失敗した理由や待機している理由がわかります。

  • ログを表示で、実行の出力を開きます。
  • 停止で実行を停止します。スクリプトのメニューの実行を停止では、すべての実行を停止します。
  • 項目をダブルクリックすると、各実行のログを逐次表示しながら、すべての内容を確認できます。

ログ

ログはMacの~/Library/Logs/VMPal/Hubにあります。Hubでヘルプ › ログをFinderに表示を選ぶと、スクリプトのログが開きます。

  • VMPalは各ログを16MiB以内に保ちます。それより長いログは、先頭と末尾が残ります。
  • VMPalは、スクリプトごとに、終了した直近50回の実行をそのログとともに保持します。

VMPalの終了

実行中のものがあるときにVMPalを終了しようとすると、VMPalはまず確認し、実行を停止して終了を表示します。終了すると、実行を停止し、そのクローンを削除します。VMPalの終了時にまだ待機中だった実行は、開始されません。また、アップデートのインストールを待っている間は、何も開始されません。

スクリプトの設定

スクリプトの設定を変更するには、スクリプトのメニューでスクリプトを編集… を選択するか、サイドバーの名前の横にある編集… をクリックします。

設定 動作
言語 シェル、またはWindowsのVM向けのPowerShell
タイムアウト これより長く続く実行は、VMPalが停止します。5分〜6時間から選べます。デフォルトは1時間です。vmpalでは最大24時間まで設定できます
カラー Hubでのスクリプトの行と、スクリプトを実行するVMのスクリプトマークに色を付けます。Macのカラーから1つ選ぶか、なしにします。スクリプトのメニューのカラーや、サイドバーの名前の横にあるカラーボタンでも変更できます

スクリプトのメニューで複製を選ぶと、スクリプトのコピーがすぐ下に作成されます。スクリプトを削除… では、スクリプトとその実行、ログが削除されます。

変数

各実行には、次の環境変数が設定されます。

変数 値
VMPAL_SCRIPT_NAME スクリプトの名前
VMPAL_RUN_ID 実行のID
VMPAL_TARGET 実行場所。mac、またはVMの名前

PowerShellでは、$env:VMPAL_SCRIPT_NAMEなどの形で参照します。

制限

  • 各場所で一度に1つ:スクリプトは、実行場所ごとに一度に1つずつ実行され、さらに1つが待機できます。新しい実行は、待機中の実行と入れ替わります。
  • クローンは同時に2つまで:クローンでの実行は、同時に最大2つまで進みます。スクリプトがVMの次のクローンを作るのは、前のクローンをVMPalが削除してからです。
  • macOSのVMは同時に2台まで:macOSでは、自分で実行しているものも含めて、同時に実行できるmacOSのVMは最大2台です。2台が実行中の場合、macOSのVMでの実行は、どちらかが停止するまで待ちます。
  • VM自体での実行は一度に1つ:どのスクリプトであっても、VM自体で同時に行える実行は1つです。VM自体で実行するスクリプトは、最大32,000バイト(UTF-8)です。これより長いスクリプトの実行はVMPalがスキップするため、クローンで実行してください。
  • 開始までの待機は30分:VMのシャットダウン待ちなどで開始まで30分待った実行は、VMPalがスキップします。

このMacでのスクリプト

Mac上のスクリプトは、自分のアカウントでコードを実行します。そのためVMPalは、vmpalやAIエージェントがMacでスクリプトを実行させようとするときに、ある設定を確認します。対象となるのは、次の操作です。

  • スクリプトの実行場所にMacを追加する
  • そこでスクリプトを今すぐ実行する
  • そこで実行するスクリプトの本文を変更する

この設定は設定 › AIエージェント › このMacでのスクリプトにあります。

選択肢 VMPalの動作
許可(エージェントが確認) デフォルトです。VMPalは確認せずに許可します。エージェントには先にユーザに確認するよう伝えていますが、VMPalはそれを確かめられません。そのため、Mac上のどのアプリでも、この方法で自分のアカウントとしてコードを実行できてしまいます
VMPalで確認 VMPalがスクリプトの本文と実行場所を表示して確認します。確認はスクリプトのバージョンごとに1回です
オフ VMPalが拒否します

この設定は、VM内のスクリプトや、Hubで自分が行う操作には影響しません。

vmpalで操作する

vmpalはVMPalのコマンドラインツールで、dockerやghと同じように使えます。vmpal scriptコマンドで、Hubと同じことができます。

コマンド 動作
vmpal script create <name> --file <path> スクリプトを保存します。実行場所は、VMの新しいクローンなら--run-in <VM>、VM自体なら--run-in-place <VM>、このMacなら--hostで選びます
vmpal script run <script> --wait 今すぐ実行し、実行が終わるまで待ちます。終了コードで成功したかどうかがわかります
vmpal script log <script> 最新の実行の出力を表示します
vmpal script runs <script> 実行を、状態と失敗した理由とともに一覧表示します
vmpal script edit <script> 本文、設定、実行場所を変更します
vmpal script create "Build" --file build.sh --timeout 30m --run-in "Ubuntu"
vmpal script run "Build" --wait
vmpal script log "Build"

そのほかのコマンドはコマンド一覧をご覧ください。AIエージェントは、vmpal_create_script、vmpal_run_script、vmpal_get_run_logなどのVMPalのMCPツールで同じことを行います。そのためには、このMacのコーディングエージェントによるすべての仮想マシンの管理を許可をオンにする必要があります。