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

클라우드 에이전트 인증하기 (Authenticate cloud agents)

클라우드 시크릿 저장소의 자격 증명으로 클라우드 에이전트를 인증하는 방법을 알아볼게요.

출처: 문서

본문

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

클라우드 시크릿 저장소 사용하기 (Use the cloud secret store)

다음 시크릿 인터페이스들은 분리되어 있어요:

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

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

인증 방법 선택하기 (Choose an authentication method)

Claude Code에는 Anthropic API 키를 사용해요. Codex에는 OpenAI API 키 또는 계정 범위(account-scoped)의 OpenAI OAuth 자격 증명을 사용해요.

에이전트를 해당 명령으로 구성해요:

Codex의 경우 계정 범위의 OpenAI OAuth를 쓰거나 sbx --cloud secret set openai로 OpenAI API 키를 저장할 수 있어요.

Anthropic API 키를 저장한 뒤 Claude Code를 실행해요:

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

자격 증명을 샌드박스 파일시스템 밖에 두기 (Keep credentials out of the sandbox filesystem)

sbx --cloud secret으로 설정한 자격 증명은 샌드박스 파일시스템 밖인 클라우드 시크릿 저장소에 남아 있어요.

에이전트의 대화형 로그인은 샌드박스 안에 자격 증명을 쓸 수 있어요. 그 파일들은 템플릿과 sbx move 스냅샷에 포함될 수 있어요. 에이전트 안에서 로그인했다면, 제공 업체의 로그아웃 지침을 따라 샌드박스를 캡처하거나 옮기기 전에 그 자격 증명을 제거하세요.

자격 증명 범위 설정하기 (Set credential scope)

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

$ sbx --cloud secret set github

API 키나 토큰을 이름으로 한 샌드박스에 범위를 한정할 수 있어요:

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

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

서비스 식별자 (Service identifiers)

아래 표는 로컬 샌드박스용으로 문서화된 기본 제공 서비스들에 대한 클라우드 시크릿 지원을 보여줘요:

지원되는 서비스는 sbx --cloud secret set <service>로 구성해요. OpenAI OAuth는 --oauth를 추가하고 계정 범위를 사용해요.

다른 서비스는 커스텀 시크릿(custom secret)을 구성하세요.

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

커스텀 시크릿 구성하기 (Configure a custom secret)

기본 제공 서비스가 아닌 API에는 set-custom을 사용해요:

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

명령이 값을 요청해요. 이 시크릿을 쓰는 샌드박스는 PROJECT_API_TOKEN에 자리 표시자(placeholder)를 받아요. 클라우드 프록시는 api.example.com으로 가는 요청에 Authorization: Bearer ***를 설정해요. 로컬 커스텀 시크릿과 달리, 클라우드 주입은 요청에 일치하는 자리 표시자를 요구하지 않고 목적지 호스트를 기준으로 헤더를 설정해요.

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

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

자격 증명 나열하고 제거하기 (List and remove credentials)

값을 드러내지 않고 클라우드 시크릿 메타데이터를 나열해요:

$ 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)

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