実行環境と Secrets

環境とは何か

人が開発するとき、PC に言語ランタイムや依存パッケージを入れ、起動コマンドを覚えます。Cloud Agent にも同じものが必要です。公式ドキュメントも、環境を渡さないことは『エンジニアに PC を渡さない』ことに近い、と表現しています。

依存のインストール、起動方法、必要な秘密情報、ネットワーク。これがそろうほど、Agent は『書いたつもり』ではなく『動かして確認した』ところまで進めます。公式も、環境づくりが Cloud Agent の効果を上げるいちばん大切な一歩だ、と位置づけています。

公式のベストプラクティスでも、『まず環境を整える』『必要な Secrets と通信先が届くか確認する』『手元でも再現しにくいものはクラウドでも難しい』と書かれています。依頼文を磨く前に、仕事場を疑う習慣が近道です。

『書いた』と『確認した』のちがい

仕事場が足りない Agent は、ファイルを直すところまではできても、テストや画面確認で止まりがちです。あなた側から見ると、『スクショが付かない』『プレビュー手順が無い』『確認できなかったと書く』といった形で現れます。

逆に仕事場がそろうと、Agent は自分で起動し、クリックし、成果物を添えてから PR を出せます。これが公式の言う『閉じたループ』（書いて終わりにせず、検証まで自分で回す）です。

• スクショや短い動画が欲しい → アプリを起動できる環境が必要
• ログイン後の画面を見てほしい → ログイン用 Secrets（必要なら 2FA）が必要
• 社内 API まで触ってほしい → ネットワーク許可や接続の準備が必要

環境の作り方は3系統

公式のセットアップでは、だいたい次のどれか（または組み合わせ）で仕事場を用意します。名前を覚える必要はありません。『環境がない』と『環境の作り方を選ぶ』は別問題だと知っておくと、開発者との会話が速くなります。

Dockerfile を使うときは、`environment.json` の `build.dockerfile` と `build.context` は `.cursor` フォルダ基準です（詳しい人向け）。`context` を省略すると `.cursor` になり、`.` / `./` / `..` はリポジトリルートを指す特別扱いです。`install` コマンド自体はプロジェクトルートで実行されます。

• Agent 主導のセットアップ（ガイド付き）: Cloud Agents ダッシュボードまたは Desktop の Agents Window から始め、GitHub / GitLab / Azure DevOps / Bitbucket を接続し、依存の install に必要な Secrets 名だけを渡して Agent に仕事場を作ってもらう（公式の推奨。多くの場合10分以内のイメージ）
• 保存済みスナップショット: 一度整えた状態を使い回す。ダッシュボードで作ったスナップショット ID を `.cursor/environment.json` の `snapshot` フィールドに書いて固定することもできます（詳しい人向け）
• Dockerfile / .cursor/environment.json: リポジトリ側に環境定義を置く。プロジェクト全体を Dockerfile で COPY しないのが公式の前提です（Cursor がワークスペースを管理し、正しいコミットを checkout する）。Dockerfile を変えたときはレイヤーキャッシュで変更した層だけ再ビルドされ、毎回ゼロからではない、と公式にあります（詳しい人向け）。Dockerfile ベースではコンピュータ操作（画面確認）は Debian / Ubuntu 系 Linux が前提です。Enterprise では Cursor が Dockerfile を提案する private beta もあります（詳しい人向け）
• Cloud Agent Builds: 起動前に clone と install を済ませた型をバックグラウンドで作る（新環境では既定）

Cloud Agent Builds（事前に仕事場を温める）

公式の Cloud Agent Builds は、Agent が動く前にバックグラウンドで clone と依存の install を済ませた『起動可能な型』を作ります。新しい環境は Builds が既定でオンです。毎回ゼロから npm install するより、起動が速く、いつも同じ道具立てから始めやすくなります。

ダッシュボードの Environments → 対象環境 → Builds タブで、Build の成功／失敗・ログ・開始時刻を確認できます。Agent の実行記録には、どの Build から起動したかも残ります。『前回と違う挙動』のときは、Version history だけでなく Build の履歴も見ると原因に近づけます。

新しい Build が失敗しても、最後に成功した Build が使われ続けます。依存の更新ミスで、いきなり全員の Agent が動かなくなる心配は小さくてよい、という公式の説明があります。Builds 自体に追加課金はなく、Cloud Agent に含まれます。

