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

​
사용 방법

배경 에이전트에는 두 가지 방식으로 접근할 수 있어:
  1. Background Agent Sidebar: 네이티브 Cursor 사이드바의 배경 에이전트 탭에서 계정에 연결된 모든 배경 에이전트를 확인하고, 기존 에이전트를 검색하고, 새 에이전트를 시작할 수 있어.
  2. Background Agent Mode: UI에서 배경 에이전트 모드를 켜려면 를 눌러.
프롬프트를 제출한 다음, 목록에서 에이전트를 선택해 상태를 확인하고 머신에 접속해.

배경 에이전트는 며칠간의 데이터 보존이 필요해.

​
피드백

우리 Discord의 #background-agent 채널이나 background-agent-feedback@cursor.com로 피드백 보내줘. 버그, 기능 요청, 아이디어 모두 환영해.

​
설정

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

​
GitHub 연결

백그라운드 에이전트가 GitHub에서 네 리포를 클론하고 별도 브랜치에서 작업한 뒤, 손쉬운 인수인계를 위해 네 리포로 푸시해. 네 리포(의존 리포나 서브모듈 포함)에 읽기/쓰기 권한을 부여해 줘. 다른 제공자(GitLab, Bitbucket 등)는 앞으로 지원할 예정이야.
IP Allow List 구성
조직에서 GitHub의 IP allow list 기능을 사용 중이라면, 백그라운드 에이전트에 대한 접근을 설정해야 해. 연락처 정보와 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 단계에서 지속되는 건 디스크 상태뿐 — 여기서 시작된 프로세스는 에이전트가 시작될 때 살아 있지 않아.

​
Startup Commands

install를 실행한 뒤 머신이 올라오면 start 명령을 실행하고, 이어서 모든 terminals를 시작해. 이렇게 하면 에이전트가 돌 때 상시 떠 있어야 하는 프로세스들이 켜져. start 명령은 종종 건너뛸 수 있어. dev 환경이 Docker에 의존한다면 써 — start 명령에 sudo service docker start를 넣어. terminals는 앱 코드용이야. 이 터미널들은 너랑 에이전트가 함께 쓸 수 있는 tmux 세션에서 돌아. 예를 들어, 많은 웹사이트 레포는 터미널에 npm run watch를 지정해.

​
environment.json 스펙

environment.json 파일은 다음처럼 생길 수 있어: 
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}
정식 스펙은 여기에 정의돼 있어.

​
모델

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

​
가격

Background Agent 요금에 대해 더 알아봐.

​
Security

Background Agents는 Privacy Mode에서 사용할 수 있어. 우린 네 코드로 학습하지 않고, 에이전트를 실행하는 데 필요한 코드만 일시적으로 보관해. Privacy Mode에 대해 더 알아보기. 알아두면 좋은 점:
  1. 수정하려는 repo에 우리 GitHub 앱의 read-write 권한을 부여해 줘. 이 권한으로 repo를 clone하고 변경해.
  2. 네 코드는 우리 AWS 인프라의 격리된 VM에서 실행되고, 에이전트가 동작하는 동안 VM 디스크에 저장돼.
  3. 에이전트는 인터넷에 접근할 수 있어.
  4. 에이전트는 모든 터미널 명령을 자동 실행해서 테스트를 반복할 수 있게 해. 이건 모든 명령에 사용자 승인이 필요한 foreground agent와 달라. 자동 실행에는 데이터 유출 위험이 따를 수 있어: 공격자가 prompt injection 공격으로 에이전트를 속여 악성 사이트로 코드를 업로드하게 만들 수 있어. 배경 에이전트에서 prompt injection 위험에 대한 OpenAI의 설명을 참고해.
  5. Privacy Mode가 비활성화되어 있으면, 제품 개선을 위해 프롬프트와 개발 환경 정보를 수집해.
  6. Background agent를 시작할 때 Privacy Mode를 비활성화했다가 실행 중에 활성화하더라도, 에이전트는 완료될 때까지 비활성화 상태로 계속 실행돼.

​
대시보드 설정

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

​
기본값 설정

  • 기본 모델 – 실행에서 모델을 지정하지 않았을 때 쓰이는 모델. Max Mode를 지원하는 아무 모델이나 골라.
  • 기본 리포지토리 – 비어 있으면 에이전트가 리포를 선택하라고 물어봐. 여기서 리포를 지정해두면 그 단계를 건너뛸 수 있어.
  • 기본 브랜치 – pull request를 만들 때 에이전트가 fork하는 기준이 되는 브랜치. 비워 두면 리포지토리의 기본 브랜치를 써.

​
보안 설정

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