colab-operator

スキル：Colab セッションオペレーター

colab CLI を使用して Google Colab 環境を操作します。GPU／TPU セッションのプロビジョニング、VM 上での Python／シェルの実行、ファイルの同期、作業内容のノートブックへの記録を行います。

インストール

ユーザーが colab ツールをまだインストールしていない場合は、uv tool install google-colab-cli または pip install google-colab-cli を実行してインストールできます。

有効にするタイミング

• TPU／GPU セッションの作成または管理。
• リモート Colab VM での Python またはシェルの実行。
• ローカルとリモート間でのファイル同期。
• 環境セットアップ（パッケージ、認証、Drive）の自動化。
• セッション履歴の Jupyter ノートブックへのエクスポート。

基本的な考え方（最初にお読みください）

• セッションは、レンタルした VM 上で稼働する Jupyter カーネルです。 colab new は課金対象の VM を割り当て、colab stop は VM を解放します。カーネルがアクティブである限りセッションは維持され、Colab バックエンドが自動的に稼働状態を保ちます。
• 同じセッション内では、カーネルの状態が colab exec／colab repl の呼び出しをまたいで維持されます。 呼び出しのたびに同じカーネル（カーネル ID はローカル状態にキャッシュされます）へ再接続し、終了時には WebSocket を閉じるだけです。カーネルは停止しません。そのため、インポートしたモジュール、変数、定義した関数は、別々の colab exec コマンド間でも保持されます。状態は段階的に構築し、呼び出しごとにすべてを再インポートしないでください。（実際にリセットするのは colab stop と colab restart-kernel です。）
• デフォルトの作業ディレクトリは /content です。 すべての exec／repl／run は、最初にこのディレクトリへ cd します。ファイル操作には絶対パス（/content/...）を使用してください。colab ls/rm/upload/download では絶対パスの /content/... が使用でき、ls のデフォルトパスは content（VM のルート）です。
• colab は実行して終了する方式です。 各コマンドは認証を行い、処理を 1 つ実行して終了します。

認証（エージェントの動作を妨げる最大の要因）

• グローバルフラグは --auth={adc,oauth2} で、デフォルトは adc（Application Default Credentials）です。サブコマンドより前に指定する必要があります。例：colab --auth=adc new -s x。
• ADC のセットアップ（ヘッドレス環境やエージェントで最も確実です）。Colab バックエンドには特定のスコープの組み合わせが必要なため、次の 4 つすべてのスコープを指定して ADC を再発行します。

  gcloud auth application-default login \
    --scopes=openid,\
  https://www.googleapis.com/auth/cloud-platform,\
  https://www.googleapis.com/auth/userinfo.email,\
  https://www.googleapis.com/auth/colaboratory
  

  4 つすべてが必要な理由：userinfo.email（セッションバックエンド colab.research.google.com 用。これがないと 401）、colaboratory（Colab の機能／API 用）、openid と cloud-platform（gcloud 自体が必須としており、cloud-platform を含まないスコープリストを拒否します）。
• oauth2 のセットアップ：初回使用時に colab --auth=oauth2 <anything> を実行すると、ブラウザーの同意フローが開始されます（トークンは ~/.config/colab-cli/token.json にキャッシュされます）。クライアント設定ファイル ~/.colab-cli-oauth-config.json（または -c PATH）が必要です。ブラウザーでの操作には通常、人間の対応が必要なため、エージェントには ADC を推奨します。
• 一度に認証を確認する：colab sessions（読み取り専用で、サーバーの割り当てを一覧表示）または colab whoami（非表示のデバッグコマンド。現在のメールアドレス、スコープ、オーディエンス、有効期限を表示）を実行します。呼び出しで 401 または 403 が返された場合、ほとんどの場合、原因は認証情報またはスコープの不足です。colab whoami で即座に確認できます。
• CLI の認証と colab auth を混同しないでください。 colab auth は、実行中のカーネルに VM 側の GCP 認証情報を渡します（ノートブックのコードから BigQuery／GCS を呼び出せるようにするためのものです）。CLI 自体の認証とは別のものです。CLI の 401／403 を解決するために「colab auth を実行してください」と案内してはいけません。問題はスコープまたは ID にあり、上記の gcloud コマンドで解決します。

ワークフロー

プロビジョニング

• colab new -s <name>（CPU）。アクセラレーターを使用するには、--gpu A100 または --tpu v6e1 を追加します。必ず -s <name> を指定してください。名前を省略するとランダムな6桁の16進数が自動生成され、後続のコマンドで指定が曖昧になります。
• 対応する --gpu：T4、L4、G4、H100、A100。対応する --tpu：v5e1、v6e1。
• 注意点：認識されない --gpu の値を指定すると、何も通知されずに A100 にフォールバックします（その後のステップで通常は失敗します）。アクセラレーターを指定した colab new が 400 を返す場合、このアカウントにはそのアクセラレーターを利用する割り当て量または権限がありません。--gpu T4 に切り替えるか、フラグを省略してCPUを使用してください。
• アクセラレーターの利用可否はプランによって異なり、ほとんどのアカウントで利用できるのはCPUのみです。GPU／TPUが割り当てられるとは限りません。

実行

