Cursor Cookbook 소개
Cursor Cookbook은 Cursor 팀이 직접 운영하는 공식 예제 저장소로, "small examples for building with Cursor" 라는 한 줄로 자기 위치를 정의합니다. 코딩 에이전트를 자체 앱·스크립트·워크플로에서 호출하는 Cursor SDK와, AWS 같은 고객 관리 인프라 위에 에이전트 워커를 띄우는 Cloud Agents 두 축을 실습 가능한 형태로 모아 둔 자료입니다.
Cursor Cookbook이 다루는 두 영역은 서로를 보완합니다. Cursor SDK는 같은 에이전트를 로컬 워크스페이스와 클라우드 런타임 모두에서 같은 인터페이스로 다룰 수 있도록 해 주고, Cloud Agents 쪽은 그 에이전트를 사용자가 직접 통제하는 인프라 위에서 돌리기 위한 배포 레퍼런스를 제공합니다. 결과적으로 "Cursor의 에이전트를 어떻게 코드로 부르고, 어디에서 돌릴지" 라는 두 질문에 한 번에 답하는 구조입니다.
본 게시물에서는 Cursor Cookbook에 포함된 셀프 호스팅 Cloud Agents 예제, Cursor SDK 예제 다섯 가지, 그리고 실행에 필요한 사전 준비를 정리합니다.
Cursor Cookbook의 SDK 예제 한눈에 보기
저장소의 SDK 예제 중 가장 정교한 DAG task runner 가 동작하는 모습으로, 작업이 PENDING → RUNNING → FINISHED 로 흐르는 동안 Cursor Canvas가 매 상태 변경마다 핫리로드되며 각 노드의 토큰 출력이 라이브로 들어옵니다. Cursor SDK가 단순히 한 번 호출하고 끝나는 API가 아니라, 실행 이벤트를 스트리밍하면서 결과를 IDE 안에서 시각화할 수 있도록 설계됐다는 점을 한 장면에 압축해 보여 줍니다.
Cursor Cookbook의 셀프 호스팅 Cloud Agents 예제
저장소의 self-hosted-cloud-agent 디렉토리는 Cursor Cloud Agent 워커를 고객 관리 AWS 인프라 위에서 돌리기 위한 레퍼런스를 제공합니다. Cursor는 오케스트레이션·모델 추론·Cloud Agents UI를 그대로 책임지고, 워커만 사용자의 환경 안에서 저장소를 클론하고 명령을 실행하고 빌드/테스트를 돌리고 내부 서비스를 호출합니다. 워커는 Cursor 쪽으로 아웃바운드 HTTPS 연결만 사용하므로 워커에 대한 인바운드 접근을 열어 줄 필요는 없습니다.
배포 옵션은 세 가지로 명시되어 있고, 각각 일반 README(아키텍처·트레이드오프·검증·트러블슈팅) 와 구현 README(복사 붙여넣기용 셋업 명령) 가 짝지어 제공됩니다.
- EC2 + Docker: 한 호스트에서 워커 컨테이너 하나만 띄우는 가장 작은 풋프린트
- ECS/Fargate: CloudWatch 메트릭과 ECS Service Auto Scaling을 활용하는 AWS 네이티브 경로
- EKS + Helm: Cursor의 worker-set 컨트롤러와
WorkerDeployment리소스를 사용하는 쿠버네티스 경로
세 예제는 각자의 보안·네트워크·과금 정책 안에서 Cursor Cloud Agent를 어떻게 띄울지 판단할 때 시작점으로 사용하기 좋습니다.
Cursor Cookbook의 Cursor SDK 예제 다섯 가지
Cursor SDK는 TypeScript API로, 같은 에이전트를 로컬 워크스페이스와 클라우드 런타임에서 동일하게 다룰 수 있게 해 줍니다. 실행 이벤트를 스트리밍으로 받으며, 프롬프트·모델·취소·아티팩트·대화 상태를 모두 코드에서 관리할 수 있습니다. SDK 섹션은 다섯 개의 예제 디렉토리로 구성됩니다.
Quickstart
로컬 에이전트를 하나 만들고, 하드코딩된 프롬프트 한 번을 보낸 뒤 어시스턴트 텍스트를 stdout으로 스트리밍하고 실행이 끝날 때까지 기다리는 최소 Node.js 예제입니다. Node.js 22 이상이 필요하며 pnpm install → pnpm dev 한 흐름으로 돌아갑니다. SDK가 어떻게 호출되는지 가장 짧게 보고 싶을 때 출발점이 됩니다.
Prototyping tool (app-builder)
샌드박스 클라우드 환경에서 새 프로젝트를 스캐폴딩하고 아이디어를 반복 검증하기 위한 웹 앱입니다. 로컬 Cursor 에이전트 세션을 열고, 핫 리로드되는 React 미리보기 앱을 만들어 채팅 UI로 그 앱을 수정해 나가는 엔드 투 엔드 앱 빌딩 루프를 시연합니다. API 키는 처음 실행할 때 한 번 받아 ~/.app-builder/settings.json 에 로컬 저장합니다.
Kanban board (agent-kanban)
Cloud Agents를 위한 Linear 스타일 칸반 보드입니다. Cursor SDK로 클라우드 에이전트 목록을 받아 와서 상태·저장소·브랜치·생성일 단위로 그룹화하고, 카드에 PR 링크와 아티팩트 미리보기를 띄우며, Agent.create({ cloud: { repos } }) 로 새 에이전트를 만드는 흐름까지 한 화면에서 보여 줍니다. 아티팩트 미리보기는 로컬 API 라우트를 통한 인증된 프록시로 가져옵니다.
Coding agent CLI
워크스페이스에 대고 Cursor SDK 에이전트를 돌리는 터미널 도구입니다. 인자로 프롬프트를 한 번에 던지는 원샷 모드는 기본적으로 로컬 런타임을 쓰고, 인자를 비우면 OpenTUI 기반의 인터랙티브 TUI가 떠서 로컬과 클라우드 실행을 그 자리에서 전환하거나 모델을 고르거나 세션을 리셋할 수 있습니다. OpenTUI의 네이티브 렌더러를 bun:ffi 로 노출하기 때문에 Bun 1.3 이상이 필요합니다.
DAG task runner
작업을 JSON DAG로 분해해 각 노드를 Cursor SDK 로컬 서브에이전트로 위상 정렬 순서대로 실행하고, 실행 상태를 Cursor Canvas 의 .canvas.tsx 파일로 라이브 스트리밍하는 예제입니다. 의존성이 없는 노드는 같은 랭크에 묶여 Promise.all 로 동시 실행되고, 자식 노드의 프롬프트에는 부모 노드 결과의 앞부분 약 2,000자가 자동으로 이어 붙습니다. 타임아웃은 노드를 ERROR 로 마킹해 행을 막고, 다운스트림은 자동으로 스킵되며, SIGINT/SIGTERM 은 진행 중인 서브에이전트를 취소한 뒤 캔버스를 마무리합니다. 단순한 실행 예제일 뿐 아니라 .cursor/skills/dag-task-runner 경로에 그대로 복사해 쓸 수 있는 Cursor 스킬로도 함께 제공됩니다.
Cursor Cookbook 사전 준비
SDK 예제를 실행하려면 Cursor integrations dashboard 에서 Cursor API 키를 발급받아 CURSOR_API_KEY 환경 변수로 설정해야 합니다. 패키지 매니저는 대부분 pnpm 을 사용하며, coding-agent-cli 만 bun 을 요구합니다. 자세한 API 사양과 사용 패턴은 Cursor SDK TypeScript 공식 문서 에 정리되어 있습니다.
더 읽어보기
- Cursor SDK TypeScript 공식 문서 — 본 저장소 예제들의 API 레퍼런스
- Cursor Cloud Agents 안내 — Self-hosted 예제의 상위 개념
- Cursor Canvases 문서 — DAG task runner가 라이브 스트리밍하는 대상
- Cursor integrations dashboard —
CURSOR_API_KEY발급 경로
Cursor Cookbook 공식 문서
Cursor Cookbook 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 