샌드박스 개요

A 샌드박스는 코딩 에이전트가 작업할 실제 컴퓨터, 즉 파일 시스템, 셸, 프로세스, 복제된 저장소를 제공합니다. chat()을 통해 Grok Build와 같은 하네스 어댑터(코딩 에이전트 CLI)를 샌드박스에 지정하면 에이전트의 작업(편집, 명령, 도구 호출)이 다른 채팅 실행과 마찬가지로 다시 스트리밍됩니다.

같은 코드가 노트북, CI, Docker 컨테이너 또는 엣지에서 실행됩니다. 프로바이더만 변경됩니다.

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import {
  createSecrets,
  defineSandbox,
  defineWorkspace,
  githubRepo,
  withSandbox,
} from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
import { messages, threadId } from './chat-context'

const repoSandbox = defineSandbox({
  id: 'repo-agent',
  provider: dockerSandbox({ image: 'node:22' }),
  workspace: defineWorkspace({
    source: githubRepo({ repo: 'TanStack/ai' }),
    packageManager: 'pnpm',
    setup: ['corepack enable', 'pnpm install'],
    scripts: { test: 'pnpm test', typecheck: 'pnpm test:types' },
    secrets: createSecrets({
      XAI_API_KEY: process.env.XAI_API_KEY ?? '',
    }),
  }),
  lifecycle: { reuse: 'thread', snapshot: 'after-setup', keepAlive: '30m' },
})

chat({
  threadId,
  adapter: grokBuildText('grok-build'),
  messages,
  middleware: [withSandbox(repoSandbox)],
})

같은 패키지의 sbxSandbox()는 Docker Sandboxes microVM에서 에이전트를 실행합니다. 프로바이더를 참조하세요.

세 가지 구성 요소

샌드박스 실행은 서로 독립적인 세 가지 요소의 조합입니다. 다른 요소를 건드리지 않고 어느 하나든 변경할 수 있습니다.

구성 요소	설명	선택 방법
프로바이더	에이전트가 실행되는 곳(호스트, 컨테이너, microVM, 클라우드 VM)입니다.	프로바이더 패키지(`dockerSandbox`, `sbxSandbox`, `localProcessSandbox`, …)
워크스페이스	에이전트가 보는 것, 즉 소스 저장소, 패키지 관리자, 설정 명령, 시크릿입니다.	`defineWorkspace({ … })`
하네스 어댑터	실행할 에이전트와 출력을 채팅 청크로 변환하는 방식입니다.	`grokBuildText`, `claudeCodeText`, `codexText`, `opencodeText` 또는 모든 ACP 에이전트를 위한 `acpCompatible`

defineSandbox()는 프로바이더와 워크스페이스(선택적 정책, 수명 주기, 훅 포함)를 재사용 가능한 정의로 결합합니다. withSandbox(definition)은 실행에 샌드박스를 활성화하는 chat() 미들웨어입니다.

프로바이더는 에이전트가 실행되는 곳이지 로그인 방식이 아닙니다. 기본 authMode는 'api-key'입니다. 시스템에 이미 CLI 로그인이 있으면 'host'로 설정합니다. 하네스 인증을 참조하세요.

실행 방식

chat({ adapter: grokBuildText(), middleware: [withSandbox(repoSandbox)] })
  │
  ├─ withSandbox.setup    → ensure the sandbox: resume → restore snapshot → create + bootstrap
  ├─ adapter.chatStream   → spawn `grok` INSIDE the sandbox; stream its events back as AG-UI chunks
  └─ withSandbox.onFinish → snapshot / destroy per the lifecycle

하네스 어댑터는 requires: [SandboxCapability]를 선언하므로 샌드박스를 제공하는 미들웨어가 없으면 chat()이 호출 위치에서 즉시 실패합니다. 실행할 곳이 없는 상태로 코딩 에이전트를 실수로 실행할 수 없습니다.

샌드박스를 사용하는 경우

에이전트가 실제 코드베이스에 대해 이야기만 하는 것이 아니라 직접 작업하게 하려면 샌드박스를 사용합니다. 대표적인 형태는 다음과 같습니다.

