시크릿 관리

시크릿 관리 (Managing Secrets)

API 키와 자격 증명을 Docker Agent에 안전하게 제공하는 방법을 알아봐요.

출처: 문서

본문

개요 (Overview)

Docker Agent는 모델 제공자(OpenAI, Anthropic 등)와 MCP 도구 서버(GitHub, Slack 등)와 통신하려면 API 키가 필요해요. 이 키들은 구성 파일에 절대 저장되지 않아요. 대신 Docker Agent는 순서대로 확인되는 시크릿 제공자 체인을 통해 런타임에 그것들을 해석해요(pkg/environment/default.go 참고):

Priority	Provider	Description
1	Environment variables	`export OPENAI_API_KEY=sk-...`
2	Docker Compose secrets	`/run/secrets/`의 파일
3	Docker Agent env file	`~/.config/cagent/.env`, `docker agent setup` 이 작성
4	Credential helper	`~/.config/cagent/config.yaml`의 `credential_helper:` 아래에 선언한 커스텀 명령
5	Docker Desktop	Docker Desktop 백엔드가 저장한 시크릿 (Desktop 설치에서 설정 불필요)

값이 있는 첫 제공자가 이겨요. 믹스앤매치할 수 있어요 — 예를 들어 한 키에는 환경 변수를, 다른 키에는 Docker Agent env file을 사용하는 것.

