자격 증명 관리

자격 증명 관리 (Manage credentials)

로컬 샌드박스의 자격 증명 저장과 인증 흐름, 그리고 인증 주입 방식을 알아볼게요.

출처: 문서

본문

이 자격 증명 저장소와 인증 흐름은 로컬 샌드박스에 적용돼요. 클라우드 자격 증명은 별도 설정이 필요해요: Authenticate cloud agents 문서를 보세요.

대부분의 에이전트는 모델 제공 업체의 API 키가 필요해요. 호스트의 HTTP/HTTPS 프록시가 샌드박스의 아웃바운드 요청을 가로채고, 호스트에서 일치하는 자격 증명을 찾아, 전달 전에 인증 헤더를 덮어써요. 프록시 관리가 활성화되면 실제 자격 증명은 호스트에 남고, 샌드박스는 센티널(sentinel) 값만 봐요. 자격 증명 격리가 더 넓은 샌드박스 보안 모델에 어떻게 맞는지는 Trust boundaries 문서를 보세요.

자격 증명 주입이 동작하는 방식 (How credential injection works)

샌드박스가 아웃바운드 요청을 만들면, 호스트 쪽 프록시가 세 가지를 결정해요: 요청이 키트(또는 기본 제공 에이전트)가 선언한 서비스와 일치하는지, 어떤 헤더를 쓸지, 어떤 값을 주입할지. 키트가 일치와 헤더를 선언하고, 여러분이 호스트에서 값을 제공해요. 프록시 관리 자격 증명에서는 실제 값이 샌드박스에 들어가지 않아요 — 에이전트는 proxy-managed 같은 센티널만 봐요.

키트는 OAuth passthrough: true를 설정해 센티널 마스킹을 해제할 수 있어요. 그러면 실제 토큰 응답이 샌드박스로 들어가고 자격 증명 격리가 줄어들어요. oauth 키트 필드를 보세요.

그 값을 제공하는 여러 방법이 있어요. 같은 서비스에 둘 이상의 소스가 값을 가질 때는 저장된 시크릿(stored secret)이 우선해요.

형식 (Form)	무엇인가요	언제 쓰나요
저장된 시크릿 (sbx secret set)	OS 키체인에 서비스별로 저장된 값 또는 동적 소스	기본 제공 또는 키트 선언 서비스의 기본값
커스텀 시크릿 (sbx secret set-custom)	도메인과 환경 변수에 연결된 값	서비스 모델이 맞지 않을 때 — 에이전트가 변수 형식을 검증하거나, 시크릿이 요청 본문에 실릴 때
OAuth	호스트 쪽 로그인 흐름; 토큰은 샌드박스에 들어가지 않음	Claude Code, Codex, Cursor, Droid처럼 에이전트가 지원할 때
레지스트리 자격 증명 (sbx secret set --registry)	이미지와 키트를 pull 하기 위한 인증	개인 레지스트리에서 템플릿이나 키트를 pull 할 때

값을 제공하는 것과 그 사용을 승인하는 것은 별개의 단계예요. 자격 증명 바인딩(credential bindings)은 키트에 어떤 메커니즘과 도메인을 권한 부여했는지 기록해요. 자격 증명 값은 저장하지 않아요.

다중 제공 업체 에이전트(OpenCode, Docker Agent)에서는 프록시가 호출되는 API 엔드포인트를 기준으로 자격 증명을 선택해요. 제공 업체별 세부 사항은 각 에이전트 페이지를 보세요.

저장된 시크릿 (Stored secrets)

sbx secret set은 자격 증명 값이나 동적 시크릿 소스를 OS 키체인에 서비스 식별자로 저장해요. 기본 제공 에이전트는 고정된 서비스 집합을 선언해요. 커스텀 키트는 자체 서비스를 선언할 수 있어요. 둘 다 같은 sbx secret set 흐름이 동작해요.

이름이 mcp:로 시작하는 시크릿은 호스트의 MCP 게이트웨이용으로 예약되어 있어요. 에이전트·제공 업체 자격 증명과 어떻게 다른지는 MCP secrets 문서를 보세요.

시크릿이 저장되는 곳 (Where secrets are stored)

sbx secret set을 지원하는 저장소는 운영체제에 따라 달라요:

• macOS: 시스템 키체인
• Windows: Windows 자격 증명 관리자
• Linux: GNOME Keyring이나 KDE Wallet 같은 데스크톱 키링이 노출하는 Secret Service

