백그라운드 에이전트를 사용해 원격 환경에서 코드를 편집하고 실행하는 비동기 에이전트를 생성해. 상태를 확인하고, 후속 지시를 보내거나, 언제든 직접 넘겨받아 진행할 수 있어.

​
사용 방법

백그라운드 에이전트는 두 가지 방식으로 사용할 수 있어:
  1. Background Agent Sidebar: Cursor 기본 사이드바의 백그라운드 에이전트 탭에서 계정에 연결된 모든 백그라운드 에이전트를 확인하고, 기존 에이전트를 검색하거나 새로 시작할 수 있어.
  2. Background Agent Mode: UI에서 백그라운드 에이전트 모드를 켜려면 를 눌러.
프롬프트를 제출한 뒤 목록에서 에이전트를 선택해 상태를 확인하고 머신에 진입해.

백그라운드 에이전트는 수일간의 데이터 보관이 필요해.

​
설정

백그라운드 에이전트는 기본적으로 격리된 Ubuntu 기반 머신에서 실행돼. 에이전트는 인터넷에 액세스할 수 있고 패키지를 설치할 수 있어.

​
GitHub 연결

백그라운드 에이전트가 GitHub에서 레포를 클론하고 별도 브랜치에서 작업한 다음, 손쉬운 넘겨주기를 위해 네 레포로 푸시해. 레포(종속 레포나 서브모듈 포함)에 읽기/쓰기 권한을 부여해 줘. 다른 제공자(GitLab, Bitbucket 등)는 앞으로 지원할 예정이야.
IP 허용 목록 구성
조직에서 GitHub의 IP 허용 목록 기능을 사용한다면, 백그라운드 에이전트가 접근할 수 있도록 설정해야 해. 연락처 정보와 IP 주소를 포함한 전체 설정 방법은 GitHub 통합 문서를 참고해.

​
기본 환경 설정

더 고급 시나리오에선 직접 환경을 세팅해. 원격 머신에 연결된 IDE 인스턴스를 준비하고, 로컬 머신을 설정해서 툴과 패키지를 설치한 다음 스냅샷을 찍어. 런타임 설정은 이렇게 구성해:
  • Install 커맨드는 에이전트가 시작되기 전에 실행돼서 런타임 의존성을 설치해. 예를 들어 npm install이나 bazel build를 돌릴 수도 있어.
  • Terminals는 에이전트가 작업하는 동안 백그라운드 프로세스를 실행해 — 웹 서버를 띄우거나 protobuf 파일을 컴파일하는 식으로.
가장 고급 케이스에선 머신 설정에 Dockerfile을 써. 이 Dockerfile로 시스템 레벨 의존성을 구성할 수 있어: 특정 컴파일러 버전이나 디버거를 설치하거나, 베이스 OS 이미지를 바꾸는 것까지. 프로젝트 전체를 COPY하진 마 — 워크스페이스는 우리가 관리하고 올바른 커밋을 체크아웃해. 의존성 설치는 여전히 install 스크립트에서 처리해. 개발 환경에 필요한 시크릿을 입력해 — 시크릿은 우리 데이터베이스에 저장 시 암호화(At-rest, KMS 사용)돼 있고, 백그라운드 에이전트 환경에 제공돼. 머신 설정은 .cursor/environment.json에 들어 있어. 이 파일은 레포에 커밋해도 되고(권장), 비공개로 보관해도 돼. 설정 플로우가 environment.json 생성 과정을 안내해 줄 거야.

​
유지 관리 명령

새 머신을 설정할 때는 기본 환경에서 시작한 다음 environment.json의 install 명령을 실행해. 이 명령은 브랜치를 전환할 때 개발자가 실행하는 것과 같아—새 의존성을 설치하는 거지. 대부분은 install 명령이 npm install 또는 bazel build야. 빠른 머신 시작을 위해 install 명령 실행 후 디스크 상태를 캐시해. 여러 번 실행해도 되도록 설계해. 지속되는 건 install 명령으로 인한 디스크 상태뿐이야—여기서 시작한 프로세스는 에이전트가 시작될 때 살아 있지 않아.

​
시작 명령어

