설치
설치 (Installation)
몇 분 만에 시스템에서 Docker Agent를 실행해보세요.
출처: 문서
본문
사전 요구 사항 (Prerequisites)
- 하나 이상의 AI 제공자(OpenAI, Anthropic, Google 등)용 API 키
- 선택 사항: Docker Desktop — 컨테이너화된 MCP 도구와 Docker Model Runner 실행용
Docker Desktop (사전 설치됨) — Docker Desktop (Pre-installed)
Docker Desktop 4.63부터 Docker Agent는 이미 사용 가능해요. 별도 설치가 필요 없어요 — 터미널을 열고 실행만 하면 돼요:
$ docker agent version
Tip Docker Desktop은 Docker Agent를 번들로 포함하고 최신 상태로 유지해요. 특히 Docker MCP 도구와 Docker Model Runner를 쓰고 싶다면 시작하기 가장 쉬운 방법이에요.
Homebrew (macOS / Linux)
Homebrew로 Docker Agent를 설치해요:
# Install
$ brew install docker-agent
# Verify
$ docker-agent version
docker-agent 바이너리를 ~/.docker/cli-plugins 에 복사해 docker CLI 플러그인으로도 설치할 수 있어요. 그러면 docker agent version 을 실행할 수 있어요.
바이너리 릴리스 다운로드 (Download Binary Releases)
GitHub Releases 페이지에서 Windows, macOS, Linux용 사전 빌드 바이너리 릴리스를 다운로드해요.
macOS / Linux
# Download the latest release
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-${OS}-${ARCH}" -o docker-agent
chmod +x docker-agent
sudo mv docker-agent /usr/local/bin/
docker-agent version
# or alternatively, instead of moving to /usr/local/bin:
mkdir -p ~/.docker/cli-plugins
sudo mv docker-agent ~/.docker/cli-plugins
docker agent version
Windows
릴리스 페이지에서 docker-agent-windows-amd64.exe 를 다운로드하고 docker-agent.exe 로 이름을 바꿔 PATH에 추가해요. 또는 ~/.docker/cli-plugins 로 옮길 수도 있어요.
선택적 자체 업데이트 (Optional Self-Updates)
Docker Agent가 독립 GitHub 릴리스 바이너리에서 설치된 경우 DOCKER_AGENT_AUTO_UPDATE 를 참값(1, true, yes, on)으로 설정해 자동 자체 업데이트를 선택(opt in)할 수 있어요:
# Enable for one command
DOCKER_AGENT_AUTO_UPDATE=1 docker agent run
# Or enable for the current shell session
export DOCKER_AGENT_AUTO_UPDATE=1
docker agent run
자체 업데이트가 활성화되면 Docker Agent는 일반 명령이 실행되기 전에 최신 GitHub 릴리스를 확인해요. 더 새로운 릴리스가 있고 세션이 대화형이면 Docker Agent는 설치할지 현재 버전을 계속 실행할지 물어요. 예라고 답하면(또는 CI나 파이프 입력 같은 비대화형 세션이면, 그 경우 업데이트가 자동으로 진행됨) OS와 아키텍처용 자산을 다운로드하고, 릴리스가 제공한 SHA-256 다이제스트/체크섬을 검증하며, 현재 바이너리를 교체하고, 같은 인자로 명령을 재시작해요.
자체 업데이트는 안전 실패(fail-safe)해요: 확인, 다운로드, 검증, 설치, 재시작 중 실패하면 Docker Agent는 현재 바이너리를 계속 실행해요. version/help/completion 명령과 Docker CLI 플러그인 메타데이터 핸드셰이크는 자체 업데이트를 트리거하지 않아요.
Note 패키지 매니저 설치 (Package-manager installs) Docker Desktop과 Homebrew는 이미 Docker Agent 업데이트를 관리해요. 그 방식으로 설치했다면 그 업데이트 메커니즘을 선호하세요. 자체 업데이트는 주로 독립 릴리스 바이너리를 위한 것이에요.
소스에서 빌드 (Build from Source)
최신 기능을 위해, 또는 기여하려면 소스에서 빌드해요:
사전 요구 사항 (Prerequisites)
- Go 1.26 이상
- Task (빌드 도구)
- golangci-lint (린팅용)
# Clone the repository
git clone https://github.com/docker/docker-agent.git
cd docker-agent
# Build the binary
task build
# The binary is at ./bin/docker-agent
./bin/docker-agent --help
Tip Windows에서 빌드 (Building on Windows) Windows에서는
task build대신task build-local을 사용하세요. 이는 Docker Buildx를 사용해 Docker 컨테이너 안에서 바이너리를 빌드해서, Windows 특화 툴체인 설정과 CGo 크로스 컴파일 문제를 피해요. 출력은./dist디렉터리로 나가요.
API 키 설정 (Set Up API Keys)
Docker Agent는 사용하려는 모델 제공자의 API 키가 필요해요. 환경 변수로 설정해요:
# Pick one (or more) depending on your provider
export OPENAI_API_KEY="sk-..." # OpenAI
export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic
export GOOGLE_API_KEY="AI..." # Google Gemini (or GEMINI_API_KEY)
export GITHUB_TOKEN="ghp-..." # GitHub Copilot (PAT with copilot scope)
export MISTRAL_API_KEY="..." # Mistral
export OPENROUTER_API_KEY="..." # OpenRouter
지원 제공자와 환경 변수의 전체 목록은 Configuration Overview 참고.
Note 에이전트 YAML에서 구성한 제공자(들)의 키만 있으면 돼요. Docker Model Runner (DMR)를 쓰면 API 키가 필요 없어요 — 모델이 로컬에서 실행돼요.
설치 확인 (Verify Installation)
# Check the version
$ docker agent version
# Run the default agent
$ docker agent run
# Or run an agent from an OCI registry
$ docker agent run myorg/agent:tag
다음 단계 (What's Next?)
- Quick Start — 5분 안에 첫 에이전트를 만들고 실행.
- Troubleshooting — 뭔가 안 되나요? 디버그 모드, 일반적인 문제, 해결책.