cargo-hosting

Cargo CLI — ホスティング

Cargo Hosting では、ワークスペース単位のリソースを2種類と、それらを公開するデプロイを実行します。

• App — 専用のサブドメインで配信される静的なフロントエンドです（デフォルトは Vite のシングルページアプリです。Astro、Gatsby、Create React App、Parcel、Webpack も検出されます。また、Next.js、SvelteKit、Nuxt は独自の build スクリプトで動作します。詳しくは App のビルドをご覧ください）。URL については URL をご覧ください。テンプレートは @cargo-ai/app-sdk をベースに構築されています（Vite + refine + shadcn プリミティブ。getCargoEnv() / useCargoApi() はワークスペースに接続済みです）。
• Worker — エッジ上で実行されるサーバーレス HTTP ハンドラーです（fetch(request, env)）。@cargo-ai/worker-sdk をベースに構築されています（OpenAPI 3.1 仕様を /openapi.json に自動生成し、Swagger UI を /docs に表示します）。
• Deployment — ローカルのソースディレクトリを App または Worker にビルドしてアップロードします。デプロイはプロモートされるまで公開されません。

App／Worker をフォルダーに整理するには、cargo-workspace-management（folder …）を使用してください。ここで指定する --folder-uuid フラグには、そのフォルダーの UUID を指定します。

エンドツーエンドの手順については、references/examples/apps.md、references/examples/workers.md、references/examples/deployments.md をご覧ください。 JSON レスポンスの構造については、references/response-shapes.md をご覧ください。 よくあるエラーとその解決方法については、references/troubleshooting.md をご覧ください。

初期設定

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）は、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは JSON を標準出力に出力します。失敗した場合は、{"errorMessage": "..."} を返してゼロ以外の終了コードで終了します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を指定するか、対応する get コマンドで状態を確認してください。スキルバンドル全体をインストールすると、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンのスコープ、管理者専用の機能が追加されます。

ライフサイクル

App と Worker の流れは同じです。scaffold → スロットの作成 → デプロイ → プロモート：

init (local scaffold) → create (slot + slug) → deployment create (build+upload) → deployment promote (go live)

1. テンプレートからローカルプロジェクトをスキャフォールドします。hosting app init <dir> / hosting worker init <dir> を実行します。
2. ワークスペースにスロットを作成します。hosting app create --name --slug を実行すると appUuid（または workerUuid）が返されます。--slug はサブドメインの一部となり、ワークスペース内で一意である必要があります。
3. （任意）ローカル開発環境を接続します。App の場合は、hosting app env <appUuid> を実行すると、ローカルコピーに必要な .env.local の各行（Cargo OAuth + ワークスペース + App UUID + API URL）が出力されます。Worker の場合は、スキャフォールド内で npm run dev を実行します（Worker をローカルで実行するを参照）。Cargo API を呼び出す Worker では、初回デプロイ前に CARGO_API_TOKEN シークレットも必要です（Worker の環境変数とシークレットを参照）。
4. デプロイします。hosting deployment create --app-uuid <uuid> --source <dir> を実行すると、ソースがアップロードされます。その後、バックエンドがサンドボックス内でビルドします。App の場合は npm ci --ignore-scripts の後に App 独自の build スクリプトを実行します。スクリプトがない場合はフレームワークのデフォルトのビルドを実行します（App のビルドを参照）。Worker の場合はエントリーポイントをバンドルします。deploymentUuid が返されます。
5. プロモートします。hosting deployment promote --uuid <deploymentUuid> を実行すると、公開 URL がそのビルドを指すようになります。

デプロイのビルドは非同期で実行されます。プロモートする前に、ステータスが終端状態になるまで hosting deployment get <uuid> をポーリングしてください（非同期ポーリングを参照）。

URL