install를 실행한 뒤 머신이 올라오면 start 명령어를 실행하고, 이어서 모든 terminals를 시작해. 그러면 에이전트가 돌 때 살아 있어야 하는 프로세스들이 올라가. start 명령어는 보통 생략해도 돼. 네 dev 환경이 Docker에 의존한다면 써 — start 명령어에 sudo service docker start를 넣어. terminals는 앱 코드용이야. 이 터미널들은 너와 에이전트가 함께 쓸 수 있는 tmux 세션에서 실행돼. 예를 들어, 많은 웹사이트 레포는 npm run watch를 터미널로 넣어.

​
environment.json 스펙

environment.json 파일은 다음처럼 생길 수 있어: 
{
  "snapshot": "설정에서 가져옴",
  "install": "npm install",
  "terminals": [
    {
      "name": "Next.js 실행",
      "command": "npm run dev"
    }
  ]
}
공식적으로, 스펙은 여기에서 정의돼 있어.

​
모델

백그라운드 에이전트에선 Max Mode 호환 모델만 쓸 수 있어.

​
가격

Background Agent 가격에 대해 더 알아보기.

​
보안

Background Agents는 개인정보 보호 모드에서 사용할 수 있어. 우린 네 코드로 학습하지 않고, 에이전트를 실행하는 데 필요한 코드만 보관해. 개인정보 보호 모드 자세히 보기. 알아두면 좋은 점:
  1. 수정하려는 리포에 우리 GitHub 앱의 읽기/쓰기 권한을 부여해줘. 이걸로 리포를 클론하고 변경할 수 있어.
  2. 네 코드는 격리된 VM으로 구성된 우리 AWS 인프라에서 실행되고, 에이전트가 동작하는 동안 VM 디스크에 저장돼.
  3. 에이전트는 인터넷에 접근할 수 있어.
  4. 에이전트는 모든 터미널 명령을 자동 실행해서 테스트를 반복할 수 있게 해줘. 이건 모든 명령에 사용자 승인이 필요한 포그라운드 에이전트와 달라. 자동 실행은 데이터 유출 위험을 초래할 수 있어: 공격자가 프롬프트 인젝션 공격으로 에이전트를 속여 악성 웹사이트에 코드를 업로드하게 만들 수 있어. 배경 에이전트에 대한 프롬프트 인젝션 위험에 관한 OpenAI의 설명을 참고해.
  5. 개인정보 보호 모드를 비활성화하면, 제품 개선을 위해 프롬프트와 개발 환경 정보를 수집해.
  6. 백그라운드 에이전트를 시작할 때 개인정보 보호 모드를 비활성화한 뒤, 에이전트 실행 중에 활성화하더라도 완료될 때까지 비활성화 상태로 계속 진행돼.

​
대시보드 설정

워크스페이스 관리자는 대시보드의 Background Agents 탭에서 추가 설정을 변경할 수 있어.

​
기본값 설정

  • 기본 모델 – 실행에서 모델을 지정하지 않았을 때 사용되는 모델. Max Mode를 지원하는 아무 모델이나 골라.
  • 기본 리포지토리 – 비워두면 에이전트가 리포 선택을 요청해. 여기에서 리포를 지정하면 그 단계를 건너뛸 수 있어.
  • 기본 브랜치(Base branch) – 에이전트가 풀 리퀘스트를 만들 때 포크하는 기준 브랜치. 리포지토리의 기본 브랜치를 쓰려면 비워 둬.

​
보안 설정

모든 보안 옵션은 관리자 권한이 필요해.
  • 사용자 제한 – 없음(모든 멤버가 백그라운드 에이전트를 시작할 수 있음) 또는 허용 목록 중에서 선택해. 허용 목록으로 설정하면 어떤 팀원이 에이전트를 만들 수 있는지 정확히 지정할 수 있어.
  • 팀 팔로업 – 켜면 워크스페이스의 누구나 다른 사람이 시작한 에이전트에 팔로업 메시지를 추가할 수 있어. 끄면 팔로업은 에이전트 소유자와 관리자에게만 허용돼.
  • 에이전트 요약 표시 – Cursor가 에이전트의 파일 diff 이미지와 코드 스니펫을 표시할지 제어해. 사이드바에 파일 경로나 코드를 노출하고 싶지 않다면 꺼둬.
  • 외부 채널에 에이전트 요약 표시 – 위 토글을 Slack이나 연결된 외부 채널에도 적용해.
변경 사항은 즉시 저장되고 새 에이전트에 바로 적용돼.