Ubuntu 패키지는 GNOME Keyring에 의존하므로, 표준 데스크톱 설치에는 별도 설정이 필요 없어요.

Secret Service가 실행되지 않는 Linux 호스트(헤드리스 서버와 일부 WSL 설정)에서는 sbx가 사용자 설정 디렉터리 $XDG_CONFIG_HOME/com.docker.sandboxes 아래 파일로 대체하는데, $XDG_CONFIG_HOME이 설정되지 않으면 ~/.config/com.docker.sandboxes로 기본 설정돼요. 이 대체는 자동이며 설정이 필요 없어요. 이렇게 시크릿을 저장하면 sbx가 안내를 출력해요:

No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password

sbx는 파일을 0700 권한의 디렉터리에 저장해요. 이는 ~/.docker/config.json에 쓰는 파일 권한 모델과 같아요. 파일을 읽을 수 있는 사용자나 프로세스는 저장된 자격 증명을 가져올 수 있으므로 그 디렉터리를 민감하게 다뤄야 해요. 가능하면 앱별 접근을 중재하는 키체인을 선호하세요.

나중에 호스트에서 Secret Service를 시작하면 sbx는 다시 키체인에 새 시크릿을 저장해요. 데스크톱 키링 없이 샌드박스를 실행하는 방법은 "헤드리스 Linux에서 Docker Sandboxes를 쓸 수 있나요?" 문서를 보세요.

시크릿 저장하기 (Store a secret)

$ sbx secret set anthropic

이 명령은 시크릿 값을 대화형으로 요청해요. 서비스 시크릿은 기본적으로 전역이라 모든 샌드박스에서 쓸 수 있어요. 시크릿을 특정 샌드박스로 범위를 한정하려면:

$ sbx secret set openai --sandbox my-sandbox

서비스 시크릿을 추가·업데이트·제거하면 재시작 없이 기존 로컬 샌드박스에 적용돼요. --command나 --ref로 설정한 시크릿도 마찬가지예요. 샌드박스 범위 시크릿이 전역 시크릿보다 우선해요.

MCP 시크릿 (MCP secrets)

MCP 게이트웨이는 OAuth 클라이언트 시크릿과 커스텀 요청 헤더 시크릿에 같은 호스트 자격 증명 저장소를 사용해요. 이 기록들은 이름이 mcp:로 시작하고 sbx secret ls에 나타나요. 호스트에 남고 샌드박스에 주입되지 않아요. 게이트웨이는 이를 사용해 샌드박스 에이전트를 대신해 MCP 서버에 대한 연결을 인증해요.

설정 방법은 OAuth client secrets와 custom request headers 문서를 보세요. 헤더 시크릿은 전역 범위를 사용하고 자체 재시작 요구사항이 있어요.

동적 시크릿 소스 사용하기 (Use a dynamic secret source)

동적 시크릿 소스는 프록시가 필요할 때 인증된 호스트 도구에서 자격 증명을 가져오게 해요. 시크릿 저장소는 자격 증명 값 대신 참조나 명령을 담아요. 해석과 캐싱은 호스트에서 일어나고, 샌드박스는 여전히 프록시 관리 자리 표시자만 받아요.

1Password 시크릿 참조나 AWS Secrets Manager ARN과 함께 --ref를 사용해요:

$ sbx secret set anthropic --ref 'op://Work/Anthropic/credential'
$ sbx secret set openai \
  --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:openai-api-key'

해당 op 또는 aws CLI가 호스트에 설치되고 인증되어야 해요.

참고 (Note): 특정 1Password 계정이나 AWS 프로필로 참조를 해석하려면 sbx secret set을 실행할 때 OP_ACCOUNT 또는 AWS_PROFILE을 설정하세요. sbx는 시크릿을 해석할 때마다 그 계정이나 프로필을 사용해요. 두 변수 모두 설정되지 않으면 제공 업체 CLI가 자체 기본값을 사용해요.

표준 출력에 시크릿을 출력하는 다른 호스트 도구에는 --command를 사용해요:

$ sbx secret set github --command 'gh auth token'

sbx는 호스트 셸로 명령을 실행하고 출력을 다듬어요. 명령 텍스트는 저장되고 데몬이 재생해요. 명령에 시크릿을 직접 넣지 마세요 — 텍스트가 셸 기록과 프로세스 목록에 나타날 수 있어요.

