Claude CodeのCerebriumプラグインでサーバーレスGPUにデプロイする

Cerebriumプラグインは、Claude CodeにCerebrium向けのskill 1本と、ドキュメント検索用のホスト型MCPサーバーを足します。Cerebriumは、REST・ストリーミング・WebSocket・非同期のエンドポイントとして、PythonのAIワークロードをサーバーレスのGPUまたはCPUで動かすプラットフォームです。この記事は、プラグインの中身、導入とCLI認証、cerebrium.tomlで事故になりやすい箇所、そしてデプロイ前に必ず確認を挟む権限設定を順に扱います。

Cerebriumプラグインに入っているもの

マーケットプレイスのページには「Anthropic verified」と表示され、提供元のCerebrium自身が公開するプラグインとして載っています。入っているのは次の2つです。

skillが段階的に読まれる点が設計の肝です。本体にはワークフロー、安全のための規則、エンドポイントの形がまとまっています。細部は参照ファイルに分かれ、該当する作業のときだけ読み込まれます。

MCPが公開するツールはsearch_cerebrium、query_docs_filesystem_cerebrium、submit_feedbackの3つです。MCPの宣言が.mcp.jsonとルートのmcp.jsonの2か所にあるのは、前者がClaude Codeの慣習、後者がAgent Pluginsの標準が要求するパスだからだとリポジトリは説明しています。プラグインに同梱したMCPが接続される仕組みは、プラグイン同梱のMCPサーバーの解説にあります。

導入とCLI認証の手順

導入は2段階です。まずClaude Code側にプラグインを入れ、次にCerebrium側のアカウントとCLIを用意します。

Claude Codeのセッション内では、次のコマンドを実行します。

/plugin marketplace add CerebriumAI/cerebrium-skills
/plugin install cerebrium@cerebrium

/plugin installはセッション内では即時にインストールせず、プラグインの詳細を開く/pluginパネルに移ります。そこで内容を確かめ、スコープを選びます。シェルから入れたいときは、claude plugin install cerebrium@cerebriumの形も使えます。

CLIの準備はシェルで行います。

pip install cerebrium          # または brew tap cerebriumai/tap && brew install cerebrium
cerebrium login                # ブラウザが開く対話式
cerebrium projects current     # 認証とプロジェクトの確認

cerebrium loginはブラウザを開く対話式で、TTYの無い環境では失敗します。CIなどでは、ダッシュボードのAPIキー画面で作ったサービスアカウントのトークンをCEREBRIUM_SERVICE_ACCOUNT_TOKENに設定します。課金は秒単位で、現在の料金と付与クレジットは料金ページで確かめます。

プラグインを使わず、npx skills add CerebriumAI/cerebrium-skills -g -yとnpx add-mcp https://cerebrium.ai/docs/mcp -n cerebrium-docs -g -yで、検出された全エージェントに入れる方法もあります。前者の1コマンドはClaude Code以外のエージェントにも同時に入ります。

まず依頼してみる3つの文面

リポジトリのREADMEは、次のような依頼文を試す例として挙げています。

• FastAPIアプリをH100で、認証を有効にしてCerebriumへデプロイし、ログを追う
• 負荷時にリクエストが詰まるアプリの原因を調べ、設定を直す
• 13BのvLLMモデルに合うGPUとリージョン、cerebrium.tomlを決める

どの文面でも、skillはcerebrium関連のタスクとして自動で読み込まれます。skillの中身を知っておくと、Claudeが何を根拠に動くかを読み取れます。

cerebrium.tomlで事故になりやすい3点

skillが繰り返し強調するのは、設定ファイルの扱いです。

書かなかったキーは、既定値に戻る

cerebrium deployはアプリのレコード全体を置き換えます。以前のデプロイやcerebrium apps scaleでmax_replicas = 20にしていても、デプロイするcerebrium.tomlにそのキーが無ければ、1に戻ります。重要な値はすべてファイルに残します。

綴りを間違えたキーは、CLIでは拒否されません。ファイルはそのままアップロードされるので、バックエンドが拒否することもあれば、無視されることもあります。デプロイが通ったことを、綴りが正しい証拠にはできません。

認証と同時実行数の既定値

cerebrium initが出す雛形はdisable_auth = trueで、エンドポイントが公開状態になります。最初のcurlを通すための便宜であり、本番の既定値ではありません。実運用ではfalseにします。

max_replicasの既定値は1です。リクエストが詰まる原因として最も多く、GPUではreplica_concurrencyも1が既定です。負荷をかける前に、想定トラフィックに合わせます。

GPUの識別子とプランの上限

computeに書けるのは13個の識別子だけです。BLACKWELL_B300は公開のGPU表に載っていても、受け付けられる集合には入っていません。さらにプランの上限が先に効きます。Hobbyはgpu_countが1まで、A100やH100などは最低でもStandardプランが要ります。設定が正しく見えても拒否されるときは、プランを疑います。

可用性を上げる手として、computeに最大5個までの優先順リストを書けます。

[cerebrium.hardware]
compute = ["HOPPER_H100", "AMPERE_A100_80GB", "ADA_L40"]
gpu_count = 1
cpu = 8
memory = 32.0

