클라우드 환경 설정

클라우드 에이전트는 격리된 Ubuntu 머신에서 실행됩니다. Agent가 개발자가 사용하는 것과 동일한 리포지토리, 도구, 의존성, 시크릿, 네트워크 액세스를 갖추도록 환경을 설정하세요.

클라우드 에이전트 대시보드에서 새 환경을 생성하세요.

Cloud Agent 환경이란 무엇인가요?

Cloud Agent의 개발 환경은 노트북의 설정과 비슷합니다. 클론된 리포지토리, 설치된 의존성, 시크릿, 시작 명령어, 네트워크 액세스로 구성됩니다.

효과적인 개발 환경은 에이전트에 코드베이스와 조직에 대한 전체 컨텍스트를 제공하므로, 에이전트가 자신의 작업을 테스트하고 검증할 수 있습니다.

환경 설정이 왜 중요한가요?

Agent의 역량은 실행 환경에 따라 달라집니다. 코드는 작성할 수 있어도 테스트를 실행하거나, 서비스를 조회하거나, API에 접근할 수 없는 Agent는 작업을 끝까지 완료할 수 없습니다.

엔지니어링 작업을 처음부터 끝까지 처리하려면 클라우드 에이전트에 모든 리포지토리, 도구, 의존성, 컨텍스트를 갖춘 개발 환경이 설정되어 있어야 합니다. 그래야 자율적으로 작업하며 생산성을 유지할 수 있습니다.

개발 환경은 Agent 세션도 더 빠르게 합니다. Builds는 백그라운드에서 리포지토리, 도구, 의존성을 준비하므로 에이전트가 바로 사용할 수 있는 머신에서 시작합니다.

환경 설정은 클라우드 에이전트의 효과를 높이는 가장 중요한 단계입니다.

환경 설정 옵션

Cloud Agent의 환경을 구성하는 주요 방법은 두 가지입니다.

1. 클라우드 에이전트 대시보드에서 Cursor의 에이전트가 자체적으로 환경을 설정하도록 할 수 있습니다. 에이전트가 의존성을 설치하고 환경을 검증한 후 첫 번째 Build를 생성합니다.
2. Dockerfile을 사용해 환경을 수동으로 구성할 수 있습니다. 이 옵션을 선택하면 .cursor/environment.json 파일에서 Dockerfile을 지정할 수 있습니다.

두 옵션 모두 설치 스크립트를 지정할 수 있습니다. Cursor는 Build를 생성하는 동안 이를 실행하므로 에이전트가 시작되기 전에 의존성이 준비됩니다.

멀티 리포지토리 환경

에이전트가 둘 이상의 저장소에서 작업해야 할 때 멀티 리포지토리 환경을 사용하세요. 환경을 생성할 때 여러 저장소를 선택합니다. Cursor는 선택한 각 리포지토리를 Agent 머신에 클론하고, 동일한 리포지토리 그룹을 사용하는 이후의 에이전트 실행과 자동화에 이 환경을 재사용합니다.

프런트엔드, 백엔드, 인프라, 또는 공유 라이브러리가 각각 별도의 리포지토리에 있을 때 멀티 리포지토리 환경을 사용하세요. Agent는 전체 작업 공간을 살펴보고, 여러 리포지토리에 걸친 변경 사항을 조정해 적용하고, 리포지토리 전반에서 테스트를 실행하고, 변경한 리포지토리에서 풀 리퀘스트를 열 수 있습니다.

활성화된 환경과 이전에 활성 상태였던 모든 버전은 클라우드 에이전트 대시보드의 환경 구성 페이지에서 확인할 수 있습니다.

환경 결정 순서

Cursor는 저장소 또는 리포지토리 그룹별로 환경 설정을 확인하며, 처음 일치하는 항목을 사용합니다:

1. 저장소의 .cursor/environment.json
2. 개인이 저장한 환경
3. 팀이 저장한 환경

이 방식으로 팀 단위에서는 예측 가능한 기본값을 유지하면서도, 저장소 수준의 .cursor/environment.json이 없을 때는 개별 사용자가 개인 환경으로 재정의할 수 있습니다. 사용자 재정의는 새 환경 설정을 전체 팀에 적용하기 전에 미리 시험해 보는 데에도 유용합니다.

Agent로 설정하기(권장)

Cursor는 10분 이내에 클라우드에서 개발 환경을 설정할 수 있습니다. 클라우드 에이전트 대시보드 또는 Cursor 데스크톱 앱의 Agent 창에서 안내형 설정을 시작하세요.