稼働中のホストは、ホスティングのルートドメイン配下の <slug>-<first 8 chars of the workspace UUID> です。アプリとワーカーではルートドメインが異なります。本番環境では、アプリは https://<slug>-<ws>.app.getcargo.run、ワーカーは https://<slug>-<ws>.worker.getcargo.run です。ワークスペースのサフィックスによってホストがグローバルに一意になるため、スラッグはワークスペース内で一意であれば十分です。

URLを手作業で組み立てないでください。ルートドメインは環境によって異なるため、create または get から url を読み取ってください。各デプロイには、昇格前にプレビュー用ホスト https://deployment-<deploymentUuid>.<root> も割り当てられます。

ルートドメインが異なるため、アプリからワーカーへの呼び出しは必ずクロスオリジンリクエストになります。 同一オリジンで提供する方法はないため、ワーカー側で CORS に応答する必要があります。references/examples/workers.md のアプリ＋ワーカーのパターンを参照してください。

アプリ

# Discover
cargo-ai hosting app list                          # all apps (filter with --folder-uuid <uuid>)
cargo-ai hosting app get <uuid>                     # one app's details + URL

# Scaffold locally (Vite + @cargo-ai/app-sdk)
cargo-ai hosting app init ./my-app --list-templates # see available templates, then:
cargo-ai hosting app init ./my-app --template blank --name "My App"

# Create the slot (slug unique per workspace; `url` in the response is the live host)
cargo-ai hosting app create --name "My App" --slug my-app --folder-uuid <folder-uuid>

# Print .env.local for local development
cargo-ai hosting app env <app-uuid>
cargo-ai hosting app env <app-uuid> --api-url https://api.getcargo.io

# App env vars (public build-time values; take effect on the next deploy + promote)
cargo-ai hosting app env-var list --app-uuid <app-uuid>
cargo-ai hosting app env-var set --app-uuid <app-uuid> --key VITE_LOG_LEVEL --value debug
cargo-ai hosting app env-var remove <env-var-uuid>                 # uuid from env-var list

# Update / remove
cargo-ai hosting app update --uuid <app-uuid> --name "Renamed"
cargo-ai hosting app update --uuid <app-uuid> --folder-uuid null   # move to workspace root
cargo-ai hosting app remove <app-uuid>                             # also removes its deployments

テンプレート：blank（最小限の開始用テンプレート）、territories-overview（useCargoApi() と react-query を紹介する読み取り専用のテリトリーグリッドのデモ）、public-site（独自のビルドスクリプトですべてのルートをプリレンダリングし、robots.txt と sitemap.xml を同梱する、公開されていてインデックス可能なサイト）。現在の一覧を表示するには、app init <dir> --list-templates を実行してください。

アプリのビルド

package.json に build スクリプトが宣言されている場合、Cargo はそれを実行し、そのスクリプトがビルド全体を担います。 Cargo はその前後に何も実行しないため、スクリプトはクライアントバンドルに加えて、プリレンダリングされた HTML などの追加ファイルも生成する必要があります。build スクリプトがない場合は、検出されたフレームワークのデフォルトコマンドが実行されます。

フレームワーク（依存関係から検出）	デフォルトのビルド	出力ディレクトリ
Vite、および検出されないもの	vite build	dist
Astro	astro build	dist
Gatsby	gatsby build	public
Create React App	react-scripts build	build
Parcel	parcel build	dist
Webpack	webpack build	dist

Next.js、SvelteKit、Nuxt は検出されません。その場合はデフォルトの dist にフォールバックするため、静的ファイルを dist/ に出力する build スクリプトを宣言してください。フレームワークにかかわらず、すべてのアプリにすべてのパブリック環境変数プレフィックスが渡されます（アプリの環境変数は公開されます を参照）。