古い環境で Builds がまだオフのときは、Builds タブの Enable Builds か Run setup agent から有効化し、最初の Build が成功してから本番の Agent 実行に使うのが安全です。Test build なら、全体を有効化する前に設定だけ試せます。

main（本線）で起動するとき、Build に記録されたコミットから始まることがあります。Builds タブの Update stale builds をオンにすると、Build が Staleness threshold（既定24時間）より古いとき、起動時に main の最新を取りに行きます。threshold を 0 にすると毎回最新を取りに行きます。オフのときは Build 作成時点の main に固定されます。

機能ブランチで起動するときは、Build で温めた依存の上に、選んだブランチのソースが載せ替えられます。ブランチ側で package.json など依存が変わったときは、Agent が install をやり直すことがあります。

• install: Build のたびに走る。依存の取得・コンパイル・キャッシュの温め。npm install / pnpm install のように、何度実行しても安全な書き方（冪等）がよい。ダッシュボードや古い資料では update script と書かれていることもありますが、いまの公式名は install（install スクリプト）です。Build 中も Agent と同じローカルソケットからエージェントメタデータを読んだり OIDC トークンを発行したりできる、と公式にあります（詳しい人向け）
• start: Agent 起動のたびに走る。Docker・DB・トンネルなど、サービスの起動。多くのリポジトリでは省略できます。Docker が必要なときは `sudo service docker start` を start に書く、という公式例があります
• terminals: Agent 起動のたびに tmux でアプリプロセスを起動し、Agent と共有するターミナルとして使う
• Test build: Builds を全体有効化する前に、設定だけ試す
• Update stale builds: main のコードの新しさを Build 時点と起動時の pull で調整する

Build はいつ走るか

Build はバックグラウンドで次のようなきっかけで始まります。公式のライフサイクルは、きっかけ → clone と install → ディスクを型として保存 → 成功した Build が有効（active）になる → 新しい Agent がその型から起動、という流れです。

Builds タブでは、きっかけが4種類のラベルで表示されます。Recurring（定期チェック）・Configuration change（環境設定や Secrets の保存・変更）・Manual（Trigger build などの手動）・Agent-requested（環境直しを Agent に頼んだときなど）。名前を全部覚えなくて大丈夫です。『いつ・なぜ走ったか』の手がかりとして見れば十分です。

有効（active）な Build は、起動をさらに速くするためにあらかじめ温められたコピーが待機していることもあります。毎回 clone と install から始める必要が減る、という公式の説明です。

最初の Build がまだ1回も成功していない環境では、従来どおり Agent 起動のたびに clone と install が走ります。失敗した Build だけがあっても、いま動いている Agent の流れは止まりません。

• Recurring（定期）: 型を定期的に作り直し、main のコミットを更新しやすくする
• Skipped（スキップ）: Recurring だけの状態。main の新コミットも環境設定の変更も無いとき。install は走らず、有効な Build はそのまま。Success と Skipped が混ざるのは正常です
• Configuration change: 環境の版を保存したときや Secrets を変えたとき。必ず install が走ります
• Manual: Builds タブの Trigger build / Test build。手動で今すぐ試す。必ず install が走ります
• Agent-requested: Cloud Agent に環境直しを頼んだときなど、Agent 側から Build を頼むこともある

Builds タブでできること（概要）

詳しい人向けですが、Builds タブには Build ごとのきっかけ（trigger）・状態・開始時刻が並びます。Recurring / Configuration change / Manual / Agent-requested のどれで始まったかが分かるので、『なぜ今走ったか』の切り分けに使えます。

進行中の Build はキャンセルできます。下書き（draft）の Build を有効化したり、いま使われている Build をいったん止めたりもできます。

通常は『最新の成功 Build』から Agent が起動します。挙動を比べたいときだけ、特定の Build から Agent を起動する、という使い方も公式にあります。

Build と main の新しさ

Build は速く始めるための型ですが、main のソースが Build 作成時点に固定されることがあります。Update stale builds と Staleness threshold で、『いつ main を最新に取りに行くか』をチームで調整します。

Build が失敗したとき（ログと再現）

Builds タブには成功・失敗・進行中の Build が並びます。失敗した Build を開くと、イベントとログを読めます。新しい Build が失敗しても、Agent の起動は最後に成功した Build を使い続けるので、いきなり全員が動かなくなる心配は小さい、という公式の説明があります。

