키트 작성

키트 작성 (Author kits)

팀에 반복 가능한 샌드박스 환경을 주기 위해 키트를 빌드하는 방법을 알아볼게요.

출처: 문서

본문

키트를 빌드해 팀에 반복 가능한 샌드박스 환경을 주세요. 에이전트를 패키징하거나, 다른 에이전트와 쓸 도구를 추가하거나, 기존 키트들을 팀이 실행할 하나의 키트로 결합할 수 있어요. 이 섹션의 가이드들은 각 접근 방식을 안내해요.

참고 (Note): v3 워크로드와 v3 믹스인을 함께 선택하세요. claude와 codex 같은 기본 제공 단축키는 v2를 사용하며 v3 믹스인과 결합할 수 없어요. Version compatibility 또는 v2 reference 문서를 보세요.

무엇을 작성할지 고르기 (Choose what to author)

• Compose a kit set — 게시했거나 레지스트리에서 고른 키트를 결합해요. 세트는 네트워크 접근, 설정 명령, 에이전트 지침을 추가하고, 사용자가 어떤 모델을 쓸지 같은 설정을 고르게 할 수도 있어요.
• Build a tool mixin — 재사용 가능한 도구를 그 네트워크 접근과 자격 증명과 함께 패키징해요.
• Build an agent workload — 기본 환경, 에이전트 설치, 실행 명령을 제어해요. 기존 에이전트 이미지를 쓸 수도 있어요.

연구하고 적용할 수 있는 완전한 키트는 Docker Sandbox Kit Specification 저장소의 Kit examples를 보세요.

디렉터리와 빌드 레이아웃 (Directory and build layout)

각 키트의 소스를 자기 디렉터리에 두세요. 키트는 보통 두 파일에서 시작해요:

• YAML 디스크립터는 키트를 워크로드·믹스인·세트로 식별하고 설정과 요구사항을 선언해요.
• Dockerfile은 소프트웨어를 설치하고 파일을 이미지로 복사해요.

키트의 이름을 디렉터리와 디스크립터에 사용하세요. Dockerfile이 있으면 디스크립터와 같은 파일 이름 어간(stem)을 쓰세요: my-kit.yaml은 my-kit.dockerfile과 짝을 이뤄요.

예를 들어:

my-kit/
├── my-kit.yaml
├── my-kit.dockerfile
├── context.md
└── files/
    └── settings.json

지원 파일은 키트에 맞게 정리하세요. 이 예시는 에이전트 지침을 context.md에, 구성 파일을 files/ 아래에 둡니다.

파일이 함께 동작하는 방식 (How the files work together)

Dockerfile은 이미지에 들어가는 것(설치된 도구, 구성 파일)을 정의해요. 워크로드라면 실행할 명령도 설정해요. YAML 디스크립터는 네트워크 접근, 자격 증명, 에이전트 지침 같은 키트의 설정과 요구사항을 정의해요.

디스크립터는 문법 선언으로 시작해요:

# syntax=docker/sandbox-kit:3

이것은 키트 빌드 프론트엔드를 선택하는데, 디스크립터와 일치하는 Dockerfile을 읽어요. 빌드는 소프트웨어, 지원 파일, 검증된 디스크립터를 담은 컨테이너 이미지를 만들어요.

키트 세트는 디스크립터의 kits: 목록으로 게시된 키트를 결합해요.

키트 빌드·사용하기 (Build and use the kit)

Docker Buildx로 빌드할 때는 YAML 디스크립터를 -f에, 소스 디렉터리를 빌드 컨텍스트로 전달해요:

$ docker buildx build -f my-kit/my-kit.yaml -t my-kit:dev my-kit/

sbx에 로컬 키트 디렉터리 참조를 줄 수도 있어요. 샌드박스를 만들 때 키트를 빌드해요. 이미지를 레지스트리에 게시한 후에는 그 이미지 참조를 쓸 수 있어요.

빌드 옵션과 게시 지침은 Build and distribute kits 문서를 보세요.

다른 소스 레이아웃 (Other source layouts)

분리된 디스크립터와 Dockerfile은 키트를 정리하는 한 방식이에요. build: | 아래에 Dockerfile을 인라인으로 쓰거나, dockerfile:로 선택하거나, Dockerfile 주석에 디스크립터를 포함할 수도 있어요.

문법은 Authoring forms 문서를 보세요.

능력 (Capabilities)

