Docker Sandboxes API 개념

Docker Sandboxes API 개념

애플리케이션은 Docker Sandboxes API를 사용해 샌드박스를 만들고, 연결하고, 그 상태를 추적해요. 샌드박스의 환경을 선택한 다음, 수명 주기 전체에서 리소스로 작업하는 방법을 배워 봐요.

출처: 문서

본문

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

키트와 샌드박스 이미지

샌드박스 키트(sandbox kit)는 이미지, 설정, 네트워크 규칙, 자격 증명 요구 사항을 포함해 에이전트나 도구를 위한 환경을 정의해요. SDK는 이름으로 실행할 수 있는 키트 카탈로그를 번들로 제공해요. 다른 소스의 키트를 사용하려면 그 콘텐츠를 API용으로 준비해야 해요.

컨테이너 이미지에서 샌드박스를 만들 수도 있어요. 환경을 얼마나 직접 구성할지에 따라 소스를 선택하세요:

imageRef 값은 레지스트리의 이미지 이름이에요. image 값은 Sandboxes API가 반환하는 리소스 이름이에요. image를 사용할 때는 resources를 생략하세요. 이미지 리소스가 컴퓨트 설정을 제공하기 때문이에요.

이 생성 메서드들은 샌드박스가 실행 중일 때까지 기다리지 않아요. 명령을 실행하기 전에 작업이 끝날 때까지 기다리는 방법을 참고하세요.

번들 키트

npm 패키지에는 다음 키트 정의와 지원 파일이 포함돼요. shell 같은 짧은 이름으로 번들 키트를 실행해요:

예를 들어 client.kits.launchAndWait('shell')은 셸 샌드박스를 만들고 실행될 때까지 기다려요. 키트 실행 헬퍼는 기본적으로 small 컴퓨트(2 CPU, 4 GiB 메모리)를 사용해요. 다른 크기를 선택하려면 Compute sizes 문서를 참고하세요.

번들 키트는 SDK 릴리스에 묶여 있어요. client.kits.list()를 호출해 설치된 버전의 카탈로그를 확인하세요. 키트 정의가 npm 패키지에 포함되어 있으므로 SDK는 레지스트리에서 다운로드하지 않아요. Cloud Sandboxes는 참조된 컨테이너 이미지를 필요할 때 풀해요.

AI 에이전트를 실행하려면 Anthropic API 키 같은 모델 제공자 자격 증명을 제공하세요. 에이전트 인증 문서를 참고해 주세요. shell 키트는 명령을 실행하는 데 제공자 키가 필요 없어요.

리소스 이름

이후 요청에서 리소스를 참조하려면 반환된 name을 사용하세요. 샌드박스 이름은 sandboxes/<uid> 형태예요. 읽거나 삭제할 때 sandboxes/ 접두사를 포함한 전체 이름을 전달하세요.

서버가 이름을 할당하며 리소스의 수명 내내 유지돼요. 선택적인 displayName은 리소스의 정체성을 바꾸지 않고 변경할 수 있는 레이블이에요.

작업이 끝날 때까지 기다리기

명령을 보내기 전에 샌드박스가 실행 중일 때까지 기다리세요. SDK에서 client.kits.launchAndWait()는 번들 키트의 샌드박스를 만들고 실행될 때까지 기다려요. client.create()나 client.kits.launch()를 사용한다면 반환된 샌드박스에서 waitUntilRunning()을 호출하고 그 결과로 명령을 실행하세요.

직접 API 요청에서는 HTTP 202가 작업이 수락되었고 아직 진행 중임을 뜻해요. 필요한 상태에 도달할 때까지 리소스를 반복해서 읽으세요.

클라이언트가 기다리는 것을 멈춘 후에도 샌드박스 생성이 계속될 수 있어요. 상태를 확인하려면 샌드박스를 다시 읽고, 실패했다면 failure 필드를 검사하세요. 복구 방법은 Errors and retries 문서를 참고해 주세요.

삭제도 시간이 걸릴 수 있어요. API는 샌드박스가 삭제되는 동안 HTTP 202를, 삭제가 완료되면 HTTP 204를 반환해요. 삭제 후에는 인증된 읽기가 notFound를 반환해요.

키트 설정 대기

waitUntilRunning()과 kits.launchAndWait()는 샌드박스가 running 상태에 도달할 때까지 기다려요. 도구 설치나 저장소 클론 같은 키트 설정 명령은 그 시점에 여전히 실행 중일 수 있어요.