原因を特定するときは、失敗した Build から Agent を起動して、壊れた状態のまま調査させる方法もあります（詳しい人向け）。Builds タブの Trigger build や Test build で、設定を直したあとに再実行できます。

組み込みの Cursor Cloud MCP を使えば、Cloud Agent に『最新の失敗 Build を調べて Test build で直す』と頼む流れも公式例にあります。代表的な道具は list-environment-builds（Build 一覧）、environment-build-logs（install ログ）、trigger-environment-build（テスト Build の実行）、propose-environment-json（install / start コマンドの提案）、take-environment-snapshot / check-environment-snapshot（動いた環境の保存と完了確認）、request-environment-setup-actions（Secret 追加など、セットアップ待ちの依頼記録）です。普段は意識しなくてよく、詳しい人や Agent 自身が環境トラブルを直すときに使います（外部ツール MCP との接続節も参照）。

どの環境が選ばれるか（解決の優先順位）

同じリポジトリでも、環境の決まり方には順番があります。公式の解決順はだいたい次のとおりです。

Build の土台になる `.cursor/environment.json` は、環境の既定ブランチ（多くは main）の内容が使われます。機能ブランチだけに追加・変更したときは、commit して push したうえで、そのブランチから Agent を起動してください（公式 Cloud Environment Setup）。

Builds が有効な環境では install（旧ダッシュボード名: update script）は多くの場合 Build の段階で済みます。Build が無い／失敗しているときは Agent 起動のたびに依存更新が走ることがあります。Enterprise で VM のメモリや CPU が足りないときは、サポートへ上限引き上げを相談できます（自己サービス設定は今後追加予定、と公式）。

• リポジトリ内の `.cursor/environment.json`
• 個人用に保存した環境
• チーム共有の環境

どの環境で動いたか確認する

同じリポジトリでも、`.cursor/environment.json` の有無や警告付きの Environment ready などで、実行ごとに土台が変わることがあります。テストが通らない・スクショが付かないときは、コードより先に『いつもの仕事場か』を疑うと早いです。

公式では、Agent の実行画面で画面上部のリポジトリ名にカーソルを載せると、その実行で選ばれた環境と Version history を確認できます。実行記録には、どの Cloud Agent Build から起動したかも残ります。Cloud Agents ダッシュボードでも、環境名・Build 履歴・Version history を一覧できます。

警告付きの『Environment ready』

保存したスナップショットが期限切れや読み込み失敗になると、Cursor は既定の土台へ戻して起動を続けることがあります。画面には『Environment ready (with warnings)』のような警告と、会話内の環境カードが残ります。

これは『Agent がサボった』ではなく、『いつもの道具立てが一時的に使えなかった』サインです。警告からセットアップを開き、詳しい人と環境を直すか、Version history から前の版を戻すかを相談しましょう。自動では古い版に切り替わりません。

ネットワーク制限

Cloud Agent がインターネットのどこへ届けるかも設定できます。全部許可、既定ドメイン＋許可リスト、許可リストのみ、といった段階があります。ユーザー／チーム／環境ごとに決められ、環境に独自設定があるときはそちらが優先されます。

『パッケージが取れない』『外部 API に届かない』ときは、コードの問題ではなく通信制限のことがあります。はじめての方は『どのドメインが必要そうか』を言葉にして、詳しい人に渡すだけで十分です。

社内だけのサービスへ届けたいときは、Tailscale などのプライベート接続や、Enterprise 向けの Private Connectivity を組み合わせるチームもあります。公式の Cloud Environment Setup では、Tailscale は userspace networking モード（`tailscaled --tun=userspace-networking` とプロキシ変数）や、社内 VPC 向けの Cloudflare Tunnel（`cloudflared`）の例もあります。userspace networking では VM を tailnet の exit node にはできません（社内リソースへ届けば十分なことが多いです）。

Cloudflare Tunnel で社内 HTTP サービスへ届けるときは、社内ネットワークに `cloudflared` コネクタを置き、認証付きホスト名（例: vpc.example.com）をトンネル経由でプライベート先へ向けます。Cloudflare Access を使うなら、Secrets に `CF_ACCESS_CLIENT_ID` / `CF_ACCESS_CLIENT_SECRET` を入れ、HTTPS リクエストに `CF-Access-Client-Id` / `CF-Access-Client-Secret` ヘッダーを付ける公式例があります。プライベート TCP（データベースなど）向けには `cloudflared access tcp` を start に書き、ローカルリスナーへ向けるパターンもあります。トンネルトークンや Access の秘密はリポジトリに置かず Secrets に入れます（詳しい人向け）。