기본적으로 sbx는 등록할 때 소스를 검증하고, 리졸버의 표준 오류를 드러내지 않고 오류를 보고해요. 등록 중에 해석할 수 없는 소스를 저장하려면 --no-verify를 사용하세요. 초기 검증 실패를 해결하려면 --show-error를 사용하세요. 제공 업체 오류 출력은 민감한 정보를 담을 수 있어요. --show-error와 --no-verify는 함께 쓸 수 없어요.

해석된 서비스 시크릿은 기본적으로 55분 동안 캐시돼요. 캐시 기간을 바꾸려면 --refresh <duration>을 사용하세요. 캐시 대신 자격 증명을 쓸 때마다 소스를 해석하려면 --refresh on-demand를 전달하세요:

$ sbx secret set anthropic \
  --ref 'op://Work/Anthropic/credential' \
  --refresh 30m
$ sbx secret set github --command 'gh auth token' --refresh on-demand

--ref와 --command는 상호 배타적이에요. --token, --oauth, --registry와 함께 쓸 수 없어요.

환경 변수에서 가져오기 (Import from environment variables)

셸에 API 키가 이미 있다면, sbx secret import가 그것을 읽어 각 값을 직접 입력하지 않고 키체인에 저장해요:

$ sbx secret import

이 명령은 현재 세션에서 아래 기본 제공 서비스 표의 환경 변수를 스캔하고, 각각을 쓰기 전에 확인을 요청해요. 단일 서비스를 가져오려면:

$ sbx secret import openai

--all을 전달하면 확인 없이 모두 가져오고(새 항목만; 기존 항목은 그대로), --force는 기존 항목을 덮어써요:

$ sbx secret import --all
$ sbx secret import openai --force

--dry-run을 전달하면 아무것도 쓰지 않고 무엇이 가져와질지 미리 볼 수 있어요. 이후 sbx secret ls로 무엇이 저장됐는지 확인하세요. CI에서 자격 증명을 설정하려면 CI and headless use 문서를 보세요.

기본 제공 서비스 (Built-in services)

각 기본 제공 서비스 이름은 sbx secret import가 읽는 환경 변수와 프록시가 자격 증명을 주입하는 API 도메인에 매핑돼요:

서비스 (Service)	환경 변수 (Environment variables)	API 도메인 (API domains)
anthropic	ANTHROPIC_API_KEY	api.anthropic.com, console.anthropic.com, claude.ai, mcp-proxy.anthropic.com
cursor	CURSOR_API_KEY	api2.cursor.sh, api3.cursor.sh, repo42.cursor.sh, cursor.com
droid	FACTORY_API_KEY	api.factory.ai, app.factory.ai, relay.factory.ai
github	GH_TOKEN, GITHUB_TOKEN	api.github.com, github.com, raw.githubusercontent.com, gist.github.com, copilot.github.com, api.githubcopilot.com
google	GEMINI_API_KEY, GOOGLE_API_KEY	generativelanguage.googleapis.com, oauth2.googleapis.com, aiplatform.googleapis.com, vertexai.googleapis.com
groq	GROQ_API_KEY	api.groq.com
mistral	MISTRAL_API_KEY	api.mistral.ai
nebius	NEBIUS_API_KEY	api.studio.nebius.com, api.tokenfactory.nebius.com
openai	OPENAI_API_KEY	api.openai.com, openai.com, chatgpt.com, www.chatgpt.com
openrouter	OPENROUTER_API_KEY	openrouter.ai
xai	XAI_API_KEY	api.x.ai

sbx secret set <service>으로 시크릿을 저장하면 프록시가 나열된 API 도메인으로 가는 요청에 주입해요.

키트가 선언한 서비스 (Services declared by kits)

키트의 자격 증명을 저장할 때는 키트 문서의 서비스 식별자를 사용해요. my-service를 선언하는 키트라면 실행해요:

$ sbx secret set my-service

별도의 등록 단계는 없어요. 저장된 값과 키트의 요청이 같은 식별자를 사용해요. 프롬프트가 뜨면 키트의 자격 증명 요청을 승인하세요. Credential bindings 문서를 보세요.

키트를 작성할 때는 그 서비스를 어떻게 쓰는지 선언하세요. V3는 자격 증명 능력(credential capability)을, v2는 최상위 credentials 목록을 사용해요. 두 예시 모두 서비스를 선언하고 그 API 호스트에 대한 접근을 허용해요:

v3

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