CI 이슈 분류 / 버그 수정 봇. 새 이슈가 등록되면 저장소를 샌드박스에 복제하고, 에이전트가 재현 및 원인 분석을 수행한 뒤 결과(또는 수정안 초안)를 게시합니다.
PR 리뷰 자동화. 브랜치를 체크아웃하고 테스트/린트 스크립트를 실행한 뒤, 에이전트가 발견한 내용을 댓글로 남기게 합니다.
빌드 및 미리보기. 에이전트에게 앱의 스캐폴딩 또는 수정을 요청하고 샌드박스 안에서 개발 서버를 실행한 다음 사용자에게 라이브 미리보기 URL을 제공합니다. Cloudflare 가이드와 examples/sandbox-*-web 앱을 참조하세요.
Eval / 벤치마크 하네스. 알려진 버그가 있는 픽스처 저장소에서 코딩 에이전트를 실행하고, 격리된 환경에서 재현 가능하게 결과 diff를 검증합니다.
대화형 코딩 코파일럿. 제안만 하는 것이 아니라 실제로 코드를 실행하고 파일을 편집하며 명령을 실행해야 하는 경우에 사용합니다.

모델이 이미 메모리에 있는 코드만 읽으면 된다면 샌드박스가 필요하지 않으며, 도구를 사용하는 일반 chat()이면 충분합니다. 에이전트에 파일 시스템과 셸이 필요한 순간 샌드박스가 유용해집니다.

다음 단계

빠른 시작에서는 노트북의 샌드박스에서 에이전트가 버그를 수정하게 합니다. 그다음 필요한 요소를 선택하세요.

프로바이더: 로컬 프로세스, Docker 컨테이너, Docker Sandboxes (sbxSandbox), Daytona, Vercel, Sprites 및 각 프로바이더가 할 수 있는 작업입니다.
하네스: 실행할 에이전트를 선택합니다. Grok Build, Claude Code, Codex, OpenCode 또는 모든 ACP 에이전트를 사용할 수 있습니다.
하네스 인증: 호스트 CLI 로그인 또는 API 키입니다. 샌드박스 유형이 이를 선택하지는 않습니다.
워크스페이스: 소스 저장소, 복제 깊이 및 설정 명령입니다.
도구: 앱의 자체 도구를 샌드박스 내부의 에이전트에 연결합니다.
정책: 에이전트가 실행할 수 있는 항목에 대한 허용, 확인 또는 거부 가드레일입니다.
수명 주기 및 스냅샷: 샌드박스 재사용, 설정 후 스냅샷 생성 및 재개입니다.
이식 가능한 스냅샷: 샌드박스가 삭제된 후에도 완료된 파일을 유지합니다. 새로 고침 후 파일 유지부터 시작하세요. 일부 파일만 유지하려면 유지할 파일 선택을 참조하세요.
인스턴스 내구성: 복제본 간에도 샌드박스를 재사용합니다.
내구성 있는 실행: 실행이 탭보다 오래 지속되도록 활성화합니다.
이벤트: 에이전트의 편집과 도구 호출을 UI로 스트리밍하고 저장할 항목을 선택합니다.

사이드바의 고급 그룹에는 저널 파일, 다른 호스트에서의 인계, 정리 스위퍼, 프로비저닝, 관측성, Cloudflare, 어댑터 구축 방법이 나머지 내용으로 제공됩니다.

사용해 보기

실행 가능한 데모 세 가지입니다.

examples/sandbox-web: 영속 실행이 연결된 Docker 기반의 "앱을 만들어 주세요" 에이전트입니다. 앱을 스캐폴딩하고 개발 서버를 실행한 뒤 라이브 미리보기 URL을 반환합니다. 새로 고침과 탭 닫기 후에도 실행이 유지되며 Stop은 실제 취소로 동작합니다.
examples/sandbox-cloudflare: UI에서 실행마다 하네스를 선택하는 동일한 방식을 엣지에서 보여줍니다.
examples/ts-react-chat 의 /repo-report: TanStack/ai를 복제하고 하네스와 Auth(host 또는 api-key)를 선택한 뒤 useChat().final에서 타입이 지정된 보고서를 읽습니다. 하네스 에이전트를 참조하세요.

세 가지 구성 요소​

실행 방식​

샌드박스를 사용하는 경우​

다음 단계​

사용해 보기​

세 가지 구성 요소

실행 방식

샌드박스를 사용하는 경우

다음 단계

사용해 보기