Skip to main content

Command Palette

Search for a command to run...

Cloud Agents

Cloud 環境のセットアップ

Cloud Agents は、分離された Ubuntu マシン上で実行されます。エージェントが、開発者が使用するのと同じリポジトリ、ツール、依存関係、シークレット、ネットワークアクセスを利用できるように、環境を設定してください。

Cloud Agents ダッシュボードで新しい環境を作成します。

Cloud Agent の環境とは？

Cloud Agent の開発環境は、ノートパソコン上のセットアップを再現したものです。クローンしたリポジトリ、インストール済みの依存関係、シークレット、起動コマンド、ネットワークアクセスなどが含まれます。

効果的な開発環境であれば、エージェントはコードベースと組織に関する完全なコンテキストを得られるため、作業をテストして確認できます。

環境設定が重要な理由

エージェントの能力は、実行環境に大きく左右されます。コードを書けても、テストを実行したり、サービスを照会したり、API にアクセスしたりできなければ、作業を最後まで完了できません。

エンジニアリング作業を最初から最後まで完遂するには、Cloud Agent に、リポジトリ、ツール、依存関係、コンテキストがすべて揃った設定済みの開発環境が必要です。そうすることで、自律的かつ効率的に作業を進められます。

また、開発環境があれば、エージェントセッションも高速になります。作るはバックグラウンドでリポジトリ、ツール、依存関係を準備するため、エージェントはすぐに使用できるマシンで作業を開始できます。

環境のセットアップは、Cloud Agent の効果を高めるうえで最も重要なステップです。

環境のセットアップ オプション

Cloud Agent の環境を設定する主な方法は 2 つあります。

  1. Cloud Agents ダッシュボード から Cursor のエージェントに環境をセットアップさせる方法です。エージェントが依存関係をインストールし、環境を検証して、最初の 作る を作成します。
  2. Dockerfile を使って環境を手動で設定する方法です。このオプションを選択した場合は、.cursor/environment.json ファイルで Dockerfile を指定できます。

どちらの方法でもインストール スクリプトを指定できます。Cursor は 作る の作成中にこのスクリプトを実行するため、エージェントの開始前に依存関係の準備が整います。

マルチリポジトリ環境

エージェントが複数のリポジトリにまたがって作業する必要がある場合は、マルチリポジトリ環境を使用します。環境の作成時に複数のリポジトリを選択します。Cursor は選択した各リポジトリをエージェントのマシンにクローンし、同じリポジトリグループを使用する今後のエージェント実行と自動化でその環境を再利用します。

フロントエンド、バックエンド、インフラストラクチャ、共有ライブラリがそれぞれ別のリポジトリにある場合は、マルチリポジトリ環境を使用します。エージェントはワークスペース全体を確認し、連携した変更を加え、リポジトリをまたいでテストを実行し、変更を加えたリポジトリでプルリクエストを作成できます。

現在アクティブな環境と、過去にアクティブだったすべてのバージョンは、Cloud Agents ダッシュボード の環境の設定ページで参照できます。

環境の解決順序

Cursor は、repository または repo group ごとに環境設定を解決し、最初に一致したものを使用します。

  1. repository 内の .cursor/environment.json
  2. 個人用に保存された環境
  3. チーム用に保存された環境

これにより、repo レベルの .cursor/environment.json がない場合でも、チームレベルでは予測可能なデフォルトを維持しつつ、個々のユーザーは個人用の環境で上書きできます。ユーザーによる上書きは、新しい環境設定をチーム全体に展開する前に試す際にも役立ちます。

エージェントによるセットアップ (推奨)

Cursor なら、クラウド上で 10 分以内に開発環境をセットアップできます。ガイド付きセットアップは、Cloud Agents ダッシュボード または Cursor デスクトップアプリの Agents Window から開始できます。

GitHub、GitLab、Azure DevOps、または Bitbucket のアカウントを接続し、1 つ以上のリポジトリを選択するよう求められます。