API 키에는 이 예시처럼 HTTP 헤더와 그 값 형식을 모두 지정해요. sbx는 v3 키트에서 apiKey.inject[].scheme을 사용하지 않아요.

OAuth에는 refresh_token에 재발급 토큰을 반환하는 JSON 자격 증명 파일과 제공 업체를 사용해요. sbx는 TOML 자격 증명 파일이나 다른 재발급 토큰 필드를 지원하지 않아요.

install 단계에 선언된 자격 증명은 install 훅 중에 쓸 수 있어요. 이 자격 증명을 받는 도메인을 네트워크 정책의 install.allow 목록에 추가하세요. runtime.allow의 항목만으로는 설치 중 접근을 허용하지 않아요. 훅이 자격 증명 환경 변수를 읽는다면 그 이름을 훅의 env 목록에 포함하세요.

sbx에서 프록시는 에이전트가 실행되기 전에 install 전용 도메인으로의 자격 증명 주입을 멈춰요. 어떤 런타임 자격 증명이 도메인을 대상으로 하면(다른 서비스 이름이어도) 그 도메인은 자격 증명 주입에 계속 사용 가능해요. 같은 서비스를 두 단계 모두에 선언하면, sbx는 두 단계에서 런타임 선언의 자격 증명 설정을 사용해요.

v2

credentials:
  - service: my-service
    apiKey:
      name: MY_SERVICE_TOKEN
      proxyManaged: true
      inject:
        - domain: api.my-service.com
          scheme: bearer

permissions:
  network:
    allow: [api.my-service.com]

각 서비스는 apiKey, oauth, 또는 둘 다를 선언해요. 둘 다 런타임에 해석되면 API 키가 우선하고 OAuth가 대체 역할을 해요. 키트 쪽 전체 설정은 V3 credential definition 또는 V2 credentials 문서를 보세요.

시크릿 나열하고 제거하기 (List and remove secrets)

모든 저장된 시크릿을 나열해요:

$ sbx secret ls
SCOPE  TYPE     NAME     SECRET
(global) service github  gho_GCaw4o****...****43qy

시크릿을 제거해요:

$ sbx secret rm github

샌드박스 범위 시크릿을 제거하려면 --sandbox를 전달해요:

$ sbx secret rm github --sandbox my-sandbox

샌드박스 범위 시크릿을 제거하면 그 서비스의 전역 시크릿이 있다면 복원돼요.

참고 (Note): sbx reset을 실행하면 모든 샌드박스 상태와 함께 모든 저장된 시크릿이 삭제돼요. 리셋 후 시크릿을 다시 추가해야 해요.

GitHub 토큰 (GitHub token)

github 서비스는 에이전트가 샌드박스 안에서 gh CLI에 접근하게 해요. 호스트에서 기존 GitHub CLI 토큰을 해석해요:

$ sbx secret set github --command 'gh auth token'

데몬은 기본 캐시 기간 후 호스트 명령에서 토큰을 새로고침해요. 이는 여러분을 대신해 pull request를 만들거나, 이슈를 열거나, GitHub API와 상호작용하는 에이전트에 유용해요.

SSH 에이전트 (SSH agent)

SSH 에이전트 전달은 기본적으로 켜져 있어요. SSH_AUTH_SOCK이 설정되면 Docker Sandboxes는 각 샌드박스를 만들거나 시작하거나 합류하는 클라이언트의 값을 사용해요. 그 에이전트를 샌드박스로 전달하고 거기서 SSH_AUTH_SOCK을 설정해요.

1Password SSH 에이전트처럼 안정적인 소켓 경로를 노출하는 에이전트라면, 모든 샌드박스에 그 경로를 구성해요:

$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK"

빈 ssh.agentSocketPath(기본값)는 각 클라이언트의 현재 SSH_AUTH_SOCK을 대신 사용해요. 전달을 켜고 끄려면 ssh.agentForwardingEnabled를 사용하세요.

전달이나 소켓 선택을 바꾼 뒤에는 데몬을 재시작해 기존 샌드박스가 새 구성을 사용하게 하세요:

$ sbx daemon restart

개인 키는 호스트에 남아요. 샌드박스 안의 프로세스는 전달된 에이전트에 서명을 요청할 수 있지만, 개인 키를 읽거나 복사할 수 없어요.

