첫 클라우드 샌드박스 실행하기

첫 클라우드 샌드박스 실행하기 (Run your first cloud sandbox)

Docker Sandboxes TypeScript SDK로 클라우드 샌드박스를 만들고 명령을 실행하고 삭제하는 과정을 따라 해 볼게요.

출처: 문서

본문

참고 (Note): Docker Sandboxes API와 SDK는 실험적(experimental)이에요. 기능, 인터페이스, 동작이 바뀔 수 있어요.

Docker Sandboxes TypeScript SDK로 클라우드 샌드박스를 만들고, 그 안에서 명령을 실행하고, 삭제해요. 이 튜토리얼은 번들된 shell 키트를 사용해 Hello from Docker Sandboxes를 출력해요. 실행에 AI 에이전트나 모델 제공 업체 API 키가 필요하지 않아요.

사전 요구사항 (Prerequisites)

이 튜토리얼을 따라 하려면 다음이 필요해요:

  • 활성 Docker Agentic Platform 구독이 있는 Docker 계정
  • Node.js 20 이상과 npm

프로젝트 만들기 (Create a project)

디렉터리를 만들고 Node.js 프로젝트를 초기화해요:

$ mkdir sandboxes-api-tutorial
$ cd sandboxes-api-tutorial
$ npm init --yes
$ npm pkg set type=module

SDK와 TypeScript 도구를 설치해요:

$ npm install @docker/sandboxes
$ npm install --save-dev tsx typescript @types/node

샌드박스 만들고 사용하기 (Create and use a sandbox)

키트(kit)는 에이전트나 도구용 샌드박스의 이미지와 설정을 제공해요. shell 키트가 이 예시의 환경을 제공해요.

SDK는 기본 small 컴퓨트 크기(2 CPU, 4 GiB 메모리)로 이 키트를 실행해요. 클라우드 컴퓨팅은 여러분의 구독으로 과금돼요. 다른 크기는 Compute sizes and limits 문서를 보세요.

index.ts라는 파일을 다음 코드로 만들어요. 이 프로그램은 로그인을 요청하고, 샌드박스를 만들고, 명령을 실행하고, 샌드박스를 삭제해요.

import { oauth, Sandboxes } from '@docker/sandboxes';

const client = new Sandboxes({
  auth: oauth({
    onVerification({ verificationUriComplete, verificationUri, userCode }) {
      console.log(`Open ${verificationUriComplete ?? verificationUri}`);
      console.log(`Verification code: ${userCode}`);
    },
  }),
});

try {
  const sandbox = await client.kits.launchAndWait('shell');
  console.log('Sandbox:', sandbox.name);

  const result = await sandbox.processes.run(
    { args: ['echo', 'Hello from Docker Sandboxes'] },
    { timeoutMs: 300_000 },
  );
  console.log(result.stdout.trim());

  const latest = await sandbox.refresh();
  const deleting = await latest.delete({ force: true });
  await deleting?.waitUntilDeleted();
  console.log('Deleted', sandbox.name);
} finally {
  await client.close();
}

kits.launchAndWait는 샌드박스를 만들고 실행될 때까지 기다려요. processes.run은 명령을 실행하고 출력을 수집해요. 프로그램은 그다음 샌드박스의 최신 상태를 읽고, 삭제하고, 삭제가 끝날 때까지 기다려요. force 옵션은 샌드박스가 실행 중일 때도 삭제를 허용해요.

SDK는 로그인, 접근 토큰, 샌드박스 연결을 처리해요. 클라이언트를 닫으면 로컬 리소스가 해제돼요.

프로그램 실행하기 (Run the program)

tsx로 프로그램을 실행해요:

$ npx tsx index.ts

출력된 검증 URL을 열고 클라우드 구독이 있는 Docker 계정으로 로그인해요. 로그인 후 프로그램이 계속돼요. 성공하면 Hello from Docker Sandboxes를 출력하고, 그다음 샌드박스 삭제를 확인해요.

CI 작업이나 그 밖의 무인 애플리케이션에서는 PAT 인증을 사용하세요.

프로그램이 샌드박스 이름을 출력한 뒤 멈춘다면, client.get(name)으로 샌드박스를 가져와 작업이 끝나면 삭제하세요. 클라이언트를 닫는 것은 샌드박스를 삭제하는 게 아니에요.

다음 단계 (Next steps)

  • 애플리케이션에서 쓸 수 있는 예시를 SDK 쿡북에서 살펴보세요.
  • 저장소를 클론하거나 도구를 설치하는 키트를 쓴다면, 결과를 사용하기 전에 키트 설정이 끝날 때까지 기다리세요.
  • 리소스 이름, 수명 주기 상태, 지원되는 Cloud 옵션을 API concepts 문서에서 읽어보세요.
  • 복구 로직을 추가하기 전에 Errors and retries를 확인하세요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.