키트 사용하기

키트 사용하기 (Use kits)

배포된 키트를 실행하고, mixin으로 결합하고, 설정을 커스터마이즈하는 방법을 알아볼게요.

출처: 문서

본문

sbx run claude나 sbx run codex를 실행해 봤다면 이미 키트를 쓴 거예요. 내장 에이전트는 환경, 도구, 런타임 설정을 패키징한 키트예요. 직접 만들었거나 다른 배포자에게 받은 키트도 같은 방식으로 실행해요. sbx에 참조를 주면 Docker Sandboxes가 환경을 준비하고 키트의 설정을 적용해요.

이 페이지는 배포된 키트를 실행하고, mixin과 결합하고, 설정을 커스터마이즈하는 방법을 보여줘요.

참고 (Note): 이 기능은 Early Access 상태예요.

키트 실행하기

내장 에이전트 이름은 키트 참조의 단축어예요. 다른 키트를 실행하려면 에이전트 이름을 그 키트의 참조로 바꾸세요. 예를 들어 Docker의 배포된 v3 Codex 워크로드를 실행해 봅시다:

$ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit

이렇게 하면 Docker Hub의 v3 키트로 Codex가 시작돼요. 내장 codex 단축어는 기존 커스터마이즈와의 호환성을 유지하기 위해 v2 키트를 사용해요.

키트 소스 고르기

앞의 예시는 Docker Hub의 배포된 이미지를 사용해요. 로컬 디렉터리나 Git 저장소의 키트도 실행할 수 있어요. --kit으로 추가하는 mixin에도 같은 소스 유형이 동작해요:

소스	예시 참조
배포된 이미지	`docker.io/my-org/agent-kit:1.0.0`
로컬 디렉터리	`./my-agent`
Git 저장소	`git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent`

Git 소스에서 ref는 리비전을, dir은 키트의 하위 디렉터리를 고른다. Git URL은 &를 포함할 수 있으므로 셸 명령에서 따옴표로 감싸세요:

$ sbx run "git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent"

sbx는 샌드박스를 만들 때 배포된 이미지를 땡기고 로컬·Git 소스를 빌드해요. 소스 내용과 제공된 키트 argument가 바뀌지 않은 빌드는 캐시된 결과를 재사용해요.

기본적으로 원격 키트 소스는 Docker Hub로 제한돼요. Git 소스나 다른 레지스트리를 쓰려면 Restrict kit sources 문서를 보세요. 비공개 이미지는 Registry credentials 문서를 보세요.

샌드박스 재사용하기

샌드박스는 생성됐을 때의 키트 구성을 유지해요. 앞 예시의 샌드박스로 돌아가려면 이름을 지정하세요:

$ sbx run --name codex-v3-kit

키트 참조를 다시 지정할 필요는 없어요. 다른 워크로드·mixin 조합이나 argument 값을 시험하려면 이름이 다른 샌드박스를 만들거나 기존 것을 다시 만드세요. 기존 샌드박스에 mixin을 추가하려면 Add mixins 문서를 보세요.

런타임 접근과 지침

키트는 자신이 필요한 서비스에 대한 접근을 요청할 수 있어요. 예를 들어 Codex 워크로드는 OpenAI에 닿고 인증해야 해요. API 키를 쓴다면 호스트에 저장하고 키트가 사용하는 요청을 승인하세요. 이 둘은 별개의 단계예요. 비밀을 저장한다고 제3자 키트가 그것을 쓸 권한이 생기진 않아요. 무인(unattended) 실행 준비는 Credential bindings 문서를 보세요.

키트 문서에서 접촉하는 서비스, 필요한 자격 증명, 시작 시 실행하는 명령을 확인하세요. 프록시 관리 자격 증명의 경우 키트의 credential binding이 프록시에 서비스로의 요청에 어떤 자격 증명을 넣을지 알려줘요. 바인딩을 승인하면 프록시가 나가는 요청에 자격 증명을 추가해요. 자격 증명 값은 호스트에 남고 샌드박스 안에 노출되지 않아요.

네트워크 요청은 샌드박스의 네트워크 정책도 충족해야 해요. 키트 allow 규칙은 조직 정책 너머의 접근을 부여할 수 없어요. 연결이 실패하면 정책 로그에서 어떤 규칙이 차단했는지 확인하세요.

