키트로 에이전트 실행하기

키트는 에이전트의 이미지와 구성을 제공해요. 도구와 그것이 필요한 설정을 포함하죠. 키트를 실행하면 모든 애플리케이션에서 그 설정을 조립하지 않아도 되는 반복 가능한 시작점을 얻을 수 있어요.

출처: 문서

본문

인증된 클라이언트로 시작하세요. 에이전트 워크로드에는 모델 제공자용 자격 증명도 필요해요. Docker 인증은 샌드박스에 대한 접근을 주지, Anthropic, OpenAI, 또는 다른 에이전트 제공자에 로그인하게 해 주지는 않아요.

사용 가능한 키트 발견

설치된 SDK에 번들된 키트를 나열해요. 실행할 때 항목의 이름을 사용하세요. 카탈로그를 나열해도 샌드박스는 만들어지지 않아요.

SDK의 이름별 실행 헬퍼에는 다음 시작점이 포함돼요:

키트 이름	환경
`claude`	Claude Code
`codex`	Codex
`cursor`	Cursor
`devin`	Devin
`docker-agent`	Docker Agent
`gemini`	Gemini CLI
`opencode`	OpenCode
`shell`	자체 명령을 위한 셸 환경

카탈로그 결과를 설치된 버전의 목록으로 사용하세요. SDK를 업그레이드하면 번들 키트가 업데이트될 수 있어요.

핵심 코드:

return client.kits.list();

완전한 TypeScript 예시: kits/catalog.ts

import type { Sandboxes } from '@docker/sandboxes';

export function listKits(client: Sandboxes) {
  return client.kits.list();
}

키트 실행

Claude Code를 실행하려면 claude를 선택하고 Anthropic API 키가 담긴 저장된 anthropic 시크릿을 첨부하세요. 먼저 제공자 자격 증명을 저장한 다음 저장된 시크릿의 리소스 이름을 실행 예시에 전달하세요. 자격 증명을 명령 인자와 일반 환경 값에 넣지 마세요.

카탈로그 이름, 표시 이름, 에이전트가 필요로 하는 저장된 시크릿 이름을 전달하세요. 예시는 Small(2 vCPUs, 4 GiB)을 선택하고 실행-후-대기(launch-and-wait) 헬퍼를 사용해 하나의 마감 안에서 실행 중인 샌드박스를 반환해요. Small은 키트 리소스를 생략할 때의 기본값이기도 해요. 다른 선택지는 compute sizes 문서를 참고하세요.

수락된 핸들을 즉시 원하고 별도로 기다릴 것이라면 launch를 사용하세요. 대기가 실패하면 다른 것을 실행하기 전에 오류가 보존한 수락된 샌드박스를 검사하세요.

launchAndWait()는 샌드박스가 running 상태에 도달할 때까지 기다려요. 그 시점에 키트가 여전히 도구를 설치하거나 저장소를 클론하고 있을 수 있어요. SDK에는 모든 키트 설정이 끝날 때까지 기다리는 헬퍼가 없어요.

작업이 그 설정에 의존한다면 시작하기 전에 필요한 결과를 확인하세요. 예를 들어 키트가 저장소 클론 후 완료 마커를 쓰거나, 서비스가 헬스 체크를 노출할 수 있어요. 체크 사이에 지연을 두고 타임아웃을 걸어 폴링하세요. 그래야 실패한 설정이 애플리케이션을 무한정 기다리게 하지 않아요.

실행 헬퍼는 번들 카탈로그가 반환한 이름만 받아들이지, 커뮤니티 저장소 URL이나 레지스트리 참조는 받지 않아요. 계정 네트워크 정책은 여전히 키트 샌드박스에 적용돼요.

스크립트, 빌드, 또는 자체 실행 파일을 위한 환경이 필요하면 shell을 사용하세요. 컨테이너 이미지를 직접 사용하려면 자체 컨테이너 이미지 실행 문서를 참고하세요.

핵심 코드:

return client.kits.launchAndWait(kitName, {
  displayName,
  resources: 'small',
  storage: { secrets },
});

완전한 TypeScript 예시: kits/launch.ts

import type { Sandboxes } from '@docker/sandboxes';

export async function launchKit(
  client: Sandboxes,
  kitName: string,
  displayName: string,
  secrets: string[] = [],
) {
  return client.kits.launchAndWait(kitName, {
    displayName,
    resources: 'small',
    storage: { secrets },
  });
}

에이전트 실행

실행 예시가 반환한 샌드박스 핸들과 프롬프트를 run 헬퍼에 전달하세요. claude -p를 실행하고 응답을 기다려요. 키트만 실행한다고 에이전트 작업이 제출되지는 않아요.

예시는 캡처된 출력과 종료 코드를 반환해요. 에이전트 실패를 진단할 때 둘 다 확인하세요. 긴 작업은 출력을 스트리밍하고, 터미널에서 대화는 인터랙티브 세션을 여세요.

나중에 작업을 재개할 것이라면 샌드박스 이름을 저장하세요. 파일이나 실행 중인 프로세스가 더 이상 필요 없으면 샌드박스를 삭제하세요.

핵심 코드:

return sandbox.processes.run(
  { args: ['claude', '-p', prompt] },
  { timeoutMs: 300_000 },
);

완전한 TypeScript 예시: kits/run.ts

import type { Sandbox } from '@docker/sandboxes';

export async function runKitAgent(sandbox: Sandbox, prompt: string) {
  return sandbox.processes.run(
    { args: ['claude', '-p', prompt] },
    { timeoutMs: 300_000 },
  );
}

더 넓은 키트 카탈로그 탐색

커뮤니티 키트 카탈로그에는 Aider, Amp, Copilot, Kiro, OpenHands 같은 에이전트와 개발 도구, 브라우저 자동화, 소스 제어, 보안 스캔이 포함돼요. 예를 들어 Code Server는 브라우저 기반 편집기를, Playwright는 브라우저 자동화를 추가해요.

일부 키트는 완전한 샌드박스 환경을 정의하고, 다른 키트는 기존 에이전트 환경에 도구나 구성을 추가해요. 이 모두가 번들 SDK 실행 대상은 아니에요. 카탈로그 사용법은 Docker kits 가이드를 참고해 주세요.

키트로 에이전트 실행하기