SSH를 통한 Git 작업과 SSH 기반 커밋 서명에 SSH 에이전트 전달을 사용하세요. 샌드박스 커밋 서명이 동작하려면 서명 키가 호스트 SSH 에이전트에 로드되어 있어야 해요. 아웃바운드 SSH 연결은 여전히 샌드박스 네트워크 정책의 적용을 받아요. 자세한 내용은 Commit signing 문서를 보세요.

커스텀 시크릿 (Custom secrets)

중요 (Important): 커스텀 시크릿은 실험적이에요. 동작, 플래그, 자리 표시자 형식이 예고 없이 바뀔 수 있어요.

서비스 식별자 모델에 맞지 않는 자격 증명 — 예를 들어 에이전트가 부팅 시 환경 변수 형식을 검증하거나, 자격 증명이 헤더가 아닌 요청 본문에 실릴 때 — sbx secret set-custom을 사용해요. 시크릿은 하나 이상의 대상 도메인, 환경 변수 이름, 선택적 자리 표시자 문자열에 연결되며, 서비스 식별자 대신에요.

가능하면 서비스 기반 흐름을 선호하세요 — 키트가 배선을 처리하고 여러분은 값만 제공하면 돼요.

커스텀 시크릿 설정하기 (Set a custom secret)

커스텀 시크릿은 기본적으로 전역이에요. --sandbox를 전달해 특정 샌드박스로 범위를 한정하세요.

$ sbx secret set-custom \
  --host api.example.com \
  --env API_KEY \
  --value <secret>

경고 (Warning): --value <secret>로 시크릿을 전달하면 셸 기록에 기록되고, 여러분의 사용자로 실행되는 다른 프로세스에 노출돼요. 실제 자격 증명을 인라인으로 붙여넣지 마세요 — 이미 환경에 있는 변수에서 값을 읽고, 명령줄에 실제 시크릿을 전달했다면 셸 기록을 지우세요.

샌드박스 안에서 API_KEY는 생성된 자리 표시자(예: sbx-cs-<rand>)로 설정돼요. 샌드박스 프로세스가 설정된 호스트 중 하나에 요청을 보내고 요청 어디든 자리 표시자가 나타나면, 프록시가 그것을 실제 값으로 바꿔요. 에이전트는 실제 시크릿을 절대 보지 못해요.

여러 호스트 대상으로 하기 (Target multiple hosts)

--host를 반복해 관련 호스트 이름에 걸쳐 나뉜 API나, 두 개의 무관한 엔드포인트가 자격 증명을 공유할 때 같은 시크릿으로 여러 도메인을 덮어요:

$ sbx secret set-custom \
  --host api.example.com \
  --host uploads.example.com \
  --env API_KEY \
  --value <secret>

--host 값은 네트워크 규칙과 같은 문법으로 와일드카드를 쓸 수도 있어요: *는 단일 라벨(*.example.com은 api.example.com을 덮음), **는 임의 개수(**.example.com은 api.example.com과 v2.api.example.com을 덮음)와 일치해요.

커스텀 시크릿 동적 해석하기 (Resolve custom secrets dynamically)

커스텀 시크릿도 동적 시크릿 소스를 받아요. --value를 --ref 또는 --command로 바꿔요:

$ sbx secret set-custom \
  --host api.example.com \
  --env API_KEY \
  --ref 'op://Work/Example/credential'

동적 커스텀 시크릿은 기본적으로 요청 시 해석돼요. 해석된 값을 캐시하려면 --refresh를 기간과 함께 전달하세요. 검증과 오류 출력 플래그는 서비스 시크릿과 같게 동작해요. --ref와 --command는 --value나 --token과 함께 쓸 수 없어요.

GitHub Packages에서 npm 패키지 설치하기 (Install npm packages from GitHub Packages)

기본 제공 github 서비스는 npm.pkg.github.com으로 가는 요청에 자격 증명을 주입하지 않아요. GitHub Packages에서 개인 npm 패키지를 설치하려면 그 호스트용 커스텀 시크릿을 추가하세요.

호스트에서 패키지를 읽을 수 있는 토큰으로 GitHub CLI를 인증하세요. GitHub는 이 용도로 최소 read:packages 범위의 개인 접근 토큰(classic)을 문서화해요. Authenticating to GitHub Packages 문서를 보세요. 그다음 토큰 소스를 등록하고 my-sandbox를 여러분의 샌드박스 이름으로 바꾸세요:

$ sbx secret set-custom \
  --sandbox my-sandbox \
  --host npm.pkg.github.com \
  --env NODE_AUTH_TOKEN \
  --command 'gh auth token'

