키트 작성 패턴

키트 작성 패턴 (Kit authoring patterns)

도구를 키트로 패키징할 때 어디에 더하든 동작하도록 만드는 패턴을 알아볼게요.

출처: 문서

본문

도구를 키트로 패키징할 때는 어디에 더하든 동작하도록 만드는 걸 목표로 해요. 이 패턴들은 필요한 접근을 포함하고, 각 샌드박스에 맞게 준비하며, 팀에게 환경을 직접 조립하게 하지 않고 유용한 옵션을 주는 방법을 보여줘요.

런타임 접근을 도구와 함께 두기 (Keep runtime access with the tool)

도구의 네트워크 규칙과 자격 증명 요청을 그것을 설치하는 믹스인에 두세요. 예를 들어 Claude Code 믹스인은 실행 파일을 패키징하고, Anthropic API에 접근을 허용하며, API 키를 요청할 수 있어요. 그 요구사항들은 다른 워크로드에 도구를 더할 때 도구를 따라가요.

사용자는 여전히 자격 증명을 제공하고 접근을 승인해야 해요. 완전한 예시는 Build a tool mixin을 보세요.

빌드 도구를 믹스인에서 빼기 (Leave build tools out of the mixin)

한 Dockerfile 스테이지에서 도구를 빌드한 뒤 실행 파일을 빈 스테이지로 복사해요. 각 샌드박스는 컴파일러와 소스 코드 없이 도구만 얻게 돼요:

gojq/gojq.yaml

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: mixin
provides: ["[email protected]"]

build: |
  FROM golang:1.25 AS build
  RUN CGO_ENABLED=0 go install github.com/itchyny/gojq/cmd/[email protected]

  FROM scratch
  COPY --from=build /go/bin/gojq /usr/local/bin/gojq

CGO_ENABLED=0은 워크로드의 C 라이브러리 의존성 없이 gojq를 빌드해요. FROM scratch는 최종 스테이지를 빈 상태로 시작해 복사한 바이너리만 포함하게 해요. provides 항목은 다른 키트에 이 믹스인이 설치하는 gojq 버전을 알려줘요.

키트 결합 후 설정 실행하기 (Run setup after combining kits)

일부 설정은 워크로드의 도구나 파일이 필요해요. 가능한 것은 믹스인에 패키징하고, 모든 키트의 파일이 제자리에 놓인 뒤 install 훅으로 설정을 끝내요. 예를 들어 믹스인에서 내부 인증 기관(CA) 인증서를 가져와 워크로드의 신뢰 저장소에 등록해요:

internal-ca/internal-ca.yaml

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: mixin

build: |
  FROM scratch
  COPY internal-ca.crt /usr/local/share/ca-certificates/team-internal-ca.crt

capabilities:
  - type: com.docker.sandbox/lifecycle@1
    config:
      install:
        - command: update-ca-certificates
          user: "0"

PEM 인코딩 CA를 디스크립터 옆에 internal-ca.crt로 저장하고, update-ca-certificates를 제공하는 워크로드(예: Docker의 셸 키트)와 함께 믹스인을 사용해요. 훅은 모든 키트 파일이 있고 에이전트가 실행되기 전에 워크로드의 신뢰 저장소를 root로 갱신해요.

$ sbx run docker.io/docker/sbx-kit-shell:1.0.0 --kit ./internal-ca

마운트 후 저장소 시드하기 (Seed storage after it is mounted)

경로에 저장소를 마운트하면 이미지가 이미 그곳에 가진 파일을 숨겨요. 도구에 초기 데이터를 주려면 그 데이터를 이미지의 다른 곳에 두고 install 훅에서 마운트된 디렉터리로 복사해요. 사용자가 만든 변경을 보존하도록 먼저 대상 파일이 존재하는지 확인해요:

tool-state/tool-state.yaml

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: mixin

build: |
  FROM scratch
  COPY defaults.json /usr/share/company-cli/defaults.json

capabilities:
  - type: com.docker.sandbox/volume@1
    config:
      path: /home/agent/.company-cli
      size: 1g
  - type: com.docker.sandbox/lifecycle@1
    config:
      install:
        - command: |
            set -eu
            chown 1000:1000 /home/agent/.company-cli
            if [ ! -e /home/agent/.company-cli/config.json ]; then
              install -o 1000 -g 1000 -m 0644 /usr/share/company-cli/defaults.json /home/agent/.company-cli/config.json
            fi
          user: "0"

도구의 초기 구성을 디스크립터 옆에 defaults.json으로 저장해요. chown과 install이 있는 워크로드(예: Docker의 셸 키트)를 사용하세요. 훅은 디렉터리와 구성 파일을 에이전트가 쓸 수 있게 만듭니다. 볼륨에 이미 구성 파일이 있으면 훅은 그 내용을 그대로 둡니다.

볼륨 구성하기 (Configure the volume)

볼륨은 샌드박스 재시작 사이에도 도구의 데이터를 유지해요. 대체 샌드박스는 자체 볼륨을 받아요. 이 예시는 1g의 공간을 할당해요. size를 생략하면 sbx는 512m을 할당해요.

이 예시처럼 install 훅으로 영구 볼륨의 소유권과 권한을 설정하세요. 볼륨 능력의 mode 설정은 tmpfs 마운트에만 적용돼요. 저장소 옵션은 업스트림 volume 정의를 보세요.

대신 마운트된 워크스페이스에 초기 파일을 복사하려면 WORKSPACE_DIR을 목적지로 사용하고 훅의 환경에 선언하세요.

고정 구성 요소를 구성 가능한 옵션과 함께 게시하기 (Publish fixed components with configurable options)

팀에 맞는 호환 에이전트와 도구 버전을 고른 뒤 세트로 게시해요. 모델이나 린터 모드처럼 사용자가 그 구성 요소를 교체하지 않고 바꿀 수 있는 설정에는 인자를 노출해요. 버전 선택은 게시된 이미지에 고정해 두세요.

인자 문법과 제약은 Configure component arguments 문서를 보세요.

더 알아보기 (Learn more)

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