クラウド GPU の起動時にセットアップスクリプトを実行するには？

結論： https://cloudgpu.app/deploy で Raw GPU を注文するときに Startup script (optional) を開いて bash スクリプトを貼り付けます。REST API では POST /v1/gpu/instances の setup_script として送ります。CloudGPU はインスタンスの引き渡し後に、そのスクリプトをバックグラウンドで root として 1 回実行するので、実行中も SSH でログインできます。出力は /root/cloudgpu-setup.log に書かれ、スクリプトは /root/cloudgpu-setup.sh に保存されます。上限は 16 KB で、それより大きい場合はスクリプトから自分のリポジトリを git clone してください（/deploy と API ドキュメント、2026-11-03 閲覧）。

スタートアップスクリプトの仕様
言語 bash
実行ユーザー root
実行 インスタンスの引き渡し後、バックグラウンドで 1 回
実行中 SSH でログインでき、JupyterLab も使えます
ログ /root/cloudgpu-setup.log
保存されるコピー /root/cloudgpu-setup.sh
サイズの上限 16 KB（/deploy の入力欄は 16,384 文字までカウント）
設定する場所 /deploy → Raw GPU → Startup script (optional)、または REST API の setup_script

インスタンスを破棄するとデータは削除されるため、次のインスタンスで同じパッケージ、同じモデル、同じリポジトリの環境を取り戻すには、スタートアップスクリプトが手軽な方法です。

ステップ 1：スクリプトを書く

strict モードとマーカーファイルを使うと、最後まで終わったかどうか、どこで止まったかがわかります：

#!/usr/bin/env bash
set -euxo pipefail                      # stop on the first error and echo each command into the log
cd /root

# 1) packages
apt-get update && apt-get install -y tmux aria2
pip install -U uv "huggingface_hub"

# 2) your code
git clone --depth 1 https://github.com/<you>/<project>.git /root/project

# 3) models (public repo; see the token note below for gated ones)
export HF_XET_HIGH_PERFORMANCE=1
hf download Qwen/Qwen2.5-7B-Instruct --local-dir /root/models/qwen2.5-7b-instruct

touch /root/SETUP_DONE                  # marker: everything above succeeded

ヒント：

  • スクリプトは短くし、残りはリポジトリに移します。 16 KB を超える場合は、リポジトリをクローンしてスクリプトから bash /root/project/setup.sh を実行します。
  • 絶対パスを使います。 カレントフォルダーに頼らず、/root/... に書き込みます。
  • 大きなダウンロードの前にパッケージをインストールします。 システム Python がインストールを拒否する場合は、Python パッケージを仮想環境に入れます（uv venv /root/env && . /root/env/bin/activate）。
  • 常駐させるサービス： スクリプトの終了後も動き続けるよう tmux で起動します。たとえば tmux new -d -s app 'bash /root/project/serve.sh'。

ステップ 2：/deploy で注文時に追加する

  1. /deploy を開き、Raw GPU とカードを選びます。
  2. Startup script (optional) を開いてスクリプトを貼り付けます。カウンターで 16,384 文字のうちどれだけ使っているかがわかります。
  3. デプロイします。インスタンスの行に SSH の情報が表示されたら、スクリプトの実行中でもログインできます。

ステップ 3：または REST API で送る

POST /v1/gpu/instances は、gpu_model、テンプレート、自動停止の上限 max_minutes、max_spend_usd、idle_minutes と一緒に setup_script を受け付けます（API ドキュメント、2026-11-03 閲覧）。jq を使うと、ローカルファイルを正しくエスケープされた JSON 文字列にできます：

jq -n --rawfile s setup.sh \
  '{gpu_model: "RTX 4090", max_minutes: 120, max_spend_usd: 2, idle_minutes: 30, setup_script: $s}' \
| curl -sS -X POST https://cloudgpu.app/v1/gpu/instances \
    -H "Authorization: Bearer $CLOUDGPU_API_KEY" \
    -H "Content-Type: application/json" -d @-