명령이 생성된 자리 표시자를 출력해요. 기존 샌드박스에서는 에이전트 세션에 sbx run -e로, 이후 세션에는 /etc/sandbox-persistent.sh로 NODE_AUTH_TOKEN을 그 자리 표시자로 설정하세요. Set environment variables 문서를 보세요. 실제 GitHub 토큰이 아니라 자리 표시자를 사용하세요.

샌드박스 안에서 프로젝트의 .npmrc에 다음 항목을 추가하고, @my-org를 패키지의 스코프로 바꾸세요. ${NODE_AUTH_TOKEN}은 리터럴로 두어 npm이 환경 변수를 읽게 하세요:

@my-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

샌드박스 안에서 패키지를 설치해요:

$ npm install @my-org/my-package

@my-org/my-package를 패키지 이름으로 바꾸세요. npm이 자리 표시자를 npm.pkg.github.com으로 보내고, 프록시가 호스트에서 gh auth token이 가져온 토큰으로 바꿔요.

자격 증명 바인딩 (Credential bindings)

자격 증명 바인딩 파일은 각 서비스에 승인한 자격 증명 메커니즘과 도메인을 기록해요. 위치는 ~/.config/sbx/credentials.yaml, Windows에서는 %APPDATA%\sbx\credentials.yaml이에요.

써드파티 키트는 스키마 버전과 무관하게 쓰는 각 자격 증명에 승인된 바인딩이 필요해요. sbx는 그런 키트를 처음 실행할 때 대화형으로 하나를 만들어요(First-run approval 참조). 직접 항목을 쓸 수도 있어요. sbx와 함께 배포된 기본 제공 키트만 요청하는 자격 증명은 바인딩이 필요 없어요.

bindings 아래 각 항목은 서비스 식별자로 키가 지정되고 하나 또는 둘 다의 자격 증명 메커니즘을 승인해요:

• apiKey — 서비스의 저장된 API 키 주입을 승인해요. 값은 시크릿 저장소(sbx secret set <service>)에서 와요; 바인딩은 승인을 기록하지, 값을 보유하거나 찾지 않아요.
• oauth — 서비스의 OAuth 흐름을 승인해요. 호스트에서 로그인하고, 프록시가 토큰 재발급과 라우팅을 처리해요. OAuth 도메인에는 토큰 엔드포인트 호스트와 키트가 선언한 리소스 호스트가 포함돼요.

각 메커니즘은 승인한 도메인을 기록하는 domains 목록을 받아요. 키트가 기존 바인딩이 덮지 않는 도메인을 요청하면 sbx가 승인을 요청해요.

bindings:
  anthropic:
    apiKey:
      domains: [api.anthropic.com]
  github:
    apiKey:
      domains: [api.github.com, github.com]

바인딩은 승인 기록일 뿐이에요: apiKey나 oauth의 존재가 그 메커니즘을 권한 부여해요. 자격 증명을 거절하면 항목이 전혀 기록되지 않아요. 실제 자격 증명은 이 파일에 저장되지 않아요.

첫 실행 승인 (First-run approval)

써드파티 키트가 바인딩이 없는 자격 증명을 필요로 하면, sbx가 승인을 안내해요. API 키는 시크릿 저장소에 이미 있는 값을 쓰거나 프롬프트에서 입력할 수 있어요. OAuth는 로그인 흐름을 승인해요. 두 경우 모두 키트가 선언한 도메인을 승인해요. sbx가 항목을 credentials.yaml에 써요.

비대화형 맥락(CI 또는 --detached)에서는 프롬프트에 답할 사람이 없어요. sbx에서 바인딩이 없으면 샌드박스는 자격 증명을 보류한 채 시작돼요. 필수 자격 증명이라면 sbx는 샌드박스 생성에 실패하기보다 경고를 출력해요. 이는 sbx 시행의 한계예요: 키트 작성자는 샌드박스가 시작했다는 것만으로 필수 자격 증명을 쓸 수 있다고 믿으면 안 돼요.

키트를 한 번 대화형으로 실행하거나 credentials.yaml을 직접 작성해 바인딩을 미리 만들어 두세요.

바인딩 파일은 써드파티 키트가 서비스 자격 증명을 쓸 수 있는지를 관문으로 제어해요. 키트의 자격 증명 주입 규칙과 네트워크 권한이 여전히 어떤 요청이 자격 증명을 실을 수 있는지를 제한해요.