次に、依存関係のインストールとコードの実行に必要な環境変数とシークレットを Cursor に提供します。

エージェントの作業中は、依存関係のインストールなどのセットアップタスクを処理する進行状況を、共有ターミナルセッションで確認できます。Cursor はコードを検証し、作る が正常に完了すると環境を保存します。

今後の Cloud Agents はアクティブな 作る から開始し、ソフトウェアを実行して変更をテストできます。設定を .cursor/environment.json にコミットすれば、チーム全体でその恩恵を受けられます。

Dockerfile を使った手動セットアップ (上級者向け)

高度な用途では、Dockerfile で環境を設定します。

  • Dockerfile を作成して、システムレベルの依存関係のインストール、特定のコンパイラーバージョンの使用、デバッガーのインストール、ベース OS イメージの切り替えを行います
  • プロジェクト全体を COPY しないでください。ワークスペースは Cursor が管理し、正しいコミットをチェックアウトします
  • 実行時の設定を行うには、.cursor/environment.json を直接編集します
  • 非公開のパッケージレジストリやビルド時の認証情報には、ビルド シークレットを使用します

以下は、.cursor/Dockerfile (相対パス) と custom_script.sh インストールスクリプトを参照する .cursor/environment.json の例です。

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

repo で Docker、Tailscale、または Cloudflare Tunnel が必要な場合は、以下の Docker の実行、Tailscale の実行 および Cloudflare Tunnel の実行 を参照してください。

Dockerfile で環境を設定します。リモートマシンに直接アクセスすることはできません。

Dockerfile のビルドではレイヤーキャッシュを使用します。Dockerfile を変更すると、Cursor はすべてのレイヤーを最初から再ビルドするのではなく、変更されたレイヤーのみを再ビルドします。

Cursor による Dockerfile の設定 (プライベートベータ)

Dockerfile を一から書きたくないチーム向けに、Cursor が代わりに設定できます。セットアップ中に、Cursor はリポジトリを調査し、ツールと依存関係を特定して、編集してバージョン管理できる Dockerfile ベースの環境設定を生成します。

このフローは Enterprise チーム向けのプライベートベータです。アクセスをリクエストするには、Cursor アカウントの担当者に連絡するか、チーム管理者アカウントから hi@cursor.com にメールしてください。

リソース上限

各 cloud agent は、メモリと CPU に制限のある既定の VM プロファイル上で実行されます。Enterprise プランをご利用で、repo により多くのリソースが必要な場合は、サポートにお問い合わせください。ワークスペース の上限を引き上げることができます。

セルフサービスでのカスタムリソース構成は近日提供予定です。

インストールスクリプト

インストールスクリプトは、以前はダッシュボードとドキュメントで更新スクリプトと呼ばれていました。

Cursor は、作る を作成する際にインストールスクリプト (environment.json の install) を実行します。このスクリプトは各エージェントの起動を待たせず、バックグラウンドで完了します。

Cursor が事前に準備できる作業には install を使用します。たとえば、依存関係のインストール、コードの生成、アーティファクトのコンパイル、ディスクキャッシュのウォームアップなどです。

インストールスクリプトは、エージェントが使用する同じローカルソケットからエージェント メタデータを読み取り、OIDC トークンを発行できます。

作るでのインストールスクリプトの使われ方

Cursorは環境のベースイメージをもとに、リポジトリをクローンし、install を最後まで実行します。作るが成功すると、作成後のディスク状態がキャプチャされ、アクティブになります。新しいエージェントはアクティブな作るから開始します。

スクリプトは必ず完了するようにしてください。時間のかかるセットアップは、エージェントリクエスト中ではなく起動前に実行されるため、install に含めます。pnpm install などのコマンドでは、準備済みの状態を再利用し、変更された依存関係のみを更新できます。

作るで保持されるのはディスク状態のみです。実行中のプロセス、エクスポートされたシェル変数、メモリ内のキャッシュは、エージェントの実行には引き継がれません。サービスは start または terminals で起動してください。

環境設定の復旧