키트는 에이전트에게 자기 도구 사용 지침을 줄 수도 있어요. 워크로드가 지침 파일을 고르고, mixin이 그 지침을 추가해요. Docker Sandboxes는 그 파일을 워크스페이스 밖에 써서 프로젝트의 지침은 그대로 두어요.

Mixins 추가하기

Mixin은 워크로드에 도구와 구성을 추가해요. 샌드박스를 만들 때 --kit으로 mixin을 추가하세요. v3 키트에서는 워크로드와 mixin 모두 v3를 써야 해요.

예를 들어 내부 CLI mixin이 회사 실행 파일을 네트워크 규칙과 API용 자격 증명 요청과 함께 패키징할 수 있어요:

$ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-tools \
    --kit docker.io/<NAMESPACE>/company-cli:1.0.0

mixin 참조를 조직이 배포한 것으로 바꾸세요. 직접 만들려면 도구 믹스인 만들기 문서를 보세요. mixin이 요청하는 자격 증명을 호스트에 저장하고 프롬프트가 뜨면 접근을 승인하세요.

Codex는 company-cli를 쓸 수 있는 상태로 시작돼요. Docker Sandboxes는 워크로드와 mixin 양쪽의 파일과 설정을 적용해요.

claude, codex 같은 내장 단축어는 v2 키트를 사용하며 v2 mixin이 필요해요. 자세한 내용은 Version compatibility 문서를 보세요.

여러 mixin 결합하기

--kit을 반복해서 mixin을 더 추가하세요. 배포된 워크로드 세트에 호환 mixin을 추가하거나, mixin만 담은 세트를 --kit으로 넘길 수도 있어요.

세트에 이미 있는 키트는 추가하지 마세요. 두 키트가 같은 기능을 제공하면 Docker Sandboxes가 그 조합을 거절할 수 있어요.

조합을 하나의 참조로 배포하려면 키트 세트 구성하기 문서를 보세요.

샌드박스의 mixin 바꾸기

v3 키트에서는 샌드박스를 만들 때 mixin을 고른다. 다른 조합을 쓰려면 이름이 다른 샌드박스를 만드세요. 워크로드와 포함할 모든 mixin을 지정하세요.

sbx kit add 명령은 기존 v3 샌드박스에 mixin을 추가할 수 없어요.

새 샌드박스는 이전 샌드박스의 변경이나 키트 볼륨 데이터를 상속하지 않아요.

키트 구성하기

일부 mixin은 다른 키트가 공급하는 도구가 필요해요. 예를 들어 스크립트가 gojq를 호출하는 mixin은 그 의존성을 선언할 수 있어요:

requires: [gojq]

gojq mixin 예시는 자신이 제공하는 기능을 선언해요:

provides: ["[email protected]"]

샌드박스를 만들 때 두 mixin을 모두 포함하세요. Docker Sandboxes는 --kit 플래그의 순서와 무관하게 gojq mixin을 먼저 적용해요. gojq를 빼면 샌드박스 생성이 실패해요.

requires 항목은 키트가 무엇을 필요로 하는지 Docker Sandboxes에 알려줘요. 그것을 제공하는 키트는 여전히 당신이 골라 포함해야 해요. Docker Sandboxes는 이 항목을 보고 키트를 자동으로 내려받지 않아요. 키트는 최소 기능 버전을 요구하거나 호환되지 않는 키트를 배제할 수도 있어요.

--kit에서는 Docker Sandboxes가 샌드박스를 만들 때 키트를 확인하고 결합해요. 세트의 경우 배포자가 빌드할 때 이 작업이 일어나요. 배포된 키트는 이미지 digest로 식별되는 정확한 구성 요소 기록을 포함해요.

자체 키트에서 이런 관계를 선언하려면 Composition fields 문서를 보세요.

키트에 argument 넘기기

키트는 linter의 mode 같은 설정을 위한 argument를 노출할 수 있어요. argument 이름, 기본값, 허용값은 키트 문서에서 확인하세요. --kit-arg name=value로 argument를 설정해요:

$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \
    --name codex-tools-fix --kit-arg lint_mode=fix

이 예시는 lint_mode argument를 노출하는 워크로드 세트를 사용해요. 이미지 참조를 세트의 배포된 참조로 바꾸세요. 자체 세트에서 argument를 노출하려면 Configure component arguments 문서를 보세요.

