자격 증명 관리하기

자격 증명 관리하기 (Manage credentials)

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

출처: 문서

본문

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

자격 증명 주입 방식 (How credential injection works)

샌드박스가 아웃바운드 요청을 보내면 호스트 측 프록시가 세 가지를 결정해요.

1. 요청이 키트(또는 내장 에이전트)가 선언한 서비스와 일치하는지
2. 어떤 헤더를 쓸지
3. 어떤 값을 주입할지

키트가 매치와 헤더를 선언하고, 호스트에서 값을 제공해요. 프록시 관리 자격 증명의 경우 실제 값은 샌드박스에 절대 들어가지 않아요. 에이전트는 proxy-managed 같은 센티넬만 봐요. 키트는 oauth.passthrough: true를 설정해 센티넬 마스킹을 해제할 수 있어요. 이러면 실제 토큰 응답이 샌드박스로 들어가고 자격 증명 격리가 줄어요.

같은 서비스에 여러 소스가 값을 가지면 저장된 시크릿(stored secret)이 우선해요.

형식	무엇인가	언제 사용하는가
Stored secrets (sbx secret set)	OS 키체인에 서비스별로 키가 있는 값이나 동적 소스	내장 또는 키트 선언 서비스의 기본값
Custom secrets (sbx secret set-custom)	도메인과 환경 변수에 키가 있는 값	서비스 모델이 맞지 않을 때(에이전트가 변수 형식을 검증하거나 시크릿이 요청 본문에 실릴 때)
OAuth	호스트 측 로그인 흐름; 토큰이 샌드박스에 절대 들어가지 않음	에이전트가 지원할 때(Claude Code, Codex, Cursor, Droid 등)
Registry credentials (sbx secret set --registry)	이미지·키트 pull을 위한 인증	프라이빗 레지스트리에서 템플릿이나 키트 pull

값을 제공하는 것과 그 사용을 승인하는 것은 별개의 단계예요. 자격 증명 바인딩(credential bindings)은 키트가 사용을 승인한 메커니즘과 도메인을 기록해요. 자격 증명 값을 저장하지는 않아요. 멀티 제공자 에이전트(OpenCode, Docker Agent)의 경우 프록시는 호출되는 API 엔드포인트를 기준으로 자격 증명을 선택해요.

저장된 시크릿 (Stored secrets)

sbx secret set은 자격 증명 값이나 동적 시크릿 소스를 OS 키체인에 서비스 식별자에 키로 저장해요. 내장 에이전트는 고정된 서비스 집합을 선언해요. 커스텀 키트는 자신의 것을 선언할 수 있어요. 두 경우 모두 같은 sbx secret set 흐름이 동작해요.

이름이 mcp:로 시작하는 시크릿은 호스트의 MCP 게이트웨이용으로 예약돼 있어요.

시크릿이 저장되는 위치

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

• macOS: 시스템 Keychain
• Windows: Windows Credential Manager
• 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는 다시 키체인에 새 시크릿을 저장해요.

시크릿 저장하기

$ sbx secret set anthropic

이 명령은 시크릿 값을 인터랙티브하게 입력하라는 프롬프트를 띄워요. 서비스 시크릿은 기본적으로 전역이라 모든 샌드박스에 사용할 수 있어요. 시크릿을 특정 샌드박스로 범위를 한정하려면:

$ sbx secret set openai --sandbox my-sandbox

서비스 시크릿을 추가·업데이트·제거하면 재시작 없이 기존 로컬 샌드박스에 적용돼요(--command나 --ref로 구성된 시크릿 포함). 샌드박스 범위 시크릿은 전역 시크릿보다 우선해요.

MCP 시크릿

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

동적 시크릿 소스 사용하기

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

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

$ 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가 호스트에 설치되고 인증되어 있어야 해요.

참고: 특정 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와도 결합할 수 없어요.

환경 변수에서 가져오기

쉘에 이미 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로 무엇이 저장됐는지 확인해요.

내장 서비스

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

