도구 믹스인 만들기

도구 믹스인 만들기 (Build a tool mixin)

필요한 네트워크 접근과 자격 증명과 함께 재사용 가능한 CLI 도구를 패키징하는 방법을 알아볼게요.

출처: 문서

본문

도구 믹스인(tool mixin)을 만들어 필요한 네트워크 접근과 자격 증명과 함께 재사용 가능한 CLI 도구를 패키징해요. 이 예시는 gh(GitHub CLI)를 Claude Code 워크로드와 함께 쓰기 위한 믹스인으로 패키징해요.

예시 개요 (Example overview)

믹스인은 워크로드의 환경에 도구를 설치하고, 그것을 실행하는 데 필요한 능력(capabilities)을 추가해요.

이 예시에서 믹스인 디렉터리, 키트의 일부로 빌드되는 Dockerfile, YAML 디스크립터를 만듭니다. 믹스인의 Dockerfile은 gh 바이너리를 이미지로 복사하고, 디스크립터는 네트워크 접근과 자격 증명을 선언해요.

믹스인 디스크립터 (The mixin descriptor)

디스크립터는 kind: mixin을 설정하고 런타임 네트워크 접근과 그것이 요구하는 자격 증명을 선언해요.

gh-cli/gh-cli.yaml

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

capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - api.github.com
  - type: com.docker.sandbox/credential@1
    config:
      service: github
      phase: runtime
      apiKey:
        name: GITHUB_API_TOKEN
        proxyManaged: true
        inject:
          - domain: api.github.com
            header: Authorization
            format: "Bearer %s"

서비스 이름 github는 워크로드에 이 믹스인이 GitHub 자격 증명이 필요하다고 알려줘요. proxyManaged: true 설정과 inject 목록은 Docker Sandboxes에 자격 증명을 어떻게 주입할지 알려줘요. 에이전트 루프는 api.github.com의 도메인과 자격 증명에 일치하는 요청을 bearer 토큰으로 전달해요. 도메인과 디스크립터에 나열된 헤더로 접근이 범위가 제한돼요.

워크로드와 함께 실행하기 (Run with a workload)

믹스인을 빌드하고 게시한 뒤 워크로드와 함께 사용할 수 있어요. 예를 들어:

$ sbx run me/my-workload:latest --kit me/my-gh-cli:latest

결과 (The result)

믹스인의 gh 덕분에 에이전트가 GitHub CLI로 작업할 수 있어요. 자격 증명을 믹스인 자체에 넣지 마세요. 호스트에서 sbx secret set github으로 저장하세요. 자격 증명은 샌드박스에 노출되지 않고 호스트에 남아 있어요.

더 알아보기 (Learn more)

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