設定自体は詳しい人向けですが、『社内 VPN 内の API が必要』『Cloudflare Access 付きの社内ホスト名が必要』と伝えられるだけで会話が進みます。

許可リストを厳しくしたあと、スクショや動画などの成果物だけ付かなくなったときは、成果物のアップロード先ホスト（公式ドキュメントにある cloud-agent-artifacts の S3 ホスト）を許可リストへ足す必要があることがあります。`*.s3...` のような広いワイルドカードは、意図しない桶まで開けてしまうので避けます。

Docker を使うリポジトリでは、公式の Cloud Environment Setup でも触れられています。単純な `docker run` なら Docker を入れてデーモンを起動するだけで動くことが多いです。一方、Cloud Agent の VM はコンテナの中で動くため、複雑な Docker 構成（ネストしたコンテナなど）では `fuse-overlayfs` や `iptables-legacy` などの追加設定が必要になることがあります（詳しい人向け。公式に Dockerfile 例あり）。

モデルとコンテキスト窓（はじめて向け）

手動で Cloud Agent を起動するときは、使うモデル（AI の頭脳）を選べます。Cloud Agent が使えるモデルは、公式が選んだ一覧から選ぶ形です（curated selection）。Auto を選ぶと、その依頼に向くモデルを Cursor が振り分けます。Teams / Enterprise では裏側が Cursor Router で、Optimize For（Cost / Balance / Intelligence）だけ決めます（accounts-setup の Auto 節。公式 Cursor Router）。

Web や Desktop では、対応モデルについてコンテキスト窓（一度に読める文脈の大きさ）も選べます。大きいほど長い会話や大きなリポジトリを一度に扱えますが、トークン消費とコストが増えやすい点に注意しましょう。

Automations でもモデルは選べますが、コンテキスト窓の切り替えはなく、常にそのモデルの最大窓で動きます（公式）。そのため、手動起動よりトークンを使いやすい、という注意があります。定期実行の Prompt は短く、完了条件を明確にすると節約になります。Start プランには Auto も Automations もありません。

Secrets の扱い

API キーやトークンは、コードやチャットに貼らず、Web の Cloud Agents 設定（cursor.com/dashboard/cloud-agents）の Secrets へ入れます。スマホアプリからは主に使う側で、秘密情報の登録や環境そのものの編集は Web 側の作業です。

Secrets には種類があります。上の図のとおり、はじめての方は『漏れたくない値は Runtime Secret』と覚えるだけで十分です。迷ったら Runtime Secret を選びましょう。

• Runtime Secret（旧称 Redacted）: 作業には使うが、会話・ツール結果・コミット文面には `[REDACTED]` と伏せる。API キー向け
• Environment Variable: Agent にも見える設定値。公開 URL やフラグなど、読ませてよいもの向け
• Build Secret: Dockerfile のビルド時だけ使う鍵。実行中の Agent には渡らない

Secrets を環境やモノレポで分ける

複数リポジトリを束ねた環境では、その環境だけに効く Secrets（環境スコープ）も使えます。ステージング用の鍵を、別プロダクトの実行へ漏らしたくないときに便利です。

1つのリポジトリの中に `.env.local` が複数ある（フロントと API など）ときも、Secrets タブへまとめて入れます。名前がぶつかるキーは `NEXTJS_*` と `CONVEX_*` のように接頭辞を付けて区別し、各アプリから参照させます。スナップショット作成時に `.env.local` を含めると保存されることもありますが、管理しやすさでは Secrets タブが公式の推奨です。

Secrets タブが見えないとき

Secrets の追加・編集は、主に cursor.com/dashboard/cloud-agents の Secrets タブ（Cloud Agents 設定）で行います。モバイルアプリは設定の正ではなく、すでに登録済みの Secrets を Agent が使うイメージです。

タブ自体が見えないときは、Cloud Agent 用の権限やチームロールが足りないことが多いです。値を入れたいだけなら、チーム管理者か詳しい人に『Runtime Secret で（名前だけ）を登録してほしい。値は別経路で渡す』と依頼すれば十分です。

Secrets を足したあと

新しい Secrets を登録した直後、すでに動いている Agent には反映されないことがあります。公式のトラブルシュートでは、Secrets 追加後に Cloud Agent を再起動（新しい実行を始める）することを案内しています。