SDK는 모든 키트 설정이 끝날 때까지 기다리는 헬퍼를 제공하지 않아요. 애플리케이션이 그 설정에 의존한다면 작업을 시작하기 전에 준비 상태 확인(readiness check)을 추가하세요. 무엇을 확인할지는 키트와 작업에 따라 달라요. 예를 들어 저장소 클론이 끝난 뒤 작성되는 완료 마커나 서비스의 성공적인 헬스 체크 같은 거죠.

체크 사이에 지연을 두고 타임아웃을 걸어 폴링하세요. 그래야 설정이 실패해도 애플리케이션이 기다리는 것을 멈춰요.

관리 및 샌드박스 엔드포인트

샌드박스를 만들고 그 안에서 명령을 실행하는 것은 다른 엔드포인트를 사용해요:

SDK는 이 기본 URL로 요청 URL을 구성해요. HTTP 요청을 직접 만든다면 기존 경로를 유지한 채 기본 URL에 /v1 라우트를 추가하세요. 예를 들어 관리 라우트 /v1/sandboxes는 https://connect.docker.com/sandboxes/v1/sandboxes가 돼요.

각 샌드박스 엔드포인트는 그 샌드박스에 접근을 허용하는 토큰이 필요해요. SDK는 샌드박스의 프로세스나 파일 메서드를 사용할 때 이 토큰을 얻어요. 자세한 내용은 인증과 권한 부여 문서를 참고해 주세요.

샌드박스의 엔드포인트는 런타임이 바뀌면 달라질 수 있어요. 다시 연결하기 전에 샌드박스 리소스를 다시 읽어 엔드포인트를 가져오세요.

목록의 모든 결과 읽기

목록 요청은 한 번에 한 페이지의 결과를 반환해요. 다음 페이지를 가져오려면 응답의 nextPageToken을 다음 요청의 pageToken으로 전달하세요. 페이지 크기, 필터, 정렬은 그대로 유지해요. 페이지에 요청한 것보다 적은 항목이 있어도 nextPageToken이 빌 때까지 계속하세요.

기본 페이지 크기는 Cloud 샌드박스, 이미지, 스냅샷, 볼륨, 시크릿 목록에서 25개예요. 페이지당 최대 100개 항목을 요청할 수 있어요.

지원되는 Cloud 옵션 선택

Cloud는 계정 권한과 기능 가용성에 따라 키트, 샌드박스 타임아웃, 저장된 시크릿, 볼륨 첨부를 지원해요. 예를 들어 볼륨 접근은 계정에 활성화되어 있어야 해요. SDK 메서드가 있다고 해서 계정이 그걸 사용할 수 있다는 보장은 없어요.

키트 아티팩트 공급

번들 카탈로그 밖의 키트를 사용하려면 client.create()를 호출하기 전에 애플리케이션이 그 콘텐츠를 로드하고 준비해야 해요. npm SDK는 레지스트리에서 키트를 가져오지 않아요. 그 kits.launch()와 kits.launchAndWait() 헬퍼는 번들 키트 이름만 받아들여요.

예를 들어 Hermes 에이전트 키트는 docker.io/sbx/hermes-agent-kit:latest로 게시돼요. SDK로 사용하려면 키트 정의와 지원 파일을 API가 받아들이는 직렬화된 v2 아티팩트 형식으로 로드하는 SDK 외부 코드가 필요해요.

여기 설명된 키트 아티팩트는 v2 형식을 사용해요. kits 배열에는 샌드박스 키트와 거기에 구성을 추가하는 믹스인(mixin)이 들어 있어요. 자세한 내용은 v2 kit reference를 참고하세요. 번들 실행 헬퍼는 카탈로그의 키트에 대해 이와 같은 입력을 준비해요.

키트의 소스 참조와 준비된 아티팩트 바이트를 client.create()로 전달하세요:

function createFromKit(reference: string, artifactBytes: Uint8Array) {
  return client.create({
    resources: 'small',
    kits: [
      {
        artifact: {
          ref: { ref: reference, kind: 'sandbox' },
          inline: artifactBytes,
        },
      },
    ],
  });
}

ref는 키트의 소스를 식별해요. 레지스트리 풀을 트리거하지 않아요. inline 값은 키트의 파일 콘텐츠를 포함한 직렬화된 아티팩트를 Uint8Array로 담아요. 원본 spec.yaml, ZIP 파일, OCI 매니페스트는 이 필드의 유효한 입력이 아니에요.

로딩 코드를 작성하지 않고 레지스트리 참조로 공개 키트를 실행하려면 Docker Agentic Platform 콘솔을 사용하세요.

더 알아보기 (Learn more)