서비스	환경 변수	API 도메인
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 도메인에 대한 요청에 이를 주입해요.

키트가 선언하는 서비스

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

$ sbx secret set my-service

별도의 등록 단계는 없어요. 저장된 값과 키트의 요청은 같은 식별자를 사용해요. 프롬프트가 나타나면 키트의 자격 증명 요청을 승인해요. v3는 credential capability를, v2는 최상위 credentials 목록을 사용해요.

시크릿 나열·제거

$ 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

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

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

GitHub 토큰

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

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

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

SSH 에이전트

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 연결은 여전히 샌드박스 네트워크 정책의 적용을 받아요.

커스텀 시크릿 (Custom secrets)

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

서비스 식별자 모델에 맞지 않는 자격 증명, 예를 들어 에이전트가 부팅 시 환경 변수 형식을 검증하거나 자격 증명이 헤더가 아닌 요청 본문에 실리는 경우에는 sbx secret set-custom을 사용해요. 이 시크릿은 서비스 식별자 대신 하나 이상의 대상 도메인, 환경 변수 이름, 선택적 자리 표시자 문자열에 키가 매겨져요. 가능하면 서비스 기반 흐름을 선호해요. 키트가 배선을 처리하고 값만 제공하면 되기 때문이에요.

커스텀 시크릿 설정하기

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

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

경고: --value <secret>으로 시크릿을 전달하면 쉘 히스토리에 기록되고 사용자로 실행되는 다른 프로세스에 노출돼요. 실제 자격 증명을 인라인으로 붙여넣지 말고, 이미 환경에 있는 변수에서 값을 읽고, 커맨드라인에 실제 시크릿을 전달했다면 쉘 히스토리를 지우세요.

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

여러 호스트 대상

같은 시크릿으로 여러 도메인을 덮으려면 --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 포함)와 일치해요.

동적 커스텀 시크릿 해석

커스텀 시크릿도 동적 시크릿 소스를 받아요. --value 대신 --ref나 --command를 사용해요.

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

동적 커스텀 시크릿은 기본적으로 요청 시(on demand) 해석돼요. 해석된 값을 캐시하려면 --refresh에 기간을 전달해요. 검증과 오류 출력 플래그는 서비스 시크릿과 동일하게 동작해요. --ref와 --command는 --value나 --token과 결합할 수 없어요.

GitHub Packages에서 npm 패키지 설치

내장 github 서비스는 npm.pkg.github.com에 대한 요청에 자격 증명을 주입하지 않아요. GitHub Packages에서 프라이빗 npm 패키지를 설치하려면 그 호스트에 커스텀 시크릿을 추가해요. 호스트에서 패키지를 읽을 수 있는 토큰으로 GitHub CLI를 인증해요. GitHub 문서는 이 용도에 최소 read:packages 범위의 개인 액세스 토큰(classic)을 문서화해요. 그런 다음 토큰 소스를 등록해요.

$ 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을 그 자리 표시자로 설정해요. 실제 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

npm이 자리 표시자를 npm.pkg.github.com으로 보내고, 프록시가 호스트에서 gh auth token이 가져온 토큰으로 대체해요.

자격 증명 바인딩 (Credential bindings)

자격 증명 바인딩 파일은 각 서비스에 대해 승인한 자격 증명 메커니즘과 도메인을 기록해요. ~/.config/sbx/credentials.yaml에 있으며, Windows에서는 %APPDATA%\sbx\credentials.yaml이에요. 서드파티 키트는 스키마 버전과 무관하게 사용하는 각 자격 증명에 대해 승인된 바인딩이 필요해요. sbx는 그런 키트를 처음 실행할 때 하나를 인터랙티브하게 만들어요. 손으로 항목을 쓸 수도 있어요.

sbx에 포함된 내장 키트가 요청한 자격 증명만은 바인딩이 필요 없어요.

bindings 아래의 각 항목은 서비스 식별자에 키가 매겨지고 하나 이상의 메커니즘을 승인해요.

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

