작업 공간

작업 공간은 에이전트가 시작하는 환경입니다. 실행하려는 명령이 포함된 저장소를 복제하고 설치한 상태입니다. defineWorkspace()는 해당 작업 트리를 한 번 설명합니다. 각 하네스 어댑터는 이를 자체 네이티브 형식으로 변환하며, 선택한 provider 내부에서 실행합니다. 이 페이지에서는 작업 트리 자체인 source, packageManager, setup, scripts를 다룹니다. 시크릿, 스킬, MCP 서버는 프로비저닝에서 다룹니다.

import { createSecrets, defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

defineWorkspace({
  // Where the working tree comes from.
  source: githubRepo({ repo: 'owner/repo', ref: 'main' }),
  // Package manager (auto-detected from the lockfile when omitted).
  packageManager: 'pnpm',
  // Commands run once during bootstrap.
  setup: ['corepack enable', 'pnpm install'],
  // Named commands the agent can run.
  scripts: { test: 'pnpm test', build: 'pnpm build' },
  // Injected into the sandbox env at create/resume, never persisted.
  secrets: createSecrets({ XAI_API_KEY: process.env.XAI_API_KEY ?? '' }),
})

필드:

필드	설정하는 값
source	작업 트리의 출처(git 저장소, 로컬 경로 또는 없음)입니다.
packageManager	npm / pnpm / yarn / bun / auto입니다. 기본값은 auto입니다.
setup	부트스트랩 중 한 번 실행되는 명령(직렬 배열 또는 직렬/병렬 그룹)입니다.
scripts	에이전트와 사용자가 이름으로 호출할 수 있는 명령입니다.
secrets	환경에 주입되는 타입이 지정된 시크릿 참조입니다. 프로비저닝을 참고하세요.

defineWorkspace()는 에이전트 환경을 프로비저닝하기 위한 skills, plugins, instructions도 받습니다. 여기에서 중복해 설명하지 않고 프로비저닝에서 다룹니다.

소스

source는 작업 트리의 출처를 지정합니다. 다섯 가지 형태가 있습니다.

import { defineWorkspace, githubRepo, gitSource } from '@tanstack/ai-sandbox'

// Shorthand for a GitHub repo (owner/repo or a full URL).
defineWorkspace({ source: githubRepo({ repo: 'owner/repo', ref: 'main' }) })

// Any git URL.
defineWorkspace({ source: gitSource({ url: 'https://git.example.com/owner/repo.git' }) })

// The same as gitSource, written out as a plain object.
defineWorkspace({ source: { type: 'git', url: 'https://github.com/owner/repo', ref: 'main' } })

// An existing directory on the host (e.g. local-process dev loop).
defineWorkspace({ source: { type: 'local', path: '/abs/path/to/repo' } })

// No working tree: the agent starts in an empty workspace.
defineWorkspace({ source: { type: 'none' } })

githubRepo는 gitSource를 편리하게 감싼 래퍼입니다. 짧은 owner/repo는 https://github.com/owner/repo.git으로 확장되고, 전체 URL은 그대로 사용됩니다. 둘 다 { type: 'git' } 소스를 생성하므로 완전히 제어하려는 경우 해당 객체 리터럴을 직접 작성할 수도 있습니다.

기본값은 얕은 클론

githubRepo와 gitSource는 콜드 스타트를 빠르게 유지하기 위해 기본적으로 얕은 단일 브랜치 클론(--depth 1 --single-branch)을 사용합니다. 특정 기록 깊이를 지정하려면 depth 숫자를 전달하고, 모두 가져오려면 'full'을 전달하세요.

import { defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

// Shallow clone (depth 1) is the default.
defineWorkspace({ source: githubRepo({ repo: 'owner/app' }) })

// Explicit depth: fetches the last 10 commits.
defineWorkspace({ source: githubRepo({ repo: 'owner/app', depth: 10 }) })

// Full history: disables the depth flag entirely.
defineWorkspace({ source: githubRepo({ repo: 'owner/app', depth: 'full' }) })

패키지 관리자

packageManager는 'npm', 'pnpm', 'yarn', 'bun', 또는 'auto'입니다. 기본값은 소스가 배치된 후 lockfile에서 관리자를 감지하는 'auto'입니다. 추론하지 않고 선택을 고정하려면 명시적으로 설정하세요.

설정

setup은 부트스트랩 중 한 번 실행되어 새로 클론한 저장소를 설치된 저장소로 변환합니다. 일반 문자열 배열(각 단계가 직렬로 실행됨) 또는 직렬 및 병렬 그룹을 기록하는 빌더 콜백을 받습니다.

가장 간단한 형태는 배열이며, 모든 단계를 직렬로 실행하는 것과 같습니다.

import { defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

defineWorkspace({
  source: githubRepo({ repo: 'owner/app' }),
  setup: ['corepack enable', 'pnpm install'],
})

콜백은 영속 셸에서 실행됩니다. 단계 사이에 작업 디렉터리와 환경이 이어지므로 직렬 단계의 cd 또는 export가 다음 단계에 표시됩니다. 독립적인 명령을 동시에 실행하려면 parallel([...])을 사용하세요. 명령은 셸의 cwd와 env를 상속하며, 다음 직렬 단계는 모든 명령이 완료될 때까지 기다립니다.

import { defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

defineWorkspace({
  source: githubRepo({ repo: 'owner/app' }),
  setup: ({ serial, parallel }) => {
    // Runs in order on the persistent shell; cwd/env carry over.
    serial('corepack enable')
    serial('pnpm install')
    // Both commands launch concurrently, inheriting cwd + env from the shell.
    parallel(['pnpm build', 'pnpm typecheck'])
    // Runs after both parallel steps complete.
    serial('echo bootstrap done')
  },
})

provider가 스냅샷을 지원하면 부트스트랩이 setup 후 결과를 캐시하므로 이후 실행에서는 이를 건너뜁니다. 수명 주기 및 스냅샷을 참고하세요.

에이전트 CLI 설치

모든 단계는 sh -c를 통해 실행되며, 종료 코드가 0이 아니면 해당 단계가 부트스트랩을 실패시킵니다. 단계에서 하네스 CLI를 전역으로 설치한다면 반환 전에 CLI를 검증하도록 하세요. 에이전트 CLI(@openai/codex, @anthropic-ai/claude-code, …) 플랫폼별 네이티브 바이너리를 optional dependency로 제공하며 npm은 선택적 dependency를 best-effort로 처리합니다. 다운로드 실패는 설치 오류가 아니므로 npm install -g가 0으로 종료되고 나중에 Missing optional dependency와 함께 중단되는 CLI가 남습니다. CLI를 실행하면 망가진 실행을 남기는 대신 이를 명확한 부트스트랩 실패로 전환합니다.

import { defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

const install = 'npm install -g @openai/codex --include=optional && codex --version'

defineWorkspace({
  source: githubRepo({ repo: 'owner/app' }),
  // Retry once: the failure above is usually a transient download.
  setup: [`${install} || { ${install} ; }`],
})

각 명령을 자체 완결형으로 유지하세요. 한 명령을 다른 명령에 이어 붙여 단계를 다른 명령에 이어 붙여 단계를 구성하지 마세요(`${cmd} || sudo ${cmd}`). 서브셸로 시작하는 명령(예: Grok CLI 설치 프로그램인 (curl … || curl …) | bash)은 다른 명령의 유효한 인수가 아니며, sh는 아무것도 실행하지 않은 채 파싱 시점에 syntax error: unexpected "("(종료 코드 2)로 실패합니다.

일부 provider는 non-root 사용자로 실행됩니다. pnpm install 같은 작업 공간 로컬 설치에는 sudo가 필요하지 않습니다. 해당 provider에서 시스템 또는 전역 패키지를 설치하려면 setup에서 대화형 입력이 없는 sudo -n이 필요합니다. pnpm install에는 sudo가 필요하지 않습니다. 해당 provider에서 시스템 또는 전역 패키지를 설치하려면 setup에서 대화형 입력이 없는 sudo -n이 필요합니다. Provider 및 정책을 참고하세요.

스크립트

scripts는 에이전트와 사용자가 매번 전체 명령줄을 다시 작성하지 않고 이름으로 호출할 수 있는 명령 맵입니다.

import { defineWorkspace, githubRepo } from '@tanstack/ai-sandbox'

defineWorkspace({
  source: githubRepo({ repo: 'owner/app' }),
  scripts: {
    test: 'pnpm test',
    build: 'pnpm build',
    typecheck: 'pnpm test:types',
  },
})

이 명령은 자유 형식 셸이 아닌 이름이 지정된 명령으로 제공되므로 정책에서도 허용, 승인 요청 또는 거부에 사용할 안정적인 이름을 얻을 수 있습니다.