Cursor가 2026년 10월 16일 Environments API를 베타로 공개했어요. 클라우드 에이전트가 실행되는 환경을 코드에서 조회하고 관리하는 기능이에요. 팀원이 같은 저장소를 맡겼는데 의존성 설치 결과가 다르다면, 프롬프트를 고치기 전에 각 실행이 어떤 환경 설정을 읽었는지부터 비교해 보세요.
저장소 파일보다 먼저 선택되는 환경
10월 24일에 확인한 공식 설정 문서에는 환경 선택 순서가 나와 있어요. 개인이 저장한 환경이 먼저이고, 그다음은 팀 환경이에요. 둘 다 없을 때 단일 저장소 실행에서 .cursor/environment.json을 찾아요. 저장소의 파일을 고쳤어도 개인 환경이 선택되면 기대한 설정이 적용되지 않을 수 있어요.
저장된 환경이 저장소 파일을 읽는지도 따로 봐야 해요. 문서는 저장 환경의 environment.json 위치가 해당 파일을 가리켜야 한다고 설명해요. 새 환경의 위치가 None이면 저장소 파일 읽기를 건너뛰어요.
파일이 있어도 그 파일을 읽도록 연결했는지는 따로 확인해야 해요.
예를 들어 프런트엔드 저장소의 설치 명령을 수정했는데 에이전트가 이전 명령을 계속 실행한다고 해볼게요. 먼저 개인 환경이 있는지 보고, 선택된 환경이 저장소 파일을 참조하는지 확인해요. 이 순서를 거치면 적용되지 않은 파일을 반복해서 수정하는 일을 줄일 수 있어요. 이 설명은 Cursor가 호스팅하는 Cloud Agents 기준이에요.
목록에서 찾은 뒤 ID로 상세 조회하기
API 문서의 GET /v1/environments는 접근 가능한 저장 환경의 목록을 돌려줘요. repo 필터로 대상 저장소를 좁히고, 응답의 환경 ID를 확인하면 돼요.
팀 환경과 개인 환경의 이름이 비슷할 수 있으니 이름만으로 대상을 정하지 않는 편이 좋아요. 실제 구성은 GET /v1/environments/{id}로 상세 조회해요. 저장소 파일을 참조하면 repoFile에서 저장소와 파일 경로를 볼 수 있고, 저장된 구성은 environmentJson에 담겨요. 두 사람이 받은 환경 ID와 이 값을 나란히 놓으면 무엇을 비교해야 할지 분명해져요.
운영 도구를 붙일 때는 조회 결과를 먼저 보존하고, 바꿀 항목을 정한 뒤 갱신하도록 흐름을 나누는 것을 권해요. 환경 이름을 바꾸는 작업과 설치 설정을 바꾸는 작업은 영향이 달라요. 이름이 맞아 보인다는 이유로 구성까지 덮어쓰지 않도록 요청 본문을 작게 만드는 거예요.
PATCH에 보낸 설정은 전체 교체예요
PATCH /v1/environments/{id}의 environmentJson은 일부 항목을 합치는 패치가 아니에요. 구성 전체를 교체하는 값이에요. 설치 명령만 고치려고 작은 JSON을 보내면 남겨야 할 다른 설정이 빠질 수 있어요. 상세 조회로 받은 현재 구성을 바탕으로 필요한 부분만 편집한 뒤 전체 값을 보내세요.
API의 요청 필드 자체와 그 안의 JSON을 혼동하기도 쉬워요. environmentJson은 JSON으로 인코딩한 문자열이에요. 전송 라이브러리에서 바깥 요청을 직렬화하기 전에 안쪽 구성도 문자열로 준비해야 해요. 문자열 안의 따옴표를 손으로 이어 붙이기보다 사용하는 언어의 JSON 직렬화 함수를 쓰면 형식 오류를 줄일 수 있어요.
또 buildSettings는 환경 이름이나 구성과 별도 요청으로 보내야 해요. 문서는 이 필드들을 한 요청에 함께 넣으면 검증 오류가 난다고 안내해요. 여러 설정을 한꺼번에 정리하는 관리 화면을 만든다면 저장 버튼 뒤에서 요청 범위를 구분할 필요가 있어요.
파일로 관리하는 환경은 파일에서 수정하기
저장소 파일을 구성 원본으로 삼는 단일 저장소 환경은 API로 구성을 교체하려 할 때 잠금 오류를 반환할 수 있어요. 이때 잠금 조건을 우회하려고 다른 환경에 같은 값을 쓰기보다, 상세 조회의 repoFile이 가리킨 파일을 수정하는 경로를 택하세요. 팀이 코드 리뷰로 관리하던 설정을 별도 사본으로 만들지 않게 돼요.
16일 변경 안내는 API의 공개 상태를 베타로 명시했어요. 이를 정식 출시나 모든 설정의 무제한 편집으로 해석하면 안 돼요. 기존 팀 환경을 대상으로 연결할 때는 읽기 요청으로 ID와 구성 원본을 확인하고, 개발용 환경에서 변경 범위를 좁혀 확인한 뒤 적용하는 순서가 적절해요.
참고한 자료
- Cursor 2026-10-16 변경 안내 https://cursor.com/changelog/cloud-agent-canvases-and-environments (확인일 2026-10-24)
- Cursor Cloud Environment Setup https://cursor.com/docs/cloud-agent/setup (확인일 2026-10-24)
- Cursor Cloud Agents API 환경 조회·갱신 https://cursor.com/docs/cloud-agent/api/endpoints (확인일 2026-10-24)