각 메커니즘은 도메인 목록을 받아요. 자격 증명을 거절하면 항목이 전혀 기록되지 않아요. 실제 자격 증명은 이 파일에 저장되지 않아요.

첫 실행 승인

서드파티 키트가 바인딩이 없는 자격 증명을 필요로 하면 sbx가 승인을 안내해요. API 키는 시크릿 저장소의 값을 사용할 수 있고, OAuth는 로그인 흐름을 승인해요. 두 경우 모두 키트가 선언한 도메인을 승인해요. sbx는 credentials.yaml에 항목을 기록해요.

비인터랙티브 컨텍스트(CI나 --detached)에서는 프롬프트에 응답할 사람이 없어요. sbx에서 바인딩이 없으면 샌드박스가 자격 증명을 보류한 채 시작돼요. 필수 자격 증명의 경우 sbx는 샌드박스 생성을 실패시키기보다 경고를 출력해요. 무인 실행 전에 키트를 인터랙티브하게 한 번 실행하거나 credentials.yaml을 직접 작성해 바인딩을 미리 만들어두어요.

바인딩 파일은 서드파티 키트가 서비스 자격 증명을 사용할 수 있는지 여부를 통제해요. 키트의 자격 증명 주입 규칙과 네트워크 권한은 여전히 어떤 요청이 자격 증명을 실을 수 있는지를 제약해요.

레지스트리 자격 증명 (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

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

레지스트리 자격 증명 저장

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

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

사용자 이름이 필요한 레지스트리(예: admin 계정이 있는 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 레지스트리 자격 증명을 가져오지 않아요. 기존 샌드박스에 레지스트리 접근을 추가하려면 샌드박스 범위 자격 증명을 사용해요.

단일 샌드박스로 범위를 한정하려면 샌드박스 이름 아래에 저장해요.

$ 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로 게시돼요.

프라이빗 레지스트리 인증 엔드포인트 신뢰하기

자체 호스트 레지스트리가 별도 호스트를 통해 샌드박스 요청을 인증할 때 --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의 인증 호스트 같은 내장 레지스트리 관계의 인증 엔드포인트를 받아들여요. 다른 인증 호스트는 명시적 구성이 필요해요.

레지스트리 자격 증명 제거

레지스트리의 host-only와 all-sandboxes 항목을 모두 제거하려면:

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

all-sandboxes 항목만 제거하고 host-only 자격 증명은 남기려면 --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 호스트에서는 권한 보호 파일에 보관돼요.
• 샌드박스 안에서 API 키를 수동으로 설정하지 마세요. 샌드박스 에이전트는 proxy-managed 자격 증명을 사용하도록 미리 구성돼요.
• 레지스트리 자격 증명은 호스트에 남고 샌드박스가 레지스트리 인증 시 프록시가 주입해요. 레지스트리 접근이 필요한 샌드박스에만 예약하고, 노출을 줄이려면 --all-sandboxes보다 샌드박스 범위를 선호해요.
• 여러 에이전트가 OAuth를 안전한 옵션으로 지원해요. 흐름이 호스트에서 실행되므로 토큰이 샌드박스 안에서 노출되지 않아요.
• 자격 증명을 저장하지 않았다면 에이전트가 인증하도록 프롬프트를 띄워요. Codex는 sbx run codex에서 호스트에 프롬프트를 띄우고, Claude Code·Cursor·Droid는 샌드박스 안에서 인터랙티브하게 프롬프트를 띄워요. 미리 인증하려면 Codex는 sbx secret set openai --oauth를, Claude Code는 /login을 사용해요.
• 1Password나 AWS Secrets Manager에 자격 증명을 저장한다면 Sourcing credentials from 1Password와 Sourcing credentials from AWS Secrets Manager를 참고해요.

커스텀 템플릿과 자리 표시자 값

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

더 알아보기 (Learn more)

• Docker Sandboxes 인증·권한
• Docker Sandboxes 클라우드 인증