クイックスタート

Organization は請求とアイデンティティの境界です。作成時は Free plan から始まり、試用のための 500 SC が付与されます — 有料 plan で何が増えるか、どう申し込むかは Plan と請求 を参照してください。

subako cloud signup --org acme --name "Acme, Inc."

--org は organization の handle です。これが organization を識別するものであり、重複は許されず、URL にも現れ、organization が存在する限り変更できません。サインインの際に指定する名前でもあり — 次のステップの subako login --org acme も、それ以降のログインもすべて そうです — ずっと使い続けられるものを選んでください。--name は表示名にすぎず、こちらはいつでも変更できます。

このコマンドはローカルには何も保存しません。Organization が置かれる Core サーバー — 別のものを指定していなければ https://api.us.cloud.subako.ai — が表示され、次のステップではそこに サインインします。

サインインは OAuth のデバイス認可フローで行われます。CLI がコードを表示してブラウザを開き、承認すると credential が ~/.config/subako/credentials.json に保存されます。

subako login --org acme

--profile を使うと、organization の handle とは別の名前でログインを保存できます — 複数の organization や、ステージングと本番のログインを並べて持つ方法です。--server は、既定の https://api.us.cloud.subako.ai 以外の Core サーバーにログインを向けます。保存された各 profile がどのサーバーに紐づいているかは subako profile list が表示します。

subako whoami

あらゆる作業単位は workspace に属します — agent、skill、vault、API key、そしてそれらが動かす session です。use は選択内容を profile に記録するので、以降のコマンドに --workspace フラグは要りません。

subako workspace create --name production
subako workspace use production
subako workspace list

Subako はあなたに代わってモデルを呼び出すため、version は provider を指定して公開します。どの workspace も最初から platform provider が見えています — こちらで設定済みで、あなた自身のキーは不要なので、まず はここから始めてください。

subako model-provider list

workspace: production (01a0877c-03d9-7823-b997-f42147b8b607)
01a07f90-238c-7de3-b55e-6fe53de063cf  type=platform  format=openai_responses  label=Subako  description=(none)
  model=crow  label=Crow
  model=hawk  label=Hawk
  model=sparrow  label=Sparrow

自前のものを何も作っていない workspace には、ちょうどこれだけが見えます — Subako の platform provider と、それが提供する 3 つのモデルです。クイックスタートを終えるにはこれで十分で、自分で作った provider はこの横に並びます。

この一覧から 2 つを控えておいてください。公開先となる provider の id と、その下にインデントされている モデル id のいずれかです。provider がどのモデル id を受け付けるかは、この一覧が正解です。

自分のアカウントで動かしたい場合は、自前の provider を作成します。キーはフラグではなく必ず標準入力から読まれるので、シェルの 履歴にもプロセス一覧にも残りません。

subako model-provider create \
  --format anthropic \
  --display-name "Anthropic production" \
  --base-url https://api.anthropic.com < key.txt

subako model-provider formats は、このサーバーが受け付ける format を一覧します。Agent version は、その model が話す format と一致する format の provider に対してのみ公開できます。

Agent は名前とアイデンティティにすぎません。設定そのものは持たず — それを持つのは version です。

subako agent create --name support-triage

Agent id が表示されます。これが agent publish に渡す引数です。あとから見直すには subako agent list を使います。

agent config-example は、そのままで公開できる最小の設定を表示します。 サーバーを必要としないので、ほかに何も存在しないうちから編集を始められます。

例は format ごとに異なるので、選んだ provider の format を渡してください。

subako agent config-example --format openai_responses > agent.json

{
  "system_prompt": "You are a helpful assistant.",
  "model": {
    "format": "openai_responses",
    "model": "your-model-id",
    "max_tokens": 8192,
    "context_window": 128000
  }
}

your-model-id を、provider の一覧にあるモデル id — たとえば hawk — に置き換えます。id は公開時ではなく session の実行時に検証されるので、本物をここに書いてください。

Grant — MCP サーバーと skill — は任意で、同じドキュメントに書きます。 provider はファイルではなく、公開時の --model-provider で指定します。

subako agent publish <agent-id> \
  --config agent.json \
  --model-provider <provider-id>

Version はイミュータブルです。もう一度公開すると新しい version が作られ、新しい session は最新の live version に束縛されます。すでに動いている session は、束縛済みの version のままです。

API key は、あなたのプロダクトが名乗るマシン用の credential です。そのシークレットは一度だけ表示され、二度と取得できません。

subako api-key mint \
  --label "support-triage backend" \
  --permission session.create \
  --permission session.read \
  --permission session.manage

minted api key support-triage backend (01a0877e-…) in workspace production (01a0877c-…)
permissions: session.create, session.read, session.manage
expires: (never)
prefix: sbk_ak_4f50c2aa
the secret below is shown once and cannot be retrieved again:
sbk_ak_4f50c2aa8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

最後の行 — sbk_ak_… のシークレット全体 — をコピーしてください。prefix ではありません。あれは api-key list でキーを見分けるためのラベルです。 以降の呼び出しは SUBAKO_API_KEY から読むので、いま入れておきます。

export SUBAKO_API_KEY=sbk_ak_4f50c2aa8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

これは curl の例のために、あなた自身が用意するシェル変数です。CLI がこれを読むことはありません — subako は API key ではなく、subako login で保存されたログインで認証します。

このサーバーがキーに与えられる権限は subako api-key permissions が一覧します。動作する範囲でもっとも狭い組み合わせを与えてください — Permission を参照。

curl -X POST https://api.us.cloud.subako.ai/v1/sessions \
  -H "Authorization: Bearer $SUBAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<agent-id>", "display_name": "ticket-4192"}'

{
  "id": "01a0877f-d3b3-7e73-9eed-a16caee8cff7",
  "status": "idle",
  "session_token": "sbk_st_...",
  "session_token_expires_at": "2026-09-09T19:48:16Z"
}

session_token はこの session ひとつに限定された credential で、permission は何も持たず、一度だけ表示されます。ブラウザのタブに渡すの はこれで、API key はサーバー側に置いたままにします。session_token_expires_at で失効するので、追加分は API key を使って POST /v1/sessions/{session_id}/tokens から発行します。

残り 2 つのステップでは session の id とこのトークンが必要になるので、どちらも控えておいてください — これもあなた自身のシェル変数です。

export SESSION_ID=<the id from the response>
export SUBAKO_SESSION_TOKEN=<the session_token from the response>

どの呼び出しがどちらの credential を取るかに注意してください。session の作成は API key の仕事で、session の中で起きることはすべて session token の仕事です。

ユーザーのターンを追記すると run が始まります。

curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "input", "text": "Summarize ticket 4192."}'

応答には、これによって始まった run が示されます。

{ "run_id": "01a08780-611d-7290-a9a0-e8a27b64ad9c", "outcome": "new_run" }

ストリームはログの先頭から追尾するので、すでに終わった run には送るものが残っていません。after_seq=0 を渡すと、session を最初の event から再生したうえで、そのままライブに続きます。

curl -N "https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN"

Event は SSE として届き、それぞれに再接続の再開点となるシーケンス番号が 付いています。Run は run_completed、run_failed、run_cancelled のいずれかで終わりです。

id: 2
event: message_user
data: {"seq":2,"type":"message_user",...}

id: 5
event: message_assistant
data: {"seq":5,"type":"message_assistant",...}

id: 6
event: run_completed
data: {"seq":6,"type":"run_completed","run_id":"01a08780-..."}

そのあともストリームは次の run を待って開いたままになります — curl は自分では終了しないので、run_completed を見たら中断してください。