바인딩이 필요한 키트 (Kits that require a binding)

써드파티 키트는 스키마 버전과 무관하게 자격 증명을 쓰려면 여러분의 승인이 필요해요. sbx와 함께 배포된 기본 제공 키트는 요청하는 자격 증명을 바인딩 없이 쓸 수 있어요. 써드파티 v2 키트가 기본 제공 에이전트를 확장하면, 상속된 자격 증명 사용을 승인해야 해요. 같은 서비스를 스스로 요청하는 써드파티 키트도 승인해야 해요.

레지스트리 자격 증명 (Registry credentials)

레지스트리 자격 증명은 템플릿이나 키트를 pull 할 때 개인 OCI 레지스트리에 인증하며, 에이전트가 호스트 쪽 프록시를 통해 샌드박스 안에서 이미지를 pull·push 하는 데에도 쓸 수 있어요. 저장하려면 sbx secret set --registry <host>를 사용하세요. Docker Hub에서는 sbx가 sbx login 세션을 재사용해요 — 레지스트리 시크릿이 필요 없어요. 다른 레지스트리(GitHub Container Registry, ECR, ACR, 셀프호스팅 Nexus 등)는 sbx secret set --registry로 자격 증명을 저장하세요.

--all-sandboxes를 추가하거나, --sandbox SANDBOX를 추가하거나, 둘 다 전달하지 않아 범위를 선택해요:

sbx secret set [--all-sandboxes | --sandbox SANDBOX] --registry HOST

• 호스트 전용 (범위 플래그 없음): sbx CLI가 샌드박스를 만들 때 템플릿과 키트를 pull 하는 데 사용해요. 자격 증명은 호스트에 남고 샌드박스 안에서는 절대 쓸 수 없어요.
• 모든 샌드박스 (--all-sandboxes): 호스트 전용과 같고, 추가로 프록시가 샌드박스의 레지스트리 로그인 요청을 인증해요. 자격 증명은 호스트에 남고 샌드박스 파일시스템에 절대 기록되지 않아요. 에이전트가 컨테이너 이미지를 빌드·게시할 때 사용하세요.
• 샌드박스 범위 (--sandbox SANDBOX): --all-sandboxes와 같은 프록시 동작이지만 이름 있는 샌드박스에만 적용돼요. 한 샌드박스만 레지스트리 접근이 필요할 때 사용하세요.

레지스트리 자격 증명 저장하기 (Store registry credentials)

stdin에서 토큰을 파이프하고 레지스트리 호스트 이름을 대상으로 해요:

$ gh auth token | sbx secret set --registry ghcr.io --password-stdin

사용자 이름이 필요한 레지스트리(예: 관리자 계정이 있는 ACR)에는 --username을 추가해요:

$ echo "$ACR_PASSWORD" | sbx secret set \
  --registry myregistry.azurecr.io \
  --username myuser \
  --password-stdin

--all-sandboxes를 추가해 자격 증명을 모든 새 샌드박스에서 쓸 수 있게 해요:

$ gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
$ sbx run claude

샌드박스를 만들기 전에 all-sandboxes 레지스트리 자격 증명을 저장하세요. 나중에 추가된 all-sandboxes 레지스트리 자격 증명은 기존 샌드박스가 가져오지 않아요. 기존 샌드박스에 레지스트리 접근을 추가하려면 샌드박스 범위 자격 증명을 대신 사용하세요.

자격 증명을 단일 샌드박스로 범위를 한정하려면 그 샌드박스 이름 아래에 저장해요:

$ gh auth token | sbx secret set --sandbox my-app --registry ghcr.io --password-stdin

Docker Hub의 v2 키트는 sbx kit pull과 sbx kit push가 sbx login의 세션을 사용해요. 다른 레지스트리는 두 명령 모두 이 자격 증명을 사용해요. 두 명령 모두 Docker 자격 증명 저장소로 대체하므로 docker login의 자격 증명도 동작해요. v3 키트는 docker login의 자격 증명을 사용하는 Docker Buildx로 게시돼요.

개인 레지스트리 인증 엔드포인트 신뢰하기 (Trust a private registry authentication endpoint)

셀프호스팅 레지스트리가 별도 호스트를 통해 샌드박스 요청을 인증할 때는 --registry와 함께 --registry-auth-endpoint를 사용하세요. 예를 들어 registry.example.com의 셀프호스팅 GitLab 레지스트리가 Registry v2 WWW-Authenticate: Bearer 도전에서 realm으로 https://gitlab.example.com/jwt/auth를 광고할 수 있어요.