• 推奨：colab exec -s <name> -f <script.py> は、ローカルのスクリプトをリモートVM上で実行します（ローカルで読み込んでカーネルに送信するため、手動でのアップロードは不要です）。
• パイプでコードを渡す：echo "print(1)" | colab exec -s <name> または cat script.py | colab exec -s <name>。
• ノートブック：colab exec -s <name> -f nb.ipynb は各コードセルを実行し、入力ファイルと同じ場所に <basename>_output.ipynb として結果を書き込みます。先頭行に # @title Foo を指定すると、実行状況の出力でセルにラベルが付けられます。
• プロット／画像：PNG／JPEGの出力は捕捉されます。既知の場所に保存するには、exec／repl で --output-image <path> を使用します（指定しない場合は一時パスが出力されます）。標準出力がTTYでない場合は、インラインのターミナル画像エスケープが自動的に抑制されるため、パイプ出力やキャプチャーした出力が汚れません。
• シェル：バッチシェルには echo "cmd" | colab console -s <name> を使用します。Consoleはbashをtmuxで実行するため、パイプ経由の出力にもターミナル制御バイトが含まれます。特定の行を抽出するには grep -a でフィルタリングしてください。通常のシェルが不要であれば、exec のほうが高速です。
• エージェントから colab repl、colab console、colab auth、colab drivemount を対話的に実行しないでください。TTYが必要なため、ハングします。repl／console はパイプ経由の標準入力を受け付け、EOFで終了します。auth／drivemount は実際にターミナル上で人間が操作する必要があります。

一時的な単発ジョブ（colab run）

• colab run [--gpu T4] [--tpu v6e1] [--keep] [-s NAME] script.py [args...] は、new + exec + stop を1つのコマンドで実行します。新しいVMをプロビジョニングし、ネイティブの python script.py args と同様に sys.argv と __name__ == "__main__" を設定してスクリプトを実行した後、VMを破棄します（--keep を指定した場合を除く）。
• 終了コードは引き継がれます：スクリプト内で例外が捕捉されない場合や sys.exit(N) が呼び出された場合、colab run はゼロ以外の終了コードで終了します（CPythonの仕様：sys.exit()／sys.exit(0) → 0、sys.exit(N) → N、sys.exit("msg") → 1）。
• ストリームの分離：colab run 自身の [colab] ... のメッセージは stderr に、スクリプトの出力は stdout に書き込みます。そのため、colab run job.py > out.txt ではスクリプトのstdoutのみがキャプチャされます（colab exec はスクリプトのstdout／stderrをライブで、それぞれstdout／stderrにストリームします）。
• シバンとして使用できます：#!/usr/bin/env -S colab run --gpu T4 を指定すると、chmod +x を実行した .py を、GPUを借りて実行し、後片付けを行う自己完結型のスクリプトにできます。CLIの動作を編集した後にシバンをテストする場合は、先に再インストールしてください。シバンは編集可能なインストールではなく、$PATH 経由で colab を解決するためです。
• 存在しないスクリプトパスを指定すると、VMを割り当てる前にゼロ以外の終了コードで終了します（計算リソースを無駄に消費しません）。

自動化

• colab auth -s <name> — VM上のGCP認証情報を設定します。VM内からGCS／BigQueryを呼び出す前に必要です（対話型のため、エージェントからは実行できません）。
• colab drivemount -s <name> [PATH] — Driveをデフォルトで /content/drive にマウントします（対話型のため、エージェントからは実行できません）。
• colab install -s <name> pkg1 pkg2 — uv pip install --system でインストールし、失敗した場合は pip にフォールバックします。colab install -s <name> -r requirements.txt も使用できます。

確認とレポート

• colab help（または colab help <cmd>）を実行すると、コマンドの一覧と説明が表示されます。一覧はアルファベット順です。
• colab sessions を実行すると、サーバー側の割り当てが一覧表示され、古いローカルエントリーは自動的に削除されます。ローカルの記録がない孤立したセッションは [?] と表示されます。
• colab status [-s <name>] を実行すると、ハードウェア、IDLE/BUSY、最後の実行が表示されます。
• colab log -s <name> [-n 20] [-t TYPE] を実行すると、最近の構造化イベントが表示されます。タスクが失敗した場合に非常に役立ちます。
• colab log -s <name> -o summary.ipynb を実行すると、セッションがノートブックとしてエクスポートされます（拡張子に応じて .md、.txt、.jsonl でもエクスポートできます）。
• colab url -s <name> を実行すると、新しい VM を割り当てる代わりに、既存の CLI セッションに Colab ウェブ UI を接続するブラウザー URL が表示されます（起動するには --open を追加します）。
• colab skill / colab readme を実行すると、このスキルと README が表示されます（自分で情報を確認するときに便利です）。

安全性

• 完了したら必ず colab stop -s <name> を実行してください — アイドル状態の VM はコンピューティングユニットを消費します。colab run（--keep を指定しない場合）は、スクリプトがエラーになっても自動的にクリーンアップします。
• ローカルの状態は ~/.config/colab-cli/sessions.json に保存されます（設定は settings.json、履歴は history/*.jsonl に保存されます）。手作業で編集しないでください。
• 並列実行やエージェントの実行は、グローバルな --config <path> フラグを使ってセッションの状態を一時ファイルに保存し、分離してください（例：colab --config /tmp/agent.json new -s job）。

復旧

• exec で「Session not found」／404／401 が発生した場合、バックエンドによって VM が削除されています。colab exec／repl はこれを検出し、ローカルの状態を自動的にクリーンアップします。colab sessions を実行し、colab new で再作成してください。
• 実行がタイムアウトした場合やカーネルが応答しなくなった場合は、colab restart-kernel -s <name> を実行します（VM は維持され、カーネルがリセットされます）。または、colab stop を実行してから colab new を実行してください。