チーム／ワークスペースを間違えていないかも確認しましょう。Secrets はチーム単位で、別アカウントに入っていると見えません。

ログインが必要な画面を見せたいとき

会員ページや管理画面など、ログイン後にしか見えない変更は、Agent にもログイン情報が必要です。手元で使っているテスト用のユーザー名／メール／パスワードを Secrets に入れます（本番の個人アカウントは避けます）。

アプリが TOTP 形式の 2FA（認証アプリの6桁）を使うなら、その共有秘密（shared / root secret）も Secrets に入れられることがあります。公式例では Agent が `oathtool --totp -b "$TOTP_SECRET"` のように6桁を生成します。詳しい人が設定する前提で、『ログイン後画面の確認まで進めたい』と伝えるだけで十分です。値そのものはチャットに書かないでください。

AGENTS.md：Cloud 向けの作業メモ

Cloud Agent はリポジトリの `AGENTS.md` も読みます。公式は、見出し例として `Cursor Cloud specific instructions` を置き、起動や確認の手順を書いておくことを勧めています。

はじめての方でも、『プレビューの開き方』『触ってほしくない範囲』『完了時に欲しい成果物』を箇条書きで提案できます。長くなりそうなら、詳細ファイルへのリンクでも大丈夫です。Rules（いつも守る約束）と併用できます。

外部ツール（MCP）との接続

Cloud Agent は MCP という接続口で、社内ツールやデータベースなどへ手が届くことがあります。追加や管理は主に Web（cursor.com/agents の MCP、またはチームの Integrations）側です。スマホでは『この実行でどれを使うか』を選ぶイメージです。

接続の仕方には HTTP（推奨）と stdio があります。Cloud Agent はどちらも公式サポートし、OAuth が必要な MCP サーバーにも対応しています（接続は Integrations や起動時の MCP 選択で行い、チーム共有でも利用者ごとの認証が必要なことがあります）。HTTP のほうが、鍵やトークンが Agent の作業用コンピュータに直接渡らず安心です。stdio は作業場の中で動く方式で、環境が整っていないと失敗しやすいです。SSE や mcp-remote 方式は Cloud Agent ではサポートされません。stdio を使う場合、起動してみないと成功可否が分からないこともある、という公式の注意もあります。詳しい人に『HTTP でつなげるか』と聞くだけで十分です。

MCP 設定を保存したあと、環境変数（env）・HTTP ヘッダー・OAuth の CLIENT_SECRET など敏感な項目は、誰も画面から読み戻せません（暗号化保存）。値を失念したときは、詳しい人と一緒に作り直す必要があります。

チーム共有の MCP は、管理者が Default team marketplace へリンクしておくと、Cloud Agent からも使え、同僚が Agent Window / IDE / CLI へ入れる形にもできます。OAuth が必要な MCP は、チーム共有でも接続は利用者ごとです。

加えて、実行診断用の『Cursor Cloud MCP』が組み込まれています。いまの実行の状態、同じ環境の他の実行、会話ログ、環境設定、セットアップログ、実行イベント（setup_failed / pr_creation_failed / artifact_created など）、Build 履歴と install ログなどを Agent 自身が調べるための道具です。Build が失敗したときの節で触れた list-environment-builds / environment-build-logs / trigger-environment-build / propose-environment-json / take-environment-snapshot / check-environment-snapshot / request-environment-setup-actions も、この診断用 MCP の一部です。

公式の典型的な調査の流れは run-info（いまの実行）→ get-events（イベント一覧）→ environment-info（環境の版と設定）→ list-cloud-agents / batch-fetch-details（他の実行）です。list-cloud-agents では起動元・状態・日付・コード変更の有無・PR 作成の有無に加え、archived（アーカイブ済み）かどうかでも絞れます。古い失敗実行を除いて『いま動いている実行だけ』を見たいときに便利です。他の実行のダッシュボードイベントまでまとめて見るときは、batch-fetch-details の include_events を使います（1回最大50件）。batch-fetch-details では、コードを変えたか・PR を開いたかといった差分メタデータも取れます。Automation の実行を追うときは get-automation もあります。Subscriptions や Automations で『待っているのに動かない』ときは、get-message-queue で未処理のフォローアップが残っているかも確認できます。普段は意識しなくてよく、トラブル時に詳しい人が使うイメージで十分です。一般メンバーは自分の実行中心、チーム管理者は権限のある範囲で他の実行も見られる、という差があります。Team Owned の Automation が使うサービスアカウントも、一般メンバーと同じ閲覧ルールに従います。チーム管理者は Dashboard の MCP 設定から、この診断用 MCP を無効にすることもできます。