자격 증명을 저장하고 특정 샌드박스에 그 엔드포인트를 신뢰해요:

$ echo "$GITLAB_PAT" | sbx secret set --sandbox my-app \
  --registry registry.example.com \
  --username "$GITLAB_USER" \
  --registry-auth-endpoint https://gitlab.example.com/jwt/auth \
  --password-stdin

예시 호스트를 여러분의 레지스트리와 인증 호스트로 바꾸고, GITLAB_USER와 GITLAB_PAT을 GitLab 사용자 이름과 개인 접근 토큰으로 설정하세요.

이것은 프록시가 저장된 레지스트리 자격 증명을 https://gitlab.example.com/jwt/auth로 보내 레지스트리 토큰으로 교환하는 것을 허가해요. 광고된 realm은 HTTPS를 사용하고 설정된 호스트와 경로와 정확히 일치해야 해요. 그 호스트의 /jwt/auth/를 포함한 다른 경로는 덮이지 않아요. 엔드포인트 URL에는 포함된 자격 증명, 쿼리 문자열, 프래그먼트가 없어야 해요. 토큰 요청에는 service와 scope 같은 프로토콜 매개변수가 여전히 포함될 수 있어요.

이 플래그가 없으면 프록시는 레지스트리 자체 호스트와 Docker Hub의 인증 호스트 같은 기본 제공 레지스트리 관계의 인증 엔드포인트를 받아들여요. 다른 인증 호스트는 명시적 구성이 필요해요.

레지스트리 자격 증명 제거하기 (Remove registry credentials)

레지스트리의 호스트 전용과 all-sandboxes 항목을 모두 제거해요:

$ sbx secret rm --registry ghcr.io -f

호스트 전용 자격 증명은 남기고 all-sandboxes 항목만 제거하려면 --all-sandboxes를 전달해요:

$ sbx secret rm --all-sandboxes --registry ghcr.io -f

샌드박스 범위 자격 증명을 제거하려면 샌드박스 이름을 전달해요:

$ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f

모범 사례 (Best practices)

자격 증명을 제공하려면 저장된 시크릿을 사용하세요. OS 키체인이 보관 상태에서 보호하고, 키체인이 없는 Linux 호스트에서는 권한 보호 파일에 보관돼요. Where secrets are stored 문서를 보세요.

샌드박스 안에서 API 키를 수동으로 설정하지 마세요. 샌드박스 에이전트는 프록시 관리 자격 증명을 쓰도록 미리 설정되어 있어요.

레지스트리 자격 증명은 호스트에 남고, 샌드박스가 레지스트리에 인증할 때 프록시가 주입해요. 레지스트리 접근이 필요한 샌드박스에만 한정하고, 노출을 줄이려면 --all-sandboxes보다 샌드박스 범위를 선호하세요.

몇몇 에이전트가 OAuth를 또 하나의 안전한 옵션으로 지원해요: 흐름이 호스트에서 실행되므로 토큰이 샌드박스 안에 노출되지 않아요. 자격 증명을 저장하지 않았다면 에이전트가 인증을 요청해요 — Codex는 sbx run codex에서 호스트에 요청하고, Claude Code, Cursor, Droid는 샌드박스 안에서 대화형으로 요청해요. 미리 인증하려면 Codex는 sbx secret set openai --oauth를 실행하고, Claude Code는 /login을 사용하세요. Cursor와 Droid는 사전 인증 옵션이 없어서 에이전트가 시작할 때 로그인 프롬프트가 나타나요. 각 에이전트의 흐름은 개별 에이전트 페이지를 보세요.

1Password나 AWS Secrets Manager에 자격 증명을 저장한다면 Sourcing credentials from 1Password와 Sourcing credentials from AWS Secrets Manager 문서를 보세요.

커스텀 템플릿과 자리 표시자 값 (Custom templates and placeholder values)

커스텀 템플릿을 만들거나 셸 샌드박스에서 에이전트를 수동으로 설치할 때, 어떤 에이전트는 시작 전에 OPENAI_API_KEY 같은 환경 변수가 설정되어 있어야 해요. 필요하면 이 변수들을 자리 표시자 값(예: proxy-managed)으로 설정하세요. 프록시는 환경 변수 값과 무관하게 실제 자격 증명을 주입해요.

더 알아보기 (Learn more)

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