• 出力は該当するフレームワークの出力ディレクトリに配置し、index.html を含める必要があります。 そうでない場合、ビルドは失敗します。不明なパスはそのシェルにフォールバックします。
• 現在ビルドスクリプトが行う処理は、デプロイのたびに実行されます。 tsc の実行、異なる --mode の指定、prebuild／postbuild フックも対象です。そこで失敗するスクリプトは、デプロイも失敗させます。昇格はビルドの成功後にのみ行われるため、稼働中のデプロイは引き続き提供されます。
• Cargo が利用できない build スクリプトは、警告なくフォールバックします。 解析できない package.json、空のスクリプト、文字列以外の値などが該当します。デプロイ自体は成功しますが、理由はビルドログにしか記録されないため、プリレンダリングの手順がスキップされたように見える場合はログを確認してください。
• プラットフォームの値はすべてのパブリックプレフィックスに設定されます。 Vite アプリでは VITE_CARGO_API_URL、Next.js アプリでは NEXT_PUBLIC_CARGO_API_URL を読み取ります。build スクリプトを使う場合、これらは実際のプロセス環境変数としても渡されるため、通常の Node.js によるプリレンダリング処理から参照できます。ユーザーの環境変数はビルドログで伏せられます。

アプリの環境変数は公開されます

アプリが読み込むのは、キーが公開プレフィックスで始まる環境変数のみです。対象は VITE_、NEXT_PUBLIC_、PUBLIC_、NUXT_PUBLIC_、GATSBY_、REACT_APP_ です。フレームワークに関係なく、これらのプレフィックスはどれでも使用できます。環境変数はワークスペースの環境変数と、アプリレベルのエントリー（hosting app env-var set、"kind":"app" を指定した POST /v1/hosting/env-vars、またはプロジェクト内の defineApp({ env })）から取得されます。同じキーがある場合、アプリのエントリーがワークスペースのエントリーを上書きします。いずれも、誰でもダウンロードできるバンドルにコンパイルされます。そのため、次の点に注意してください。

• アプリの環境変数にシークレットは設定できません。 API は isSecret: true を secretNotSupportedForApp エラーで拒否し、プロジェクトの defineApp は secret() の値を指定するとエラーをスローし、シークレットのワークスペースエントリーはアプリのビルドに渡されません。認証情報は、アプリが呼び出すワーカーに設定してください。hosting app env-var set --help には（アプリに CARGO_API_TOKEN を設定する）--secret の例が表示されますが、これは失敗します。 このフラグはワーカーコマンドと共通です。アプリではバックエンドが拒否するため、作成と更新のどちらも失敗します。
• いずれかのプレフィックスを付けても、プラットフォームキーに一致するキー（*_CARGO_API_URL、*_CARGO_WORKSPACE_UUID、*_APP_BASE_PATH、…）は予約されています。
• 値はビルド時に埋め込まれるため、変更するには新たにデプロイしてプロモートする必要があります。

カスタムドメインと検索インデックス登録

Cargo が所有するホストは noindex です。 デフォルトの *.app.getcargo.run ホストと、すべての deployment-<uuid> プレビューは X-Robots-Tag: noindex を返すため、アプリがインデックス登録されるのはカスタムドメイン上のみです。 CLI 1.0.96 ではカスタムドメインを割り当てる CLI コマンドがないため、API を使用してください。

CARGO_API_BASE=$(cargo-ai whoami | jq -r '.baseUrl')   # https://api.getcargo.io in production
curl -X POST "$CARGO_API_BASE/v1/hosting/custom-domains" \
  -H "authorization: Bearer $CARGO_API_TOKEN" -H "content-type: application/json" \
  -d '{"kind":"app","appUuid":"<uuid>","hostname":"www.example.com"}'
# → DNS records to add: certificate validation records + a cnameTarget for the hostname
curl -X POST "$CARGO_API_BASE/v1/hosting/custom-domains/<domain-uuid>/refresh-status" \
  -H "authorization: Bearer $CARGO_API_TOKEN"                                   # repeat until status is "active"