作る が失敗しても、アクティブな 作る は置き換えられません。失敗を確認して代替の 作る を作成する間も、エージェントは直近で成功した環境から起動できます。

環境の 作る タブを開くと、ログの確認、失敗した 作る からのエージェントの起動、別の成功した 作る の選択ができます。作る の操作やデバッグについては、Cloud Agent 作る を参照してください。

インストールスクリプトに含める内容の決め方

繰り返し可能な準備手順はすべて install に記述します。依存関係のインストール、コード生成、アーティファクトのコンパイルなど、再利用可能な成果物をディスクに書き込む作業を含めます。

長時間実行されるプロセスは install に含めないでください。Docker、データベース、トンネル、開発サーバーは起動コマンドに記述します。エージェントが特定のタスクでのみ必要とするサービスについては、AGENTS.md に手順を追加することもできます。

起動コマンド

エージェントが Build から起動すると、Cursor は start コマンドを実行し、その後に設定された任意の terminals を実行します。これらは、エージェントの実行中も動かし続けておきたいプロセスに使用します。

多くのリポジトリでは start を省略できます。環境が Docker に依存している場合は、start に sudo service docker start を追加してください。

terminals はアプリケーションのコードプロセス向けです。これらのターミナルは、あなたとエージェントが共有する tmux セッション内で実行されます。

AGENTS.md にクラウド固有の手順を追加する

Cloud Agents は AGENTS.md ファイルを読み込みます。Cloud 専用のセットアップおよびテスト手順用に、Cursor Cloud specific instructions のようなタイトルの専用セクションを追加することを推奨します。

このセクションが大きくなってきた場合は、特定のタスク向けの詳細な手順を含められる他のファイルへのリファレンスを含めることを推奨します。

詳細については、AGENTS.md docs を参照してください。

環境変数とシークレット

Cloud Agentsが人間の開発者と同じようにコードを実行・テストするには、APIキーやデータベースの認証情報などの環境変数やシークレットが必要になることがよくあります。

推奨: Cursor の設定の Secrets タブを使用

シークレットを管理する最も簡単な方法は、cursor.com を使うことです。これらはCloud Agentに環境変数として渡されます。

シークレットの種類について詳しくは、Secrets のドキュメントを参照してください。長期利用のキーを使わずにクラウドロールへのアクセスを付与する方法については、OIDC トークンを参照してください。

環境スコープのシークレット

認証情報を、1 つの環境を使用するエージェントだけが利用できるようにしたい場合は、環境スコープのシークレットを使用します。これは、マルチリポジトリ環境、ステージング用の認証情報、またはアクセス要件が異なるリポジトリグループに役立ちます。

環境スコープのシークレットは、その環境内のすべての repo に適用されます。他の環境では利用できません。

サインイン認証情報と 2FA

アプリでログインが必要な場合は、ユーザー名、メールアドレス、パスワードなど、ローカルで使用しているものと同じ認証情報をシークレットとして追加します。

ログインフローで TOTP ベースの 2FA を使用している場合は、shared secret または root secret と呼ばれることもある TOTP シークレットもシークレットとして追加します。エージェントは oathtool --totp -b "$TOTP_SECRET" を使って現在の 6 桁のコードを生成できます。

複数の .env ファイルがあるモノレポ

モノレポに複数の .env.local ファイルがある場合:

  • すべての .env.local ファイルの値を同じSecrets タブに追加します
  • NEXTJS_* や CONVEX_* のようにキーが重複する場合は、重複しない変数名を使用します
  • 必要に応じて、各アプリからそれらの変数を参照します

スナップショットの取得時に .env.local ファイルを含めると、それらが保存され、クラウドエージェントで利用できるようになる場合があります。セキュリティと管理の観点から、Secrets タブを使う方法を引き続き推奨します。

AWS IAM ロールの使用