도구를 설치하는 것은 종종 작업의 일부일 뿐이에요. 도구는 API에 도달하거나, 자격 증명으로 인증하거나, 에이전트가 시작하기 전에 설정 명령을 실행해야 할 수도 있어요. 그 필요를 디스크립터의 capabilities 목록에 설명하세요. 각 항목은 Docker Sandboxes에 다음 기능 중 하나를 제공하라고 요청해요.

키트의 Dockerfile은 이미지가 어떻게 빌드되는지 정의해요. 그 능력은 Docker Sandboxes가 샌드박스를 준비하고 실행할 때 무엇을 해야 하는지 설명해요. 예를 들어 도구 믹스인은 Dockerfile로 API 클라이언트를 설치하고 네트워크 능력으로 그 API에 접근을 요청할 수 있어요. Docker만으로 이미지를 빌드·실행하면 이 능력 설정이 적용되지 않아요.

워크로드, 믹스인, 세트에 능력을 추가할 수 있어요. 각 요청을 그것이 필요한 키트와 함께 두세요. 그래야 다른 에이전트와 쓸 때 도구의 접근 규칙이 따라가요.

각 능력 항목은 type에서 기능을 식별해요. 설정이 필요한 능력은 config에서 받아요. 예를 들어 com.docker.sandbox/network-policy@1은 네트워크 접근을 요청하고, 그 config는 허용할 도메인을 나열해요.

@1은 능력의 버전을 식별해요. 키트 형식 버전과 sbx 릴리스와 무관해요. 업스트림 능력 정의가 사용 가능한 능력과 설정을 설명해요.

참고 (Note): sbx는 usb-device@1, privileged@1, agent-sessions@1 요청을 적용하지 않아요. 그 능력 시행은 필수 능력이 지원되지 않아도 샌드박스 생성이 성공하게 할 수 있어요. 이 동작에 의존하지 마세요: 키트가 실행될 런타임이 지원하는 능력을 선택하세요. kit-registry@1 능력은 승인된 OCI 빌더 키트로 제한되며, 로컬·Git 키트 소스는 받지 못해요.

여기 가이드들은 Docker Sandboxes에서 능력을 사용하는 방법을 보여줘요. 모든 디스크립터 필드와 키트 결합 규칙은 업스트림 v3 규격을 보세요.

설정이 실행될 때 고르기 (Choose when setup runs)

이미지 빌드 중에 도구를 설치하고 정적 파일을 복사하면 모든 샌드박스에서 재사용할 수 있어요. 일부 설정은 샌드박스가 존재할 때까지 기다려야 해요. 예를 들어 믹스인이 CA 인증서를 가져올 수 있지만, 그 인증서를 등록하려면 워크로드의 도구가 필요해요. 수명 주기(lifecycle) 능력으로 명령을 적절한 시점에 실행하거나 파일을 생성해요:

수명 주기 훅은 샌드박스 생성·시작 중에 실행되는 명령이에요. startup 훅을 두 번 이상 실행해도 안전하게 만드세요. sbx에서는 에이전트와 나란히 실행되므로 에이전트가 끝나기 전에 시작할 수 있어요. 매 에이전트 실행 전에 명령이 끝나야 한다면 워크로드의 엔트리포인트에 두세요.

훅에 환경 변수 전달하기 (Pass environment variables to hooks)

sbx에서 install 훅은 제한된 환경 변수 집합(기본 프로세스 변수, 프록시 설정, 인증서 경로)을 받아요. 명령에 다른 변수가 필요하면 훅의 env 목록에 이름을 넣어요. 예를 들어 env: [WORKSPACE_DIR]은 명령에 마운트된 워크스페이스의 경로를 줍니다. sbx에서 startup 훅은 이 필터링 없이 샌드박스의 환경을 받아요.

설정 예시는 Kit authoring patterns, 필드는 업스트림 lifecycle 정의를 보세요.

워크로드 컴퓨트 요구사항 설정하기 (Set workload compute requirements)

디스크립터의 resources@1 능력으로 워크로드의 기본 CPU·메모리 할당을 설정해요. 정수 CPU 코어를 사용하세요. 키트를 실행하는 누구든 샌드박스를 만들 때 --cpus와 --memory로 이 기본값을 덮어쓸 수 있어요.

이 설정을 워크로드에 두세요. sbx는 별도로 추가한 믹스인의 리소스 설정을 무시하고, 능력의 gpu 필드로 GPU를 선택하지 않아요.

더 알아보기 (Learn more)

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