GitHub, GitLab, Azure DevOps 또는 Bitbucket 계정을 연결하고 하나 이상의 저장소를 선택하라는 안내가 표시됩니다.

그런 다음 의존성을 설치하고 코드를 실행하는 데 필요한 환경 변수와 시크릿을 Cursor에 제공하면 됩니다.

Agent가 작업하는 동안 공유 터미널 세션에서 진행 상황을 확인할 수 있으며, Agent는 의존성 설치와 같은 설정 작업을 처리합니다. Cursor는 코드를 검증하고 Build를 성공적으로 완료한 후 환경을 저장합니다.

향후 클라우드 에이전트는 활성 Build에서 시작하며 소프트웨어를 실행해 변경 사항을 테스트할 수 있습니다. 팀 전체가 활용할 수 있도록 구성을 .cursor/environment.json에 커밋하세요.

Dockerfile을 사용한 수동 설정(고급)

고급 사용 사례에서는 Dockerfile로 환경을 설정하세요:

• 시스템 수준 의존성을 설치하거나, 특정 컴파일러 버전을 사용하거나, 디버거를 설치하거나, 베이스 OS 이미지를 변경하려면 Dockerfile을 생성합니다
• 전체 프로젝트를 COPY하지 마세요. 워크스페이스는 Cursor가 관리하며 올바른 커밋을 체크아웃합니다
• 런타임 설정을 구성하려면 .cursor/environment.json을 직접 수정하세요
• 비공개 패키지 레지스트리 또는 빌드 시 자격 증명에는 빌드 시크릿을 사용하세요

다음은 .cursor/Dockerfile(상대 경로)과 custom_script.sh 설치 스크립트를 참조하는 .cursor/environment.json 예시입니다:

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

리포지토리에 Docker, Tailscale 또는 Cloudflare Tunnel이 필요하다면 아래의 Docker 실행, Tailscale 실행 및 Cloudflare Tunnel 실행을 참조하세요.

환경은 Dockerfile로 설정하며, 원격 머신에는 직접 접근할 수 없습니다.

Dockerfile 빌드에는 레이어 캐싱이 사용됩니다. Dockerfile을 변경하면 Cursor는 모든 레이어를 처음부터 다시 빌드하는 대신 변경된 레이어만 다시 빌드합니다.

Cursor가 구성한 Dockerfile (비공개 베타)

Dockerfile을 처음부터 작성하고 싶지 않은 팀의 경우, Cursor가 대신 Dockerfile을 구성해 줄 수 있습니다. 설정 중에 Cursor가 리포지토리를 검사해 도구와 의존성을 파악하고, 직접 편집하고 버전 관리할 수 있는 Dockerfile 기반 환경 구성을 생성합니다.

이 워크플로는 엔터프라이즈 팀을 대상으로 비공개 베타로 제공됩니다. 접근 권한을 요청하려면 Cursor 계정 담당자에게 문의하거나 팀 관리자 계정으로 hi@cursor.com에 이메일을 보내세요.

리소스 한도

각 Cloud Agent는 메모리와 CPU가 제한된 기본 VM 프로필에서 실행됩니다. Enterprise 요금제를 사용 중이고 리포지토리에 더 많은 리소스가 필요하면 지원팀에 문의해 주세요. 워크스페이스의 한도를 늘려 드릴 수 있습니다.

셀프 서비스형 맞춤 리소스 설정 기능은 곧 제공될 예정입니다.

설치 스크립트

설치 스크립트는 이전에는 대시보드와 문서에서 업데이트 스크립트라고 불렸습니다.

Cursor는 Build를 생성할 때 설치 스크립트(environment.json의 install)를 실행합니다. 이 스크립트는 각 에이전트 시작을 지연시키는 대신 백그라운드에서 완료됩니다.

Cursor가 미리 준비할 수 있는 작업에는 install을 사용하세요. 예를 들어 의존성 설치, 코드 생성, 아티팩트 컴파일, 디스크 캐시 예열 등이 있습니다.

Build에서 설치 스크립트를 사용하는 방식

Cursor는 환경의 기본 이미지에서 시작해 리포지토리를 클론하고 install을 끝까지 실행합니다. Build가 성공하면 그 결과로 생성된 디스크 상태가 저장되어 활성화됩니다. 새 에이전트는 활성 Build에서 시작합니다.

스크립트가 모든 설정을 완료하도록 구성하세요. 비용이 많이 드는 설정은 시작 시가 아니라 에이전트 요청 전에 실행되므로 install에 포함해야 합니다. pnpm install 같은 명령은 준비된 상태를 재사용하면서 변경된 의존성만 업데이트할 수 있습니다.