MCP クライアントによっては、道具名の前に cursor-cloud- のような接頭辞が付いて見えることがあります（例: cursor-cloud-run-info）。中身は同じ道具です。

MCP の認証に失敗したときは、ダッシュボードの実行イベントに `mcp_auth_error` と出ることがあります（くわしくは次の節）。

はじめての方としては、『Agent に触らせてよい外部サービスはどれか』をチームで決めておくことが大切です。よく分からない接続は、詳しい人に確認してからオンにしましょう。

ダッシュボードの実行イベントを読む

Cloud Agent の実行画面（cursor.com/agents やダッシュボード）には、公式のイベント一覧があります。会話の要約だけでは分からない『どこで止まったか』を、短い kind 名で確認できます。

• setup_started / setup_completed: 仕事場の準備が始まった／終わった
• setup_failed: 仕事場の準備に失敗。Builds タブや setup ログを開き、install / start のエラーを直す
• setup_started のまま長く止まる: Secret 追加などのユーザー操作待ちのことがあります。会話に request-environment-setup-actions の記録が無いか確認し、Secret 名だけを管理者へ伝えて対応後に続きを頼みます
• pr_created: Pull Request が開けた
• pr_creation_failed: PR 作成に失敗。GitHub 連携の PR 権限・ブランチ保護・対象ブランチを確認。差分は残っていることが多い
• artifact_created: スクショや動画などの成果物がアップロードされた。Agent 画面の成果物欄や PR（設定次第）を開く
• mcp_auth_error: MCP 認証失敗。その MCP だけスキップされ実行は続く。Integrations で再接続するか MCP 選択から外す

はじめての方ができる貢献

環境そのものの作成は、詳しい人が担うことが多いです。あなたは、『どの外部サービスが必要か』『プレビューで何ができれば十分か』『Secrets に入れるべき値の名前（値そのものではない）と種類（Runtime Secret か）』『AGENTS.md に書いてほしい確認手順』を言葉にすることで、十分に貢献できます。

データはどれくらい残るか（はじめて向け）

Cloud Agent の実行では、だいたい2種類のデータが残ります。会話履歴（依頼文・返答・ツール結果・成果物）と、環境スナップショット（仕事場のディスクの型）。公式の retention（保持）の要点だけ押さえておくと、不安が減ります。

• 会話履歴: 既定では無期限。あとから見返したり、続きを頼めたりするためです
• 環境スナップショット: 使われない状態が最大90日続くと、自動で消えます。起動や再開のたびに、期限がまた90日伸びます
• Enterprise: チーム管理者が会話の保持を『無期限』か『90日』に決められることがあります（早期アクセス）。90日にすると古い会話は削除されますが、すでに消えたものは戻りません
• 明示削除: Delete Agent API などで会話を消せる場合があります。スナップショットはオンデマンド削除ではなく、上記の90日ルールに従います

OIDC トークンとエージェントメタデータ（詳しい人向けの概要）

はじめての方は、名前だけ知っておけば十分です。いずれも Cloud Agent の作業用コンピュータ内のローカルソケット（`CURSOR_AGENT_SOCKET`、既定は `/run/cursor/api.sock`）から読み取る公式の仕組みで、OIDC トークン発行とエージェントメタデータ取得が同じ入口を共有します。

OIDC トークンは、短い有効期限（約5分）の署名付き JWT を作業用コンピュータ内で発行し、AWS IAM の AssumeRoleWithWebIdentity や社内 API などへ『この実行だ』と証明するための道具です。長期の API キーを Secrets に置きたくないとき、詳しい人が使います。GCP Workload Identity Federation、Azure 連携、Vault など OIDC 対応の検証先でも同じ流れです。Agent に『OIDC トークンの公式手順に従って接続して』と頼む流れも公式にあります。

