개요
Sandcastle은 TypeScript 라이브러리로, 격리된 샌드박스에서 AI 코딩 에이전트를 실행할 수 있으며 Docker, Podman 및 Vercel을 내장 지원합니다. 샌드박스, 브랜치 및 병합 커밋을 처리하는 프로그래밍 API를 제공하며, 병렬 에이전트 실행 및 리뷰 파이프라인을 지원합니다.
README 미리보기
\n \n \n \n \n \n\n\n## What Is Sandcastle?\n\nA TypeScript library for orchestrating AI coding agents in isolated sandboxes:\n\n1. You invoke agents with a single `sandcastle.run()`.\n2. Sandcastle handles sandboxing the agent with a configurable branch strategy.\n3. The commits made on the branches get merged back.\n\nSandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.\n\n## Prerequisites\n\n- [Git](https://git-scm.com/)\n- A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:\n - [Docker Desktop](https://www.docker.com/) — most common for local development\n - [Podman](https://podman.io/) — rootless alternative to Docker\n - [Vercel](https://vercel.com/) — cloud-based Firecracker microVMs via `@vercel/sandbox`\n - Or [create your own](#custom-sandbox-providers) using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`\n\n## Quick start\n\n1. Install the package:\n\n```bash\nnpm install --save-dev @ai-hero/sandcastle\n```\n\n2. Run `sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.\n\n```bash\nnpx sandcastle init\n```\n\n3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).\n\n```bash\ncp .sandcastle/.env.example .sandcastle/.env\n```\n\n4. Run the `.sandcastle/main.ts` (or `main.mts`) file with `npx tsx`\n\n```bash\nnpx tsx .sandcastle/main.ts\n```\n\n```typescript\n// 3. Run the agent via the JS API\nimport { run, claudeCode } from "@ai-hero/sandcastle";\nimport { docker } from "@ai-hero/sandcastle/sandboxes/docker";\n\nawait run({\n agent: claudeCode("claude-opus-4-7"),\n sandbox: docker(), // or podmanFAQ (3)
how_tosandcastle에서 여러 프롬프트에 걸쳐 agent conversation을 계속하는 방법은?
run()에서 반환된 RunResult 객체의 resume(prompt) 메서드를 사용하세요. 예: const r = await run({ agent: claudeCode('claude-opus-4-6'), sandbox: docker(), prompt: 'draft a plan' }); await r.resume('now execute the plan');. 이렇게 하면 전체 컨텍스트와 함께 에이전트 세션이 계속되므로 sessionId를 수동으로 전달할 필요가 없고 샌드박스 재구축을 피할 수 있습니다. @ai-hero/sandcastle에서 사용 가능합니다.
문제 해결createSandbox를 동일한 브랜치에 대해 여러 번 실행할 때 왜 오래된 브랜치를 유지하나요?
샌드박스는 첫 번째 실행에서 브랜치의 로컬 클론을 재사용하므로, 이후 실행에서 최신 변경 사항을 가져오지 않습니다. 해결 방법: onSandboxReady 훅을 추가하여 워크스페이스 내에서 git pull origin <branch>를 실행하십시오.
문제 해결@ai-hero/sandcastle에서 셸 확장이 타임아웃될 때 'PromptExpansionTimeoutError'가 전체 실행을 중단시키는 문제를 어떻게 해결하나요?
프롬프트 내의 셸 명령어에 재시도 래퍼를 적용하세요. 예를 들어, !\\gh api graphql ...\\`를 !\\for i in 1 2 3; do gh api graphql ... && break; sleep 2; done\\`로 대체하세요. 이는 토큰 캐시 경합이나 API 중단과 같은 일시적인 오류를 처리합니다. 상위 라이브러리에서 네이티브 재시도를 추가할 때까지(issue #617 추적), 이 수동 루프는 단일 시간 초과로 인해 AFK 실행이 중단되는 것을 방지합니다. 경합이 지속되면 병렬 샌드박스 에이전트를 줄이세요.