Build는 디스크 상태만 보존합니다. 실행 중인 프로세스, 내보낸 셸 변수, 인메모리 캐시는 에이전트 실행으로 이어지지 않습니다. 서비스는 start 또는 terminals로 시작하세요.

환경 구성 복구

Build에 실패해도 활성 Build는 대체되지 않습니다. 실패 원인을 확인하고 대체 Build를 생성하는 동안 에이전트는 가장 최근에 성공한 환경에서 계속 시작됩니다.

환경의 Builds 탭을 열어 로그를 확인하고, 실패한 Build에서 에이전트를 시작하거나 다른 성공한 Build를 선택하세요. Build 제어 및 디버깅에 대한 자세한 내용은 Cloud Agent Builds를 참조하세요.

설치 스크립트에 포함할 내용 정하기

반복 가능한 모든 준비 단계는 install에 넣으세요. 전체 종속성 설치, 코드 생성, 아티팩트 컴파일, 기타 재사용 가능한 결과를 디스크에 기록하는 작업이 여기에 해당합니다.

장시간 실행되는 프로세스는 install에 넣지 마세요. Docker, 데이터베이스, 터널, 개발 서버는 시작 명령어에 넣으세요. 에이전트가 특정 작업에만 필요한 서비스는 AGENTS.md에 지시를 추가할 수도 있습니다.

시작 명령어

에이전트가 Build에서 부팅된 후, Cursor는 start 명령어를 실행한 다음 설정된 terminals를 실행합니다. 에이전트가 동작하는 동안 계속 실행되어야 하는 프로세스에 사용하세요.

많은 저장소에서는 start를 생략할 수 있습니다. 환경이 Docker에 의존한다면, start 안에 sudo service docker start를 추가하세요.

terminals는 앱 코드 프로세스를 위한 것입니다. 이 터미널들은 사용자와 Agent가 공유하는 tmux 세션 안에서 실행됩니다.

AGENTS.md에 클라우드 전용 지침 추가

클라우드 에이전트는 AGENTS.md 파일을 읽습니다. Cursor Cloud specific instructions와 같은 제목으로, 클라우드 전용 설정 및 테스트를 위한 별도 섹션을 추가하는 것을 권장합니다.

이 섹션의 분량이 많아지면, 특정 작업에 대한 자세한 지시를 담을 수 있는 다른 파일에 대한 참고를 포함하는 것을 권장합니다.

자세한 내용은 AGENTS.md 문서를 참조하세요.

환경 변수와 시크릿

클라우드 에이전트가 실제 개발자처럼 코드를 실행하고 테스트하려면, API 키나 데이터베이스 인증 정보와 같은 환경 변수와 시크릿이 필요한 경우가 많습니다.

권장: Cursor 설정의 Secrets 탭 사용

시크릿을 관리하는 가장 쉬운 방법은 cursor.com에서 하는 것입니다. 이 값들은 cloud agent에 환경 변수로 전달됩니다.

여러 유형의 시크릿에 대한 자세한 내용은 Secrets documentation을 참조하세요. 장기 키 없이 cloud-role 접근 권한을 부여하려면 OIDC 토큰을 참조하세요.

환경별 시크릿

자격 증명을 하나의 환경을 사용하는 Agent만 사용할 수 있어야 한다면 환경별 시크릿을 사용하세요. 멀티 리포지토리 환경, 스테이징 자격 증명 또는 접근 요구 사항이 서로 다른 저장소 그룹에 유용합니다.

환경별 시크릿은 해당 환경의 모든 리포지토리에 적용됩니다. 다른 환경에서는 사용할 수 없습니다.

로그인 자격 증명 및 2FA

앱에 로그인이 필요하다면, 사용자 이름, 이메일, 비밀번호와 같이 로컬에서 사용하는 것과 동일한 자격 증명을 시크릿으로 추가하세요.

로그인 흐름에서 TOTP 기반 2FA를 사용하는 경우, 공유 시크릿 또는 루트 시크릿이라고도 하는 TOTP 시크릿도 시크릿으로 추가하세요. Agent는 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 → 클라우드 에이전트로 이동한 다음, 생성한 IAM 역할의 ARN을 값으로 하는 CURSOR_AWS_ASSUME_IAM_ROLE_ARN라는 이름의 사용자 또는 팀 시크릿을 추가하세요.

3. 외부 ID 생성: 이 작업은 팀 관리자가 팀 설정의 Advanced 섹션에서 수행해야 합니다. Cursor Dashboard → Settings → Advanced로 이동해 External 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로 바꾸세요.