リストの各要素は同じハードウェア系統に限ります。1組のcpu・memory・gpu_countが全要素の上限を満たす必要があるので、最も厳しい要素が天井を決めます。上の例ではADA_L40の影響で、メモリはGPUあたり92GBが上限です。VRAM 80GBが要るモデルをADA_L40を含むリストに載せるのは誤りです。また、cerebrium runは先頭の要素しか使いません。

デプロイ前の点検に使える最小構成は、skillの参照ファイルにある実例が近い形です。公式の例に沿った形で書くと、次のようになります。

[cerebrium.deployment]
name = "llm-inference"
python_version = "3.12"
disable_auth = false
use_uv = true
 
[cerebrium.hardware]
compute = ["HOPPER_H100", "AMPERE_A100_80GB"]
gpu_count = 1
cpu = 8
memory = 32.0
 
[cerebrium.scaling]
min_replicas = 0
max_replicas = 10
replica_concurrency = 1
compute_tier = "protected"
 
[cerebrium.dependencies.pip]
vllm = "latest"

min_replicas = 0ならアイドル時に課金されませんが、コールドスタートが発生します。compute_tierの既定はinterruptibleのスポット容量で、安い代わりに、レプリカが回収されることがあります。レイテンシに厳しい用途や長時間の処理はprotectedに切り替えます。

デプロイ前に確認を挟む権限設定

skillの規則の1番目は「デプロイは金がかかる」です。cerebrium deploy・cerebrium run・cerebrium apps scaleは課金対象の計算資源を起動し、cerebrium apps deleteは破壊的です。skillはClaudeに、セッション内の最初の1回の前に、何をどのハードウェアで動かすかを伝えて確認を取るよう求めています。

この確認を、skillの文言頼みにせず権限ルールでも固定できます。Claude Codeの権限は、deny、ask、allowの順に評価され、最初に一致した結果が採用されます。.claude/settings.jsonに、課金と削除に関わるコマンドをaskとして書いておきます。

{
  "permissions": {
    "ask": [
      "Bash(cerebrium deploy *)",
      "Bash(cerebrium run *)",
      "Bash(cerebrium apps scale *)",
      "Bash(cerebrium apps delete *)"
    ]
  }
}

注意点があります。Bashのルールは、Claudeが書いたコマンド文字列に一致するものです。同じプログラムを別の形で呼び出すと一致しないので、askルールは「通常の形を止める」ものであり、セキュリティ境界ではありません。確実に防ぎたい操作は、CI側のサービスアカウントの権限やプロジェクトの分離と組み合わせます。skillも、開発用と本番用でプロジェクトを分け、パイプラインが稼働中のアプリを上書きしないようにすることを勧めています。

読み取り系のcerebrium apps list・cerebrium apps get・cerebrium logs・cerebrium statusは課金を伴わないので、allowに入れて構いません。

動かないときの切り分け順

skillが示す診断は端末だけで完結します。順番は次のとおりです。

1. cerebrium apps get APP_IDで、実際に効いている設定を見る
2. ローカルのcerebrium.tomlと突き合わせる。apps scaleで変えた値や、巻き戻った値がここで見つかる
3. cerebrium logs APP_NAMEで実行時のログを読む
4. cerebrium containers listで、コンテナの状態を確かめる
5. cerebrium statusで、コードより先にプラットフォーム障害を疑う

ビルドログはcerebrium logsには出ません。cerebrium deployの実行中にだけ流れるので、--detachや--disable-build-logsを付けて失敗した場合は、付けずにもう一度デプロイして原因を読みます。

症状別の原因は次のとおりです。

リージョンの注意があります。eu-north-1(ストックホルム)とeu-north1(フィンランド、provider = "nebius"が必要)は別物です。同じくus-east-1とus-central1も別のリージョンです。GPUの種類もリージョンごとに違うため、固定する前に表で確かめます。

コールドスタートは、重みを/persistent-storageに置く、初期化をモジュールスコープで1回だけ行う、の順で手を打ちます。常時ウォームを保つmin_replicasやscaling_bufferは継続的に課金されるので、最後に検討します。

同じ系統のデプロイ系プラグインとの違い

クラウドのデプロイを任せる記事は他にもあります。Deploy on AWSプラグインは構成提案から見積もり、IaCでのデプロイまでを扱います。Appwriteプラグインは、FunctionsとSitesのデプロイ用コマンドを持ちます。

Cerebriumプラグインの特徴は、コマンドを持たずskillだけでCLI操作を導く点です。スラッシュコマンドは追加されず、デプロイの手順はskillの本体と参照ファイルが担います。skillの仕組みそのものはSkillsの解説にまとまっています。

よくある質問

Claude Code以外でも使えますか

使えます。リポジトリはCodex、Gemini CLI、Cursorなど、Agent Skills形式を読む環境向けのメタデータも同梱しています。Gemini CLIは拡張機能として1コマンドで入り、Cursorはリポジトリをそのまま読み込みます。

アカウントが無くてもskillは動きますか

skillはCLIの操作を導く文書なので、実際にcerebrium runやcerebrium deployを動かすにはアカウントとログインが要ります。cerebrium runはローカルのエミュレータではなく、作業ディレクトリをアップロードして、cerebrium.tomlに書いたハードウェアで実行されます。

設定のキーをClaudeが誤って作ることはありませんか

skillはキーやGPU識別子を創作しないよう指示し、許容値を参照ファイルに持たせています。実際の挙動が気になるときは、デプロイ前にcerebrium.tomlを目で確かめてから、確認の許可を出します。