AWS 向けの公式例では、Secrets に `CURSOR_AWS_ASSUME_IAM_ROLE_ARN`（引き受ける IAM ロールの ARN）を入れ、チーム設定で External ID を発行し、AWS 側の信頼ポリシーを合わせると、Agent 起動中は `AWS_PROFILE=cursor-cloud-agent`・`AWS_CONFIG_FILE`（Cursor 管理の設定ファイル）・`AWS_SDK_LOAD_CONFIG=1` が自動設定され、長期の `AWS_ACCESS_KEY_ID` を自分で export しなくても AWS CLI / SDK が動く、と説明されています（管理者・詳しい人向け）。STS の一時認証情報は1時間で失効し、Agent が再開するときは失効15分前から自動更新される、とも公式にあります。

エージェントメタデータは、Agent ID（`agent/id`、bcId）、ダッシュボード名（`agent/name`）、起動元（`agent/source`：WEBSITE / API / SLACK / AUTOMATIONS など）、実行基盤（`agent/runtime` は Cursor 管理 VM では `managed`）、所有者（`owner/user-id` / `owner/team-id` / 必要なら `owner/service-account-id`）、いまのターンを送った人（`turn/user-id` など）、このターンの ID（`turn/id`。`agent/id` とは別）、ターン開始時刻（`turn/started-at`）、このターンで動いたモデル（`turn/model`。Auto を選んでも実名が入る）、保管庫（`workspace/repo-url` は主リポジトリ、`workspace/repo-urls` は複数行で全保管庫。主リポジトリが先頭で残りはソート）、ブランチ、環境 ID、Automation ID（`workspace/automation-id`）などをキーと値で読む仕組みです。Hooks や install スクリプト、ログのタグ付けに使います。

team follow-ups では、所有者（`owner/user-id`）と、このターンを送った人（`turn/user-id`）が違うことがあります。公式例では、追記者が所有者と違うときに別の監査パスを通す、といった使い方があります。

`turn/` 配下（`turn/id` / `turn/user-id` / `turn/model` / `turn/started-at` など）は、コーディングターンが動いている間だけ存在します。ターンとターンのあいだは `turn/` 自体が消え、404 になります。Hooks で読むときはターン中だけ値があり、ターンをまたいでキャッシュしない、と公式は注意しています。

起動直後にソケットがまだ無いときは、接続を再試行します。読み取りエラーは 403 が致命的（再試行しない）、429（rate_limited）/ 503（saturated・同時接続が多すぎる）/ 500 / 502 / 504 は Retry-After を見てバックオフで再試行、という公式の整理があります（429 は1分あたり120回・最大20件のバースト上限。ソケットへの同時接続は最大8で、OIDC 発行と共有されます）。

所有者や送信者のメール（`owner/user-email` / `turn/user-email`）も読めますが、許可リストには変わりにくい `owner/user-id` を使うのが公式の推奨です。ソケットに届くプロセスは全キーを読めるので、メタデータを秘密情報の代わりにしないでください。

メタデータに署名はなく、認証情報の代わりには使いません。クラウドへ ID を証明したいときは OIDC トークンを使い、『誰がこのターンを送ったか』『どのモデルが動いたか』などはメタデータから読む、と公式は整理しています。エージェントメタデータはプレビュー段階の公式機能です。

VM の外から Agent を作る Cloud Agents API や SDK で付ける metadata タグとは別物です。API キーで外から管理するタグと、作業用コンピュータ内の実行メタデータは混同しないでください。

Agent に読ませたいときは、公式の metadata / identity ページの手順を Prompt に含める形が推奨されています（例: 『エージェントメタデータを読むには https://cursor.com/docs/cloud-agent/metadata の手順に従って』）。

管理者・詳しい人に頼むときの型

公式も、環境づくりは Agent 主導のセットアップを推奨しています（ダッシュボードや Agents Window から始め、あとでスナップショット保存）。ダッシュボードでは Update with Agent（いまの環境を直す）、New Setup Run（いちから組み直す）、Version history の Restore（前の版に戻す）も選べます。あなたがコードを書かなくても、次の一文で依頼を始められます。

• やりたいこと: Cloud Agent がプレビュー（またはテスト）まで自分で確認できるようにしたい
• 対象リポジトリ: （名前）
• 必要な外部サービス: （例: プレビュー用 API、画像配信、なし）
• Secrets に入れたい名前だけ: （値はチャットに書かない。漏れたくない値は Runtime Secret。ログイン用や環境スコープの要否も一言）
• お願い: Agent 主導セットアップ → 動いたらスナップショット保存 → できれば `.cursor/environment.json` と AGENTS.md の Cloud 節もリポジトリへ