• ホスト名には少なくとも3つのラベルが必要です。そのため、example.com ではなく www.example.com を割り当ててください。
• ワーカーにもカスタムドメインを設定できます（"kind":"worker","workerUuid":…）。ホスト名が異なればオリジンも異なるため、アプリからワーカーへの CORS は引き続き適用されます。
• インデックス登録には、各 URL に実際の HTML も必要です。 build スクリプトでプリレンダリングしてください（public-site テンプレートを参考にしてください）。プリレンダリングしたルートには .html パスでリンクしてください。/about.html はプリレンダリングしたファイルを返しますが、/about は SPA シェルにフォールバックします。public/robots.txt と public/sitemap.xml を配置し、プリレンダリングした各ページの head にタイトル、説明、canonical、Open Graph のタグを設定してください。
• ホストされたアプリは 404 を返しません。 存在しないパスには 200 とともに SPA シェルが返されるため、クライアント側の not-found ビューで <meta name="robots" content="noindex"> を設定してください。
• CargoRefineApp 上に構築されたアプリには Cargo へのログインが必要で、インデックス登録できません。公開サイトでは独自のツリーをレンダリングします。
• 検索エンジンへの送信は自動では行われません。Search Console でサイトマップを送信してください。

ワーカー

アプリと同じ形式のコマンドを使用し、app を worker に置き換えてください。

cargo-ai hosting worker list                        # filter with --folder-uuid <uuid>
cargo-ai hosting worker get <uuid>

# Scaffold (edge fetch(request, env) handler on @cargo-ai/worker-sdk)
cargo-ai hosting worker init ./my-worker --list-templates
cargo-ai hosting worker init ./my-worker --template blank --name "My Worker"

cargo-ai hosting worker create --name "My Worker" --slug my-worker --folder-uuid <folder-uuid>
cargo-ai hosting worker update --uuid <worker-uuid> --name "Renamed"
cargo-ai hosting worker remove <worker-uuid>        # also removes its deployments

テンプレート：blank（OpenAPI 仕様と Swagger UI を自動生成）と custom-integration（Cargo Custom Integration — マニフェスト／アクション／エクストラクター／オートコンプリート／動的スキーマ）。

エントリーポイント。 ビルドでは、存在するファイルのうち src/index.ts、src/index.js、index.ts、index.js の順で最初のものをバンドルします。該当するファイルがない場合、ビルドは失敗します。.mjs、.mts、.cjs のエントリーポイントは認識されないため、.js／.ts に名前を変更してください。スキャフォールドの package.json で "type": "module" が設定されているため、.js でも ES モジュール構文を使用できます。

ワーカーの環境変数とシークレット

ワーカーは、c.env.KEY（Hono コンテキスト）または fetch(request, env) の env 引数から設定を読み取ります。次の 3 つのソースから設定が渡されます。

ソース	設定方法	適用先
プラットフォームバインディング	自動	CARGO_API_URL、CARGO_WORKSPACE_UUID、CARGO_WORKER_UUID
ワークスペース環境変数	cargo-ai workspaceManagement envVar create --key K [--secret]	ワークスペース内のすべてのワーカー（アプリには、公開プレフィックスが付いた非シークレットの変数のみが適用されます）
ワーカー環境変数	cargo-ai hosting worker env set --worker-uuid <uuid> --key K [--secret]、プロジェクトでの defineWorker({ env })、または POST /v1/hosting/env-vars	そのワーカーのみ。同じキーのワークスペース環境変数がある場合は、ワーカー側の設定が優先されます

CARGO_API_TOKEN はデフォルトでは注入されません。 トークンを設定するまで、createCargoApi(c.env) は Missing CARGO_API_TOKEN… をスローします。例外は、サービスユーザーが設定されたワーカー（hosting worker update --uuid <uuid> --run-as-user-uuid <service-user-uuid>、または defineWorker({ runAs })）です。この場合、環境変数にキーがすでに設定されていなければ、公開のたびに（プレビューのデプロイも含む）そのユーザー用の一時的な CARGO_API_TOKEN が新たに発行され、以前のトークンは取り消されます。worker create には --run-as-user-uuid がありません。update で設定してください。ユーザーは、あなたが持つ権限でカバーされる権限を持つサービスユーザーである必要があります（runAsUserNotFound / runAsUserNotPermitted）。作成方法については、../cargo-workspace-management/SKILL.md → 「Service users」を参照してください。それ以外の場合は、ワークスペース API トークンを発行し、初回デプロイ前にシークレットとして保存してください。

