클라우드 에이전트 인증하기

클라우드 에이전트 인증하기

클라우드 에이전트는 클라우드 시크릿 스토어의 자격 증명으로 인증해요. 에이전트를 실행하기 전에 이 자격 증명을 설정해서 인증이 샌드박스 안에 저장된 파일에 의존하지 않게 해요.

출처: 문서

본문

클라우드 시크릿 스토어 사용하기

다음 시크릿 인터페이스는 서로 분리돼요.

  • sbx secret — 로컬 샌드박스용 시크릿 관리
  • sbx --cloud secret — CLI가 만든 클라우드 샌드박스용 시크릿 관리
  • Docker Agentic Platform — 웹 인터페이스를 통해 자신의 시크릿 이름 관리

한 인터페이스로 만든 자격 증명은 다른 곳에서는 사용할 수 없어요. 클라우드 샌드박스를 시작하기 전에 다음 방법 중 하나로 클라우드 자격 증명을 구성해요.

인증 방법 선택

Claude Code에는 Anthropic API 키를, Codex에는 OpenAI API 키나 계정 범위의 OpenAI OAuth 자격 증명을 사용해요. 에이전트를 해당 명령으로 구성해요.

에이전트 또는 제공자 권장 명령 인증
Claude Code sbx --cloud secret set anthropic Anthropic API 키 입력 프롬프트
OpenAI OAuth 사용 Codex sbx --cloud secret set openai --oauth OpenAI OAuth 흐름을 열고 결과 자격 증명을 계정 범위로 저장
서비스 API 키 sbx --cloud secret set <service> API 키 또는 토큰 입력 프롬프트

Codex의 경우 계정 범위에서 OpenAI OAuth를 사용하거나 sbx --cloud secret set openai로 OpenAI API 키를 저장할 수 있어요. Anthropic API 키를 저장한 뒤 Claude Code를 실행해요.

$ sbx --cloud run claude --name cloud-project

자격 증명을 샌드박스 파일시스템에서 분리하기

sbx --cloud secret으로 구성된 자격 증명은 클라우드 시크릿 스토어에 남아 샌드박스 파일시스템 밖에 있어요. 에이전트의 인터랙티브 로그인은 샌드박스 안에 자격 증명을 쓸 수 있어요. 그 파일들은 템플릿과 sbx move 스냅샷에 포함될 수 있어요. 에이전트 안에서 로그인했다면, 샌드박스를 캡처하거나 이동하기 전에 제공자의 로그아웃 지침을 따라 그 자격 증명을 제거해요.

자격 증명 범위 설정

자격 증명은 기본적으로 계정 범위를 사용해요. 계정 범위 자격 증명은 Docker 계정의 클라우드 샌드박스에 사용할 수 있어요.

$ sbx --cloud secret set github

API 키나 토큰을 이름으로 하나의 샌드박스에 범위를 한정해요.

$ sbx --cloud secret set openai --sandbox cloud-project

샌드박스 범위 시크릿은 같은 서비스의 계정 범위 시크릿보다 우선해요. 샌드박스를 만들기 전에 설정해서 CLI가 샌드박스 시작 시 포함하게 해요. OAuth 자격 증명은 샌드박스 범위를 사용할 수 없어요.

서비스 식별자

다음 표는 로컬 샌드박스용으로 문서화된 내장 서비스의 클라우드 시크릿 지원을 보여줘요.

서비스 클라우드 시크릿 인증
anthropic API 키
cursor API 키
droid API 키; 클라우드 관리 OAuth는 지원 안 함
github 토큰
google API 키
groq API 키
mistral API 키
nebius API 키
openai API 키 또는 OAuth
openrouter 커스텀 시크릿 사용

지원되는 서비스를 구성하려면 sbx --cloud secret set <service>를 실행해요. OpenAI OAuth에는 --oauth를 추가하고 계정 범위를 사용해요. 다른 서비스는 커스텀 시크릿을 구성해요.

클라우드 시크릿 명령은 레지스트리 자격 증명이나 동적 --ref, --command 리졸버를 지원하지 않아요. 환경 파일은 snapshot: true로 호스트 명령이나 볼트 참조를 한 번 해석하고 그 결과를 리터럴 클라우드 시크릿으로 업로드할 수 있어요.

커스텀 시크릿 구성하기

내장 서비스가 아닌 API에는 set-custom을 사용해요.

$ sbx --cloud secret set-custom --name project-api \
  --host api.example.com --env PROJECT_API_TOKEN

명령이 값을 입력하라는 프롬프트를 띄워요. 이 시크릿을 사용하는 샌드박스는 PROJECT_API_TOKEN에 자리 표시자를 받아요. 클라우드 프록시는 api.example.com에 대한 요청에 Authorization: Bearer ***를 설정해요. 로컬 커스텀 시크릿과 달리, 클라우드 주입은 요청에 일치하는 자리 표시자가 필요 없이 대상 호스트를 기반으로 헤더를 설정해요.

다른 헤더를 선택하려면 --header를 사용해요. 헤더를 지정하면 기본값은 원본 시크릿이에요. --format을 %s 자리 표시자 하나와 함께 사용해 접두사를 추가할 수 있어요. 예: --header Authorization --format 'Bearer %s'.

각 --host는 스킴, 포트, 경로가 없는 정확한 DNS 이름이어야 해요. 여러 호스트에는 플래그를 반복해요. IP 주소와 와일드카드는 지원되지 않아요. --sandbox cloud-project를 추가해 시크릿을 그 샌드박스로 범위를 한정하고, 샌드박스를 만들기 전에 설정해요. 커스텀 시크릿 이름은 내장 서비스 이름과 같을 수 없어요.

자격 증명 나열 및 제거

값을 노출하지 않고 클라우드 시크릿 메타데이터를 나열해요.

$ sbx --cloud secret ls

일치하는 범위에서 자격 증명을 제거해요.

$ sbx --cloud secret rm github
$ sbx --cloud secret rm openai --sandbox cloud-project
$ sbx --cloud secret rm project-api

커스텀 시크릿은 sbx --cloud secret rm --host api.example.com으로 제공하는 호스트로도 제거할 수 있어요. 제거는 확인을 요구해요. 스크립트에서는 --force를 사용해요. 클라우드 모드는 한 번에 모든 시크릿을 제거하는 걸 지원하지 않아요.

더 알아보기 (Learn more)