呼び出しはステータス creating で 202 を返します。ステータスが running になるまで GET /v1/gpu/instances/{id} をポーリングすると、SSH のホスト、ポート、パスワードが入ります。gpu_model には "auto" も指定でき、その場合はリクエストを実行できる利用可能な GPU を CloudGPU が選びます。素の GPU ではなくテンプレートを使いたい場合は、GET /v1/gpu/templates でテンプレート ID を一覧できます。AI コーディングアシスタント向けには、同じ API を CloudGPU MCP サーバー（npx -y cloudgpu-mcp）が提供しています。

ステップ 4：ログを見て結果を確認する

tail -f /root/cloudgpu-setup.log          # Ctrl-C stops following, not the script
ls /root/SETUP_DONE && echo "setup finished"
ps aux | grep -v grep | grep cloudgpu-setup   # still running?

スクリプトが失敗した場合は、ログの最後の数行に止まったコマンドが表示されます（set -x はそのためです）。コマンドを直してから、保存されたコピーを手動で実行します。自動で実行されるのは 1 回だけです：

bash /root/cloudgpu-setup.sh 2>&1 | tee -a /root/cloudgpu-setup.log

2 回実行しても問題が起きないように書いておきましょう。hf download は完了済みのファイルをスキップしますが、git clone は既存のフォルダーへは失敗するので、[ -d /root/project ] || git clone ... のようにガードします。

シークレットとトークン

スクリプトはインスタンス上の /root/cloudgpu-setup.sh に保存され、echo した内容はログに残ります。長期間有効なシークレットは入れないでください。ゲート付きの Hugging Face モデルを使う場合は、インスタンスの準備ができてからログインして（read -rs HF_TOKEN && export HF_TOKEN）ダウンロードするか、セッション後に無効化する fine-grained の読み取り専用トークンを使います。シークレットを使う行の前後では set -x をオフにし（set +x … set -x）、ログに出力されないようにしてください。

課金

インスタンスはスクリプトの実行中もその後も、1 分単位（切り上げ）、最低 1 分で課金され、インスタンスを破棄すると課金は止まります。API の上限 max_minutes、max_spend_usd、idle_minutes は、クライアントの接続が切れても CloudGPU のサーバーが適用します。

よくある質問

CloudGPU のスタートアップスクリプトはいつ実行されますか？

インスタンスがあなたに引き渡された後、バックグラウンドで root として 1 回実行されます。実行中も SSH でログインできます。

スタートアップスクリプトの出力はどこにありますか？

インスタンス上の /root/cloudgpu-setup.log にあります。スクリプト自体は /root/cloudgpu-setup.sh に保存されます。

スタートアップスクリプトの大きさの上限は？

16 KB までです。それより大きい場合は、スクリプトからリポジトリを git clone し、リポジトリ内のスクリプトを実行してください。

API でスタートアップスクリプトを設定できますか？

はい。POST /v1/gpu/instances で setup_script（bash、16 KB まで）として送ります。gpu_model や、max_minutes、max_spend_usd、idle_minutes などの任意の上限と一緒に指定できます。

手動でもう一度実行できますか？

自動で実行されるのは 1 回だけです。保存されたコピーは bash /root/cloudgpu-setup.sh で自分で実行できます。2 回目の実行でも問題が起きないように書いておきましょう。

出典（2026-11-03 閲覧、Asia/Shanghai）

  • CloudGPU /deploy の Raw GPU パネル（“Runs once as root after the machine is handed over, in the background; you can SSH in while it runs. Output goes to /root/cloudgpu-setup.log and the script is saved at /root/cloudgpu-setup.sh. Up to 16 KB”）：https://cloudgpu.app/deploy
  • CloudGPU API ドキュメントの GPU インスタンス（setup_script、max_minutes、max_spend_usd、idle_minutes、202 creating、ポーリング）：https://cloudgpu.app/api/docs#gpu
  • CloudGPU MCP サーバー：https://cloudgpu.app/docs/mcp
  • jq マニュアル（–rawfile）：https://jqlang.org/manual/

起動できるカードは Deploy ページに一覧があります。料金は https://cloudgpu.app/ja/pricing に掲載しており、ここでは繰り返しません。

最終更新：2026-11-03（Asia/Shanghai）。