cargo-ai workspaceManagement token create --name "worker: my-worker"   # value shown ONCE
export CARGO_API_TOKEN=<token value>
cargo-ai workspaceManagement envVar create --key CARGO_API_TOKEN --secret \
  --description "Cargo API token for hosted workers"                     # --value omitted → read from $CARGO_API_TOKEN

ワークスペースの環境変数に設定すると、そのトークンはすべてのワーカーに適用されます。特定のワーカーだけに保持させる場合は、そのワーカーに設定してください。

• プロジェクト： defineWorker("my-worker", { path, env: { CARGO_API_TOKEN: secret("CARGO_API_TOKEN") } })。
• CLI： printf %s "$CARGO_API_TOKEN" | cargo-ai hosting worker env set --worker-uuid <uuid> --key CARGO_API_TOKEN --value - --secret（シェルから $CARGO_API_TOKEN を読み取るには、--value を省略します）。hosting worker env list --worker-uuid <uuid> ではキーが表示され、シークレットの値は null として表示されます。hosting worker env remove <env-var-uuid> で変数を削除します（uuid は env list で確認できます）。変更は次回のデプロイとプロモート後に反映されます。
• API： {"kind":"worker","workerUuid":"<uuid>","key":"CARGO_API_TOKEN","value":"…","isSecret":true} を指定して POST /v1/hosting/env-vars を呼び出します。TypeScript では、これは @cargo-ai/api の api.hosting.envVars.create(…) に相当し、list には { workerUuid } を渡します。

値はデプロイ時に取得され、リアルタイムには読み取られません。 バインディングはデプロイがプロモートされた時点で適用され、非シークレットの値は process.env.KEY としてバンドルにもコンパイルされます。変数の追加や変更後は、deployment create と promote を再度実行してください。 それまでは、実行中のワーカーには古い値が適用されます。

シークレットがバンドルに含まれることはありません。 シークレットは、暗号化されたランタイム値としてバインドされます。コンパイルされるのは非シークレットの値のみで、バンドルはデプロイごとのプレビュー用ホストからダウンロードできるため、機密情報は必ず --secret / isSecret: true を指定してください。

ワーカーをローカルで実行する

どちらのテンプレートにも dev.ts のハーネスが含まれています。npm run dev を実行すると、Node 上で src/index.ts がホットリロード付きで http://localhost:8787 に配信されます（PORT で変更できます）。dev.ts がデプロイされることはありません。

• ローカルにはプラットフォームバインディングが存在しないため、 c.env は空です。createCargoApi は process.env にフォールバックするため、npm run dev の前にシェルで CARGO_API_TOKEN（本番以外の API の場合は CARGO_API_URL も）をエクスポートしてください。独自の変数も、コード内で同じフォールバックが必要です。
• manifest.json の outboundAllowlist と cron トリガーはローカルでは適用されません。 デプロイ上でテストしてください。

dev.ts が存在する前にスキャフォールドされたプロジェクトでは、新しい hosting worker init から dev.ts と dev スクリプト、および開発用依存関係の @hono/node-server と tsx をコピーできます。

ワーカーからのファイルの保存

@cargo-ai/worker-sdk の createCargoObjects(env) は、createCargoApi と同じ CARGO_API_TOKEN を使用して、ワークスペースのコンテンツファイルをパスで読み書きします。

import { createCargoObjects } from "@cargo-ai/worker-sdk";

const objects = createCargoObjects(c.env);
await objects.put("decks/acme.pdf", pdfBytes, { contentType: "application/pdf" }); // ≤ 100 MB; overwrites in place
const { url } = await objects.url("decks/acme.pdf", { expiresInSeconds: 3600 });    // signed, no auth needed to open