Note 이전 Docker Agent 버전은 macOS Keychain과 pass 비밀번호 매니저에서도 시크릿을 읽을 수 있었어요. 이 소스들은 더 이상 조회되지 않아요: 거기 저장된 키를 위 소스 중 하나로 마이그레이션하세요, 예: docker agent setup 을 다시 실행. 어떤 제공자가 값을 반환하든, 그 값이 1Password 시크릿 참조처럼 보이면(op:// 로 시작), Docker Agent는 모델 제공자나 도구에 넘기기 전에 op CLI를 통해 해석해요. Docker Agent가 --sandbox 로 에이전트를 실행하고 Docker AI 게이트웨이가 구성되면, 샌드박스 프록시가 게이트웨이 요청을 스스로 인증해요: 당신의 Docker 로그인 토큰을 게이트웨이 호스트(컨테이너 docker.com 도메인만)로의 HTTPS 요청에 주입해요. 토큰은 절대 샌드박스에 들어가지 않아요 — 그 안에서 DOCKER_TOKEN 은 프록시 관리 플레이스홀더예요.

환경 변수 (Environment Variables)

가장 간단한 접근. Docker Agent를 실행하기 전에 셸에서 변수를 설정해요:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
docker agent run agent.yaml

일반적인 변수:

Variable	Provider
OPENAI_API_KEY	OpenAI
ANTHROPIC_API_KEY	Anthropic
GOOGLE_API_KEY	Google Gemini
MISTRAL_API_KEY	Mistral
OPENROUTER_API_KEY	OpenRouter
XAI_API_KEY	xAI
NEBIUS_API_KEY	Nebius

MCP 도구는 추가 변수가 필요할 수 있어요. 예를 들어 GitHub MCP 서버는 GITHUB_PERSONAL_ACCESS_TOKEN 이 필요해요. 이것들은 구성의 env 필드로 도구에 전달돼요:

toolsets:
  - type: mcp
    ref: docker:github-official
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_PERSONAL_ACCESS_TOKEN

Env 파일 (Env Files)

편의를 위해 .env 파일에 시크릿을 저장하고 --env-from-file 로 Docker Agent에 전달할 수 있어요:

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

docker agent run agent.yaml --env-from-file .env

파일 형식은 다음을 지원해요:

한 줄에 하나씩 KEY=VALUE 쌍
# 로 시작하는 주석
따옴표가 붙은 값: KEY="value with spaces"
빈 줄은 무시

Important 시크릿을 버전 관리에 커밋하지 않도록 .env 를 .gitignore 에 추가하세요.

Docker Agent env 파일 (Docker Agent env file)

~/.config/cagent/.env 의 .env 파일(위와 같은 형식)은 --env-from-file 플래그 없이 매 실행에서 자동으로 읽혀요. 이것은 env-file 위치를 선택할 때 docker agent setup 이 API 키를 저장하는 곳이고, 손으로 편집할 수 있어요:

# ~/.config/cagent/.env
OPENAI_API_KEY=sk-...

파일은 소유자 전용 권한(0600)으로 생성되지만, 값은 평문으로 저장돼요.

Docker Compose 시크릿 (Docker Compose Secrets)

Docker Compose로 Docker Agent를 컨테이너에서 실행할 때, Compose 시크릿을 사용해 자격 증명을 안전하게 주입할 수 있어요. Compose는 /run/secrets/ 아래에 시크릿을 파일로 마운트하고, Docker Agent는 이 위치에서 자동으로 읽어요.

파일에서 (From a file)

각 시크릿을 자체 파일에 저장한 뒤 compose.yaml 에서 참조해요:

echo -n "sk-ant...here" > .anthropic_api_key

# compose.yaml
services:
  agent:
    image: docker/docker-agent
    command: run --exec /app/agent.yaml "Hello!"
    secrets:
      - ANTHROPIC_API_KEY
    volumes:
      - ./agent.yaml:/app/agent.yaml:ro

secrets:
  ANTHROPIC_API_KEY:
    file: ./.anthropic_api_key

Docker Compose는 파일을 /run/secrets/ANTHROPIC_API_KEY 로 마운트해요. Docker Agent는 추가 구성 없이 그것을 집어요.

호스트 환경 변수에서 (From a host environment variable)

CI/CD 파이프라인에서 시크릿은 종종 환경 변수로 주입돼요. Compose는 이들을 /run/secrets/ 로 전달할 수 있어요:

secrets:
  ANTHROPIC_API_KEY:
    environment: "ANTHROPIC_API_KEY"

여러 시크릿 (Multiple secrets)

services:
  agent:
    image: docker/docker-agent
    command: run --exec /app/agent.yaml "Summarize my GitHub issues"
    secrets:
      - ANTHROPIC_API_KEY
      - GITHUB_PERSONAL_ACCESS_TOKEN
    volumes:
      - ./agent.yaml:/app/agent.yaml:ro

secrets:
  ANTHROPIC_API_KEY:
    file: ./.anthropic_api_key
  GITHUB_PERSONAL_ACCESS_TOKEN:
    file: ./.github_token

환경 변수보다 Compose 시크릿을 쓰는 이유 (Why use Compose secrets over environment variables?)

Aspect	Environment Variables	Compose Secrets
저장	메모리에, `docker inspect` 로 보임	`/run/secrets/` 아래에 tmpfs 파일로 마운트
가시성	프로세스 목록과 inspect 출력에 표시	`docker inspect` 에 노출되지 않음
최적 용도	개발	프로덕션과 CI/CD

자격 증명 헬퍼 (Credential Helper)

Docker Agent는 사용자 구성에서 정의한 외부 자격 증명 헬퍼로 셸 아웃할 수 있어요. 조직에 이미 재사용하고 싶은 시크릿 데몬(HashiCorp Vault, 1Password CLI, bitwarden-cli 등)이 있을 때 유용해요.

~/.config/cagent/config.yaml 에서 헬퍼를 선언해요:

# ~/.config/cagent/config.yaml
credential_helper:
  command: op
  args: ["read", "op://Personal/docker-agent"]

명령은 마지막 인자로 변수 이름이 추가되어 호출되고, stdout으로 시크릿 값을 출력해야 해요.

Docker Desktop

Docker Desktop이 설치된 머신에서 Docker Agent는 로그인된 Docker 계정에 저장된 시크릿에 대해 Desktop의 백엔드를 질의해요. 이는 투명해요 — 추가 구성 없음 — 로그인된 Docker 사용자가 환경 변수를 설정하지 않고 제공자 API 키를 얻는 방법이에요.

Docker 인증 (Docker Authentication)

Docker 모델 게이트웨이를 통한 모델 트래픽 라우팅에는 Docker 토큰이 필요해요. Docker Desktop은 15분 동안 유효하고 Docker Agent가 갱신할 수 없는 토큰을 내놓으므로, Desktop이 제공할 유용한 것이 없을 때 — 로그아웃됐거나, 실행 중이 아니거나, 자체 갱신이 막혔거나 — Docker Agent는 docker login 이 자격 증명 저장소에 남긴 장기 액세스 토큰을 새 Docker 토큰으로 교환해요, docker login 자체가 수행하는 것과 같은 교환. 따라서 docker login 으로 로그인하는 것으로 충분해요; Docker Desktop은 필요하지 않아요.

교환되는 것은 Docker 액세스 토큰뿐이에요 — docker login 이 저장하는 dckr_… 시크릿 — 절대 계정 비밀번호가 아니고, 교환은 HTTPS로 Docker Hub로 가요. 그 결과 bearer 토큰은 Docker Agent 캐시 디렉터리 아래의 비공개 파일에 캐시되어 형제 프로세스가 자체 발행 대신 그것을 재사용하게 하고, docker logout 이나 계정 전환 후 몇 초 안에 사용이 중단돼요. 어떤 토큰이 사용 중이고 어디서 왔는지 보려면 docker agent debug auth 를 실행하세요.

DOCKER_AGENT_NO_TOKEN_EXCHANGE=1 을 설정해 거부(opt out)할 수 있어요: 그러면 Docker Agent는 Docker Desktop에만 의존해요.

1Password 참조 (1Password References)

위 체인을 통해 해석된 어떤 시크릿 값이든 리터럴 시크릿 대신 1Password 시크릿 참조일 수 있어요. 값이 op:// 로 시작하면 Docker Agent는 1Password CLI(op read <reference>)를 호출해 해석하고 결과를 사용해요.

이것은 모든 제공자와 동작해요 — 가장 흔히 환경 변수나 env 파일:

export OPENAI_API_KEY="op://Personal/OpenAI/api-key"
docker agent run agent.yaml

참조는 op://<vault>/<item>/<field> 형식을 따릅니다. op CLI가 설치되어 있고 로그인되어(op signin) 비대화형 읽기가 성공하는지 확인하세요.

Warning 해석 실패 시 동작 (Behaviour when resolution fails) 값이 op:// 로 시작하지만 op CLI가 설치되지 않았거나, 참조를 읽을 수 없으면(로그인 안 됨, 잘못된 경로, 잠긴 볼트), Docker Agent는 경고를 로그하고 빈 값을 사용해요 — 원시 op:// 참조를 모델 제공자나 도구에 절대 전달하지 않아요. 해석된 참조(및 결정적 실패)는 실행 수명 동안 캐시되고, 취소된 조회 같은 일시적 실패는 캐시되지 않으므로 이후 시도가 재시도할 수 있어요.

방법 선택 (Choosing a Method)

Method	Best for	Setup effort
Environment variables	빠른 로컬 개발, 스크립트	Low
Env files	팀 프로젝트, 여러 키	Low
Docker Agent env file	모든 프로젝트에서 사용하는 키, `docker agent setup` 이 작성	Low
Docker Compose secrets	컨테이너화된 배포, CI/CD	Medium
Credential helper	기존 시크릿 데몬(Vault, 1Password CLI, ...) 재사용	Medium
1Password references (`op://`)	이미 1Password를 쓰는 팀	Low

방법을 결합할 수 있어요. 예를 들어 장기 제공자 키는 Docker Agent env file에, 프로젝트 특정 MCP 토큰은 env 파일로 저장해요.

시크릿 누수 방지 (Preventing Secret Leaks)

제공자 키는 시크릿 저장소에 살고 위 체인을 통해 Docker Agent로 전달돼요 — 에이전트 자체는 그것들을 입력으로 받지 않아요. 하지만 대화의 내용은 여전히 자격 증명을 누출할 수 있어요: 토큰을 붙여넣는 사용자, 내장 키가 있는 구성 파일을 반환하는 도구, 프롬프트에 덤프된 트랜스크립트.

그 심층 방어 경우에는 에이전트에 redact_secrets: true 를 설정해요. 그것은 감지된 시크릿을 다음에서 지워요:

모든 전송 도구 호출의 인자 (도구가 보기 전에)
모든 전송 채팅 메시지 (모델 제공자가 보기 전에)
모든 도구의 출력 (이벤트 소비자, 영속 세션 파일, post_tool_use 훅 입력, 다음 LLM 호출에 도달하기 전에)

agents:
  root:
    model: openai/gpt-5
    description: A helpful assistant
    instruction: You are a helpful assistant.
    redact_secrets: true
    toolsets:
      - type: shell

규칙셋은 GitHub PAT, AWS / GCP / Azure 자격 증명, Stripe / Slack / GitLab / Hugging Face 토큰, JWT, PEM 인코딩 개인 키, Docker Hub PAT 등을 다뤄요. 감지된 각 span은 리터럴 [REDACTED] 로 대체돼요. 전체 그림과 누탐(false negative)에 대한 중요한 주의 사항은 에이전트 구성 참조의 Redacting Secrets 섹션 참고.

시크릿 관리