환경 변수:

구성되면 Cursor는 AWS 도구에서 cursor-cloud-agent 프로필을 사용하도록 다음 환경 변수를 설정합니다.

• AWS_CONFIG_FILE은 Cursor가 관리하는 AWS config 파일을 가리킵니다
• AWS_PROFILE은 cursor-cloud-agent로 설정됩니다
• AWS_SDK_LOAD_CONFIG는 1로 설정됩니다

기본 자격 증명 체인을 사용하는 AWS CLI와 AWS SDK는 설정 명령을 실행하는 동안과 Agent가 실행 중일 때 이 프로필을 자동으로 감지합니다. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN을 직접 export할 필요는 없습니다.

AWS STS AssumeRoleWithWebIdentity, GCP, Azure 또는 다른 OIDC 검증자와 연동하려면 장기 Cloud 키를 저장하는 대신 Agent VM에서 OIDC 토큰을 발급하세요.

코드에서 environment.json으로 설정하기

환경 설정을 코드에 정의된 상태로 유지하고 싶다면 .cursor/environment.json을 저장소에 커밋할 수 있습니다.

Build는 환경의 기본 브랜치에 있는 설정을 사용합니다. 기능 브랜치에서 변경 사항을 적용하려면 설정을 커밋하고 푸시한 뒤 해당 브랜치에서 에이전트를 시작하세요. Cursor는 활성 Build 위에 요청한 브랜치를 체크아웃하며, 브랜치에서 의존성이 변경되면 에이전트가 설치 명령어를 다시 실행할 수 있습니다.

스냅샷 기반 설정을 사용하는 environment.json 예시입니다(스냅샷 ID는 대시보드의 environments 페이지에서 확인할 수 있습니다):

{  "snapshot": "snapshot-20260212-00000000-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 Agent는 Docker 워크플로를 지원합니다. Cursor는 여러 서비스를 실행하는 풀스택 리포지토리에서 이를 내부적으로 사용합니다.

간단한 설정이라면 Docker를 설치하는 것만으로도 충분한 경우가 많습니다. docker run hello-world 같은 명령은 일반적으로 Docker가 설치되어 있고 데몬이 실행 중이면 작동합니다.

Docker는 또 다른 컨테이너 레이어 안에서 실행되므로 Cloud Agent에서는 엣지 케이스가 있습니다. 단순한 워크플로는 보통 작동합니다. 더 복잡한 설정은 아래의 fuse-overlayfs 및 iptables-legacy 구성부터 시작하는 것이 좋습니다.

더 복잡한 Docker 설정의 경우 fuse-overlayfs, iptables-legacy를 사용하고, 클라우드 에이전트 사용자가 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# 루트가 아닌 사용자 생성 (존재하지 않는 경우에만)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이 기본 네트워킹 모드로는 작동하지 않습니다. 대신 userspace 네트워킹 모드를 사용하세요.

이렇게 하면 서비스를 공개 인터넷에 노출하지 않고도 에이전트가 tailnet을 통해 비공개 서비스와 데이터 저장소에 접근할 수 있습니다.

다음과 같이 tailscaled를 시작하세요:

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

그런 다음 Tailscale을 통해 트래픽을 보내려는 shell에서 다음 proxy 변수를 export하세요:

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 VMs에서도 작동합니다.

Cloud Agent가 VPC 또는 인트라넷에 있는 비공개 HTTP 서비스에 접근해야 할 때는 다음과 같은 패턴을 사용하세요:

• 환경 Dockerfile 또는 설치 스크립트에 cloudflared를 설치합니다.
• 비공개 네트워크 내부에서 cloudflared 커넥터를 실행합니다.
• vpc.example.com과 같은 인증된 호스트 이름을 터널을 통해 비공개 원본으로 라우팅합니다.
• 환경에서 제한된 외부 네트워크 접근을 사용하는 경우 해당 호스트 이름을 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로 아웃바운드 연결을 설정하고 요청을 비공개 원본으로 전달합니다. 서비스와 데이터 스토어는 비공개 네트워크에 그대로 유지되며, 커넥터에서 인바운드 포트를 열어 둘 필요는 없습니다.

데이터베이스와 같은 비공개 TCP 서비스의 경우 Cloudflare TCP Access 앱을 구성하고 시작 명령에서 cloudflared access tcp를 실행하세요. 앱 또는 테스트 명령이 cloudflared가 생성한 로컬 리스너를 가리키도록 설정하세요.