Cursor は、AWS とより深く連携するために、ユーザーが指定した IAM ロールの引き受けをサポートしています。これにより、長期間有効な認証情報を共有せずに、Cloud Agent に特定の AWS 権限を付与できます。

  1. IAM ロールを作成する: AWS アカウントで、Cloud Agent に引き受けさせたい IAM ロールを作成し、その ARN (例: arn:aws:iam::123456789012:role/acmeRole) を控えておきます。

  2. IAM ロールのシークレットを設定する: Cursor Dashboard → Cloud Agents に移動し、作成した IAM ロールの ARN を値として設定した、CURSOR_AWS_ASSUME_IAM_ROLE_ARN という名前のユーザーまたはチームのシークレットを追加します。

  3. 外部 ID を生成する: これはチーム管理者がチーム設定の Advanced セクションから行う必要があります。Cursor Dashboard → Settings → Advanced に移動し、外部 ID の設定を見つけます。外部 ID が表示されていない場合は、"AWS IAM Role ARN" フィールドに仮の値を入力し、"Validate & Save" をクリックしてページを再読み込みしてください。これにより、チーム用の外部 ID (例: cursor-xxx-yyy-zzz) が生成されます。

  4. IAM ロールの信頼ポリシーを設定する: AWS アカウントで、IAM ロールの信頼ポリシーを更新し、Cursor のロール引受用ロールを信頼するようにします。信頼ポリシーは次のようになります:

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "AllowCursorAssume",      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::289469326074:role/roleAssumer"      },      "Action": "sts:AssumeRole",      "Condition": {        "StringEquals": {          "sts:ExternalId": "cursor-xxx-yyy-zzz"        }      }    }  ]}

cursor-xxx-yyy-zzz を、チーム用に生成された外部 ID に置き換えてください。

環境変数:

設定すると、AWS のツールが cursor-cloud-agent プロファイルを使用するように、Cursor は次の環境変数を設定します。

  • AWS_CONFIG_FILE は Cursor が管理する AWS 設定ファイルを指します
  • AWS_PROFILE は cursor-cloud-agent に設定されます
  • AWS_SDK_LOAD_CONFIG は 1 に設定されます

デフォルトの認証情報チェーンを使用する AWS CLI と AWS SDK は、セットアップコマンドの実行時およびエージェントの実行中に、このプロファイルを自動的に検出します。AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN を自分でエクスポートする必要はありません。

AWS STS の AssumeRoleWithWebIdentity、GCP、Azure、またはその他の OIDC 検証サービスとフェデレーションする場合は、長期間有効なクラウドキーを保存する代わりに、エージェント VM から OIDC トークン を発行します。

environment.json を使ったコードでの設定

環境設定をコードで定義したまま保持したい場合は、.cursor/environment.json をリポジトリにコミットできます。

作る では、環境のデフォルトブランチにある設定が使用されます。フィーチャーブランチで設定を変更する場合は、設定をコミットして push し、そのブランチでエージェントを開始します。Cursor はアクティブな 作る 上で指定されたブランチをチェックアウトし、ブランチで依存関係が変更された場合、エージェントは install コマンドを再実行できます。

スナップショットベースの設定を使用する environment.json の例 (スナップショット ID はダッシュボードの environments ページから確認できます) :