また、get(path) → Blob、stat(path)、list({ prefix, cursor, limit })、remove(path)、setVisibility(path, "public" | "private") も使用できます。新しいファイルは非公開で、エージェント検索の対象にはならず、put に indexMode / visibility / mirrorToContext を渡さない限り、コンテキストリポジトリにもミラーされません。署名付き url（最長 3 時間）または公開ファイルの安定したリンクは認証なしで開けます。呼び出し元にそのファイルを渡してよい場合にのみ、リンクを返してください。パスのモデルとデフォルト値については、../cargo-content/references/objects.md を参照してください。

ワーカーのログとエラー

createWorker() は、Cargo がディスパッチする各リクエスト中の console.log/info/warn/error/debug を取得し、ワーカーのログに送信します（リクエストあたり最大 50 行）。捕捉されなかったエラーはスタックトレースとともに記録され、本文のない 500 が返されます。

捕捉されたエラーは記録されません。 ルートで例外を捕捉し、502 "The data provider is unavailable" のようなサニタイズ済みのレスポンスを返した場合、ログに残るのは HTTP 行のみです。サニタイズする前にエラーをログに記録してください。

try {
  return c.json(await loadData(createCargoApi(c.env)));
} catch (err) {
  console.error(err);                        // stack goes to the logs; the response stays clean
  return c.json({ error: "The data provider is unavailable." }, 502);
}

すべてのワーカー呼び出し（cron または受信 HTTP）は nodeKind: "worker" のスパンにもなり、上流でトレースが開始されていない場合はトレースを開始します。ワーカー全体から失敗した呼び出しを探すには、cargo-ai orchestration span list --node-kind worker --execution-statuses error --execution-started-after <iso> を実行します（各呼び出しには、logs list --run-uuid で使用する runUuid が含まれます）。また、特定の呼び出しによって何が起きたかは、orchestration trace get <traceUuid> で確認できます。CLI の trace list にはワーカーフィルターがありません。API の POST /v1/orchestration/traces/list では workerUuid を指定できます。運用手順書については、../cargo-diagnostics/SKILL.md を参照してください。

cargo-ai hosting worker logs list --worker-uuid <uuid> --levels error --limit 50 でログを読み取れます（新しい順。--run-uuid、--search、--occurred-after / --occurred-before、logs count、logs get <logUuid> --worker-uuid <uuid> も指定できます）。ウェブアプリまたは API からも確認できます。API の場合は、{"workerUuid":"<uuid>","levels":["error"],"limit":50} を指定して POST /v1/hosting/logs/list を呼び出すか、TypeScript から api.hosting.log.list(…) を使用します。

デプロイ

デプロイは、1 つのアプリまたは1 つのワーカーのいずれかに属します（--app-uuid と --worker-uuid は同時に指定できません）。

# List / inspect
cargo-ai hosting deployment list --app-uuid <uuid>          # or --worker-uuid <uuid>
cargo-ai hosting deployment get <deployment-uuid>           # status + metadata
cargo-ai hosting deployment get-promoted --app-uuid <uuid>  # what's currently live

# Build & upload a local source directory (point at the package root, NOT dist/)
cargo-ai hosting deployment create --app-uuid <uuid> --source ./my-app
cargo-ai hosting deployment create --worker-uuid <uuid> --source ./my-worker
# default ignores: node_modules,dist,build,.git,.next — override with --ignore "a,b,c"

# Go live
cargo-ai hosting deployment promote --uuid <deployment-uuid>

# Download what a deployment was built from — the uploaded pre-build source
# tree as a tar.gz, not the compiled bundle (default ./deployment-<uuid>-source.tar.gz)
cargo-ai hosting deployment export <deployment-uuid> --output ./live-source.tar.gz

ローカルコピーを失った場合や、ローカルコピーに差異が生じた場合は、deployment export を復旧手段として使用します。昇格済みのデプロイをエクスポートし（get-promoted で UUID を取得できます）、展開して、そこから再デプロイしてください。