argument 값은 일반 텍스트이며 셸 히스토리와 샌드박스 상태에 기록될 수 있어요. 비밀에는 stored credentials를 쓰세요.

특정 키트 대상 지정하기

키트 접두사가 없는 argument는 그것을 선언하는 선택된 모든 키트에 적용돼요. 한 키트를 지정하려면 --kit-arg <HANDLE>.<ARGUMENT>=<VALUE>를 쓰세요:

$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \
    --name codex-tools-fix --kit-arg codex-tools.lint_mode=fix

handle은 키트를 식별하며 그 참조에서 나와요:

키트 소스	Handle
배포된 이미지	저장소 이름의 마지막 부분 (예: `codex-tools`)
로컬 디렉터리	디렉터리 이름
Git 저장소	선택한 하위 디렉터리 이름, 또는 하위 디렉터리를 선택하지 않으면 저장소 이름

한 키트를 대상으로 한 값은 모든 키트에 제공된 값을 덮어써요.

파일에서 argument 불러오기

--kit-args-file <FILE>로 재사용 가능한 파일에서 argument를 불러와요. 한 줄에 name=value 항목 하나를 쓰세요. --kit-arg처럼 이름에 키트 handle을 붙일 수 있어요.

--kit-arg로 넘긴 값이 파일의 값을 덮어써요.

바꿀 수 있는 설정

키트 세트에서는 작성자가 노출한 argument만 바꿀 수 있어요. 다른 구성 요소 argument는 세트를 배포할 때 고정돼요.

도구 버전처럼 이미지 빌드 중에 고르는 설정은 이미지를 다시 빌드해야 해요.

키트 소스 제한하기

kit.allowedSources가 허용되는 원격 키트 소스를 통제해요. 기본값은 Docker Hub를 허용해요. Git 배포자를 포함하려면 허용할 접두사 전체 목록을 설정하세요:

$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'

접두사는 경로 세그먼트 경계에서 일치해요. 로컬 소스 디렉터리는 kit.allowLocalKits가 별도로 통제하며 기본값은 true예요:

$ sbx settings set kit.allowLocalKits false

기본값과 환경 변수 대응은 kit settings reference 문서를 보세요.

키트 서명 확인하기

배포된 키트를 작성자의 서명 신원에 대해 확인하려면:

$ sbx kit verify docker.io/<NAMESPACE>/my-kit:1.0.0 \
    --certificate-identity <SIGNER_IDENTITY> \
    --certificate-oidc-issuer <ISSUER_URL>

키 기반 서명에는 인증서 신원·발급자 옵션 대신 --key cosign.pub를 쓰세요. 기대하는 신원이나 공개 키는 배포자에게 받으세요.

키트를 불러올 때 신뢰할 수 있는 서명을 요구하려면 신뢰하는 서명자 정책을 구성한 다음 요구를 켜세요:

$ sbx settings set kit.trustedSigners \
  '[{"identity":"[email protected]","issuer":"https://accounts.google.com"}]'
$ sbx settings set kit.requireSignature true

V3 소스 디렉터리와 Git 소스는 소스 서명 워크플로를 지원하지 않아요. 서명이 필요하면 서명된 OCI 이미지를 사용하세요.

키트 디버깅하기

도구가 없거나 요청이 실패하면 실행 중인 샌드박스를 검사하세요:

$ sbx exec <SANDBOX> -- which <TOOL>
$ sbx exec <SANDBOX> -- cat /home/agent/.config/<TOOL>/settings.json
$ sbx policy log

정책 로그는 아웃바운드 요청과 그것이 매치한 규칙을 보여줘요. 차단된 패키지 레지스트리나 API 호스트를 찾는 데 쓰세요. 자격 증명을 요청하는 키트를 추가한 뒤 다운로드가 실패하면, 작성자에게 자격 증명 주입이 필요한 서비스 호스트만 대상으로 하는지 확인해 달라고 하세요.

갱신된 v3 키트를 시험하려면 이름이 다른 샌드박스를 만드세요. 기존 샌드박스를 재사용하면 기록된 키트 구성을 유지해요.

더 알아보기 (Learn more)

Credential bindings, Restrict kit sources, Registry credentials, Add mixins, 도구 믹스인 만들기, Version compatibility, 키트 세트 구성하기, Composition fields, Configure component arguments, stored credentials, kit settings reference 문서를 참고하세요.