{  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",  "install": "npm install"}

.cursor/Dockerfile (相対パス) と custom_script.sh のインストールスクリプトを参照する .cursor/environment.json のサンプルを以下に示します:

{  "build": {    "dockerfile": "Dockerfile",    "context": ".."  },  "install": "pnpm install && ./custom_script.sh"}

完全なスキーマは こちらで定義されています。

Docker の実行

Cloud Agents は Docker ワークフローをサポートしています。これは、多数のサービスを実行するフルスタックのリポジトリで社内利用しています。

シンプルな構成であれば、Docker をインストールするだけで十分なことがよくあります。docker run hello-world のようなコマンドは、通常、Docker がインストールされていてデーモンが起動していれば動作します。

Cloud Agents では、Docker はさらに別のコンテナレイヤー内で実行されるため、エッジケースがあります。シンプルなワークフローは通常動作します。より複雑な構成では、以下の fuse-overlayfs と iptables-legacy の設定を出発点にしてください。

より複雑な Docker 構成では、fuse-overlayfs、iptables-legacy を使用し、cloud agent 上のユーザーが Docker を実行できることを確認してください。

######################################################### DOCKER INSTALLATION######################################################### Docker をインストールRUN install -m 0755 -d /etc/apt/keyrings && \    curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \    chmod a+r /etc/apt/keyrings/docker.gpg && \    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \    apt-get update && \    apt-get install -y \    docker-ce=5:28.5.2-1~ubuntu.24.04~noble \    docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \    containerd.io \    docker-buildx-plugin \    docker-compose-plugin \    && rm -rf /var/lib/apt/lists/*RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*RUN mkdir -p /etc/docker && \    printf '%s\n' '{' \    '  "storage-driver": "fuse-overlayfs"' \    '}' > /etc/docker/daemon.jsonRUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy######################################################### CONFIG UBUNTU USER######################################################### パスワード認証を無効化するRUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# 非rootユーザーを作成する（存在しない場合のみ）RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# docker グループが存在しない場合は作成し、ubuntu ユーザーを追加するRUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# ubuntu ユーザーにパスワードなしの sudo を設定するRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# ubuntu ユーザーのパスワードを設定するRUN echo "ubuntu:ubuntu" | chpasswd

Tailscale の実行

Cloud agent VM では、Tailscale はデフォルトのネットワークモードで動作しません。代わりに、ユーザースペース ネットワーキングモードを使用してください。

これにより、サービスをパブリックインターネットに公開することなく、tailnet 経由でエージェントからプライベートなサービスやデータストアにアクセスできるようになります。

次のコマンドで tailscaled を起動します:

tailscaled --tun=userspace-networking \  --outbound-http-proxy-listen=localhost:1054 \  --socks5-server=localhost:1055

次に、Tailscale 経由で通信を流したいシェルで、これらのプロキシ変数をエクスポートします:

export ALL_PROXY=socks5h://localhost:1055/export HTTP_PROXY=http://localhost:1054/export HTTPS_PROXY=http://localhost:1054/

その後は、通常どおり tailscale up ... の手順を実行します。

動作するリファレンスが必要な場合は、Docker mode がこのパターンに従っているため、tailscale-orb を問題なく使用できたお客様もいます。

Cloudflare Tunnel の実行

Cloudflare Tunnel は、cloudflared がユーザー空間で動作するため、Cloud Agent VM で利用できます。

Cloud Agent から VPC やイントラネット内のプライベートな HTTP サービスにアクセスする必要がある場合は、この構成を使用します。

  • 自分の環境の Dockerfile またはインストールスクリプトに cloudflared をインストールします。
  • プライベートネットワーク内で cloudflared コネクタを実行します。
  • vpc.example.com のような認証済みの hostname を、トンネル経由でプライベートな origin にルーティングします。
  • 環境で制限付きアウトバウンドを使用している場合は、その hostname を Cloud Agent のネットワーク許可リストに追加します。
  • Cloudflare Access のサービストークンの値は Cursor Secrets に保存します。たとえば、CF_ACCESS_CLIENT_ID と CF_ACCESS_CLIENT_SECRET を使用します。

これにより、Cloud Agent は CF-Access-Client-Id と CF-Access-Client-Secret ヘッダーを付けて、通常の HTTPS 経由でプライベートサービスを呼び出せます。サービスとデータストアは自分のプライベートネットワーク内に留まり、コネクタは Cloudflare へのアウトバウンド接続を確立し、リクエストを自分のプライベートな origin に転送します。コネクタでインバウンドポートを開放する必要はありません。

デー��ベースなどのプライベートな TCP サービスの場合は、Cloudflare TCP Access アプリを設定し、起動コマンドで cloudflared access tcp を実行します。アプリまたはテストコマンドの接続先には、cloudflared が作成するローカルリスナーを指定してください。