重要なルール

• --slug はワークスペースごとに一意である必要があります。ライブホストは <slug>-<workspace prefix>.<root> で、アプリとワーカーではルートが異なります。組み立てるのではなく、get の url を使用してください（URL を参照）。重複する slug を指定すると、create は duplicateSlug で失敗します。
• アプリからワーカーを呼び出す場合はクロスオリジンになります。ワーカーはアプリのオリジンに対する CORS ヘッダーを送信する必要があります。同一オリジンでのマウントはできません。
• CARGO_API_TOKEN はご自身で用意してください。これは --run-as-user-uuid が設定されたワーカーにのみ注入され、トークンがない場合、createCargoApi はエラーをスローします。必要なデプロイを行う前に、シークレット（ワークスペースまたはワーカーの環境変数）として設定してください。
• 環境変数を変更した場合は、新しいデプロイとプロモートが必要です。値はプロモート時にバインドされ、シークレットではない値はバンドルにコンパイルされるため、変数を編集しても、次のデプロイがライブになるまでは何も変わりません。
• サニタイズする前にログを出力してください。キャッチされなかったエラーのみがスタックトレースとともにログに記録されます。catch でユーザー向けのメッセージを返す場合は、原因が失われないよう、先に console.error(err) を実行してください。
• デプロイしても、自動的にライブにはなりません。deployment create はビルドしてアップロードします。URL が変わるのは、そのデプロイを deployment promote したときだけです。現在ライブになっているものを確認するには、deployment get-promoted を使用してください。
• --source は dist/ ではなくパッケージのルートです。ビルドは Cargo サンドボックス内で実行されます。アプリの場合は npm ci --ignore-scripts の後にアプリの build スクリプト（またはフレームワークのデフォルト処理）が実行され、ワーカーの場合はエントリーポイントがバンドルされます。ビルド済みの dist/ を送信しても動作しません。
• アプリの環境変数は公開され、シークレットにはできません。バンドルにコンパイルされ、isSecret は拒否されます。認証情報はワーカーに設定してください。
• Cargo が所有するホストには noindex が設定されています。公開サイトをインデックスに登録するには、カスタムドメイン（API では 1.0.96 以降のみ）と、事前レンダリングされた HTML が必要です。
• ビルドは非同期です。プロモートする前に、終端状態になるまで deployment get をポーリングしてください（以下を参照）。
• --app-uuid と --worker-uuid は、deployment create、deployment list、deployment get-promoted で同時に指定できません。必ずどちらか一方だけを渡してください。
• remove は関連リソースも削除します。アプリまたはワーカーを削除すると、そのすべてのデプロイも削除されます。
• update --folder-uuid null（リテラル文字列 null）を指定すると、リソースをワークスペースのルートに戻します。
• ホスティングでは、リソースごとに毎月クレジットが消費されます。各アプリ／ワーカーには chargedUntil があり、1 時間ごとの処理によって 1 か月ずつ先に進みます。そのため、ライブ状態のアプリやワーカーは継続的にホスティングクレジットを消費します。提供を終了したリソースは remove で削除してください。消費量は cargo-billing で確認できます。

非同期ポーリング

deployment create はサンドボックス内でビルドを開始します。デプロイの status は pending → building → success（または error / cancelled）と変化します。終端状態になるまでポーリングし、その後、success のデプロイをプロモートしてください。

cargo-ai hosting deployment get <deployment-uuid>   # poll ~2–5s until status is terminal

終端状態は success、error、cancelled です。プロモートできるのは success のデプロイのみです。error の場合は、デプロイの errorMessage（および buildLogS3Filename）を確認してビルドの問題を調査してください。一般的なポーリング方法（間隔、再試行）については、../cargo-orchestration/references/polling.md を参照してください。

ヘルプ

すべてのコマンドで --help を使用できます。

cargo-ai hosting app create --help
cargo-ai hosting deployment create --help