CLI 레퍼런스

CLI 레퍼런스 (CLI Reference)

모든 Docker Agent 명령줄 명령과 플래그의 완전한 참조 문서예요.

출처: 문서

본문

모든 Docker Agent 명령줄 명령과 플래그의 완전한 참조예요.

팁 — 구성 불필요: 구성 인자 없이 docker agent run을 실행하면 현재 디렉토리의 docker-agent.yaml, docker-agent.yml, 또는 docker-agent.hcl을 사용해요. 없으면 빠른 실험에 완벽한 내장 기본 에이전트를 사용해요.

명령 (Commands)

docker agent run

에이전트 구성(.yaml, .yml, .hcl)으로 대화형 TUI를 시작해요.

$ docker agent run [ config ] [ message... ] [ flags ]

플래그	설명
`-a, --agent <name>`	구성에서 특정 에이전트 실행
`--yolo`	도구 호출 자동 승인(명시적으로 거부되지 않은 한). `--safety autonomous`의 레거시 별칭.
`--safety <mode>`	도구 승인 안전 모드: `strict`(모두 물어봄), `balanced`(안전한 호출 자동 승인), `restricted`(안전한 호출 자동 승인, 나머지 거부 — 무인 실행용 fail-closed), `autonomous`(모두 승인). 둘 다 주어지면 `--yolo`를 이겨요. 플래그가 없으면 별칭/사용자 구성 기본값으로 폴백하고, 그다음 에이전트 YAML의 `agents.<name>.safety` / `runtime.safety`; 재개된 세션은 `--safety` / `--yolo`가 명시적으로 전달되지 않으면 저장된 모드를 유지해요. Safety Modes 참조.
`--model <ref>`	모델(들) 재정의. 모든 에이전트에 `provider/model`, 특정 에이전트에 `agent=provider/model`. 여러 재정의는 쉼표 구분.
`--session <id>`	이전 세션 재개. 상대 참조 지원(`-1` = 생성 시간 기준 최신, `-2` = 두 번째 최신, … — 마지막 사용이 아닌 생성 순서). 아직 존재하지 않는 명시적 ID는 그 ID로 생성되므로 감독 프로세스가 세션 ID를 미리 소유하고 여러 실행에서 재사용할 수 있어요.
`-s, --session-db <path>`	SQLite 세션 데이터베이스 경로(기본: `<data-dir>/session.db` — `--data-dir`가 없으면 `~/.cagent/session.db`).
`--session-read-only`	TUI를 읽기 전용으로 열기: 대화 기록은 표시되지만 LLM에 새 메시지를 보낼 수 없어요. `--exec`와는 못 써요.
`--prompt-file <path>`	파일 내용을 추가 시스템 컨텍스트로 포함(반복 가능).
`--attach <path>`	초기 메시지에 이미지 파일 첨부
`--dry-run`	아무것도 실행하지 않고 에이전트 초기화(구성 검증에 유용).
`--remote <addr>`	로컬 대신 주소의 원격 런타임 사용. `--sandbox`, `--worktree`, `--worktree-pr`, `--worktree-base`, `--session`, `--session-db`, `--record`, `--fake`와 상호 배타 — 원격 런타임은 자체 세션 저장소·실행 환경을 소유하므로 이 로컬 전용 고려 사항이 적용되지 않아요.
`--listen <addr>`	외부 프로세스가 실행 중인 TUI를 구동할 수 있도록 이 run의 제어판을 HTTP로 노출(후속 전송, 이벤트 스트림, 제목 읽기). `host:port` 또는 `unix://`, `npipe://`, `fd://` 허용. `debug`처럼 안정적이지만 고급/자동화 지향 플래그라 `docker agent run --help`에서 숨김. 전체 워크스루는 API Server 가이드 참조.
`--session-workingdir-root <path>`	`--listen` 제어판으로 생성된 세션의 `working_dir`을 이 디렉토리와 하위로 한정(기본: 제한 없음 — `..`를 포함한 원시 값은 거부되지만 깨끗한 호스트 디렉토리는 허용). 제어판이 다른 사용자에게 도달 가능할 때 권장. `--listen`처럼 `--help`에서 숨김.
`--lean`	대체 화면이 아닌 단순화된 TUI 사용. 기본 전체 화면 TUI와 달리 일반 터미널 버퍼에 인라인으로 렌더링 — 대체 화면이 싫은 환경(tmux 팬, tty가 있는 CI, 로그 친화적 파이프라인)에 유용. 전체 TUI처럼 채팅이 비면 시작 시 ASCII 아트 배너 표시.
`--app-name <name>`	TUI에 표시되는 애플리케이션 이름 라벨 재정의(상태 표시줄, 창 제목, "/exit" 알림).
`--sidebar`	사이드바 가시성 제어. `--sidebar=false`로 설정하면 사이드바를 숨기고 Ctrl+B 토글을 비활성화(기본: `true`).
`--disable-commands <list>`	TUI에서 특정 슬래시 명령을 숨기고 비활성화. 쉼표 구분 명령 이름 목록 허용(앞 슬래시 선택, 대소문자 구분 없음). 예: `--disable-commands="/cost,/eval,/model"`.
`--theme <name>`	이름으로 TUI 테마 미리 선택, 또는 `auto`로 터미널 light/dark 배경 따르기(사용자 구성 테마 재정의; 대화형 TUI 밖에서는 무시).
`--on-event <type>=<cmd>`	해당 유형의 이벤트 발생 시 셸 명령 실행(`*=<cmd>`는 모든 이벤트 매칭). 반복 가능.
`--json`	결과를 newline-delimited JSON으로 출력(`--exec`와 함께 사용).
`--hide-tool-calls`	출력에서 도구 호출 숨기기
`--hide-tool-results`	출력에서 도구 호출 결과 숨기기
`--sandbox`	`sbx`를 사용해 샌드박스 모드로 에이전트 실행(Sandbox 참조).
`--template <image>`	샌드박스용 템플릿 이미지(기본: `docker/docker-agent-sbx-templates:latest`).
`--no-kit`	auto-kit 비활성화: 스킬이나 프롬프트 파일을 샌드박스에 스테이징하지 않음.
`--agent-picker [refs]`	시작 전에 전체 화면 대화형 피커 표시 — 에이전트 탐색·선택. 선택적 쉼표 구분 에이전트 참조 목록 허용(기본: 내장 default·coder 에이전트 + `~/.agents`에서 찾은 에이전트 구성). 화살표 키 탐색; `?`는 YAML 미리보기 패널 토글; `l`(또는 마우스 클릭)은 Lean Mode 체크박스 토글 — lean TUI로 시작; `b`(또는 [ Open Board ] 클릭)는 에이전트 실행 대신 Kanban 보드(`docker agent board`) 열기; Enter 확인. `--exec` 또는 비-TTY 모드에서는 사용 불가.
`-w, --worktree [name]`	작업 디렉토리의 새 git worktree에서 에이전트 실행 — 체크아웃에서 변경을 격리. 선택적으로 명명(`--worktree=my-feature`); 아니면 이름 생성. 작업 디렉토리가 git 저장소 안에 있어야 함. 모든 도구(셸 포함)가 worktree 안에서 실행돼요. 다른 저장소에서 분기하려면 `--working-dir`과 결합, 나중에 같은 worktree로 재개하려면 `--session`과 결합. `--remote`나 `--sandbox`와는 결합 불가. 세션이 끝나면 깨끗한 worktree는 자동 제거; 작업이 있으면 유지/제거 프롬프트(`--exec`에서는 절대 안 함).
`--worktree-base <ref>`	현재 `HEAD` 대신 `<ref>`(브랜치, 태그, 커밋, 또는 `origin/main` 같은 원격 추적 ref)에서 `--worktree` 분기. 원격 추적 ref는 먼저 fetch되어 worktree가 최신 원격 상태에서 시작해요. `--worktree` 필요. `--worktree-pr`, `--remote`, `--sandbox`와는 결합 불가.
`--worktree-pr <number\|url>`	기존 GitHub pull request(PR 번호, `#123`, 또는 PR URL)에 체크아웃된 git worktree에서 에이전트 실행. PR의 브랜치를 계속해 커밋이 다시 푸시되도록 해요. GitHub CLI(`gh`) 필요. `--worktree`, `--remote`, `--sandbox`와는 결합 불가.
`--working-dir <path>`	세션의 작업 디렉토리 설정(도구와 상대 경로에 적용).
`--env-from-file <path>`	파일에서 환경 변수 로드(반복 가능).
`--flavor <name>`	구성의 `flavors` 섹션 아래 정의된 YAML 패치인 구성 flavor 활성화(반복 가능, 순서대로 적용). Flavors 참조.
`--code-mode-tools`	JavaScript로 다른 도구를 호출하는 단일 도구 제공(code-mode 도구를 전역으로 강제).
`--models-gateway <addr>`	모델 트래픽을 게이트웨이로 라우팅. `DOCKER_AGENT_MODELS_GATEWAY`(레거시 `CAGENT_MODELS_GATEWAY`) env var도 읽음.
`--hook-pre-tool-use <cmd>`	pre-tool-use 훅 명령 추가(반복 가능). Hooks 참조.
`--hook-post-tool-use <cmd>`	post-tool-use 훅 명령 추가(반복 가능).
`--hook-session-start <cmd>`	session-start 훅 명령 추가(반복 가능).
`--hook-session-end <cmd>`	session-end 훅 명령 추가(반복 가능).
`--hook-on-user-input <cmd>`	on-user-input 훅 명령 추가(반복 가능).
`--hook-stop <cmd>`	모델 응답 완료 시 발화하는 stop 훅 명령 추가(반복 가능).
`--fake <path>`	카세트 파일에서 AI 응답 재생(테스트용). `--record`와 상호 배타.
`--fake-stream [ms]`	`--fake`로 재생 시 청크 사이 지연으로 스트리밍 시뮬레이션(값 없이 주면 15ms 기본).
`--record [path]`	AI API 상호작용을 카세트 파일에 기록하고 세션에서 TUI e2e 테스트 생성(경로 없으면 파일명 자동 생성). `--models-gateway`가 구성되면 경유.
`-d, --debug`	디버그 로깅 활성화
`--log-file <path>`	커스텀 디버그 로그 위치
`-o, --otel`	OpenTelemetry 관측 가능성 활성화: traces, metrics, logs. 컬렉터로 내보내려면 `OTEL_EXPORTER_OTLP_ENDPOINT` 필요.

# Examples
$ docker agent run agent.yaml
$ docker agent run agent.yaml "Fix the bug in auth.go"
$ docker agent run agent.yaml -a developer --yolo
$ docker agent run agent.yaml --model anthropic/claude-sonnet-4-5
$ docker agent run agent.yaml --model "dev=openai/gpt-4o,reviewer=anthropic/claude-sonnet-4-5"
$ docker agent run agent.yaml --session -1 # resume last session
$ docker agent run agent.yaml --session -1 --session-read-only # review last session without sending messages
$ docker agent run agent.yaml --prompt-file ./context.md # include file as context

# Add hooks from the command line
$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh"
$ docker agent run agent.yaml --hook-pre-tool-use "./scripts/validate.sh" --hook-post-tool-use "./scripts/log.sh"

# Queue multiple messages (processed in sequence)
$ docker agent run agent.yaml "question 1" "question 2" "question 3"

# Customize TUI display
$ docker agent run agent.yaml --app-name "My Project"
$ docker agent run agent.yaml --sidebar = false
$ docker agent run agent.yaml --disable-commands = "/cost,/eval,/model"

# Browse and pick an agent interactively
$ docker agent run --agent-picker
$ docker agent run --agent-picker = myorg/coder,myorg/researcher

팁 — Lean 인라인 TUI: --lean을 전달하면 터미널에 인라인으로 렌더링하는 가벼운 TUI를 얻어요(대체 화면 없음). 전체 TUI처럼 채팅이 비면 시작 시 ASCII 아트 배너를 표시하고 같은 슬래시 명령과 스트리밍 출력을 지원해 tmux, 스크립트, 또는 전체 화면 쟁탈이 싫은 어떤 컨텍스트에서도 편리해요.

팁 — git worktree에서 run 격리: 작업 디렉토리가 git 저장소 안에 있으면 --worktree가 새 git worktree를 만들고 세션을 그쪽에 가리켜 에이전트의 편집이 별도 브랜치에 놓이고 체크아웃을 절대 건드리지 않아요. 모든 도구 — 셸 포함 — 가 worktree 안에서 실행돼요. worktree는 worktree-<name> 브랜치의 <data-dir>/worktrees/<name>에 저장돼요.

# Run in an isolated worktree with a generated name (e.g. "focused_turing")
$ docker agent run agent.yaml --worktree
$ docker agent run agent.yaml -w "Refactor the auth package"

# Give the worktree (and its branch) an explicit name
$ docker agent run agent.yaml --worktree = auth-refactor

# Branch the worktree from another ref instead of the current HEAD.
# A remote-tracking ref is fetched first, so the worktree starts from the
# latest remote state.
$ docker agent run agent.yaml --worktree = auth-refactor --worktree-base origin/main

# Resume a worktree run later: the session remembers its worktree, so you
# don't pass --worktree again (which would fail — the worktree already exists).
$ docker agent run agent.yaml --worktree = auth-refactor # first run, creates it
$ docker agent run agent.yaml --session -1 # resumes into the same worktree

# Check out an existing GitHub pull request to continue it (requires gh)
$ docker agent run agent.yaml --worktree-pr 123
$ docker agent run agent.yaml --worktree-pr https://github.com/owner/repo/pull/123

--worktree-pr로 PR의 헤드 브랜치가 원격을 추적하며 체크아웃되므로(GitHub CLI를 통해) run 중 만든 커밋이 PR로 바로 푸시돼요. worktree는 <data-dir>/worktrees/pr-<number>에 저장돼요.

대화형 세션이 끝나면 worktree는 상태에 따라 정리돼요:

깨끗(커밋되지 않은 변경·추적되지 않은 파일·새 커밋 없음): worktree와 브랜치가 자동 제거돼요.
작업 있음(커밋되지 않은 변경·추적되지 않은 파일·새 커밋): 유지 또는 제거 프롬프트. 유지는 디렉토리와 브랜치를 보존해 나중에 돌아올 수 있고, 제거는 worktree·브랜치·모든 작업을 버려요.
비대화형 실행(--exec): worktree는 절대 정리되지 않음 — 검사를 위해 제자리에 남겨둬요.

worktree는 오직 --worktree가 이 run을 위해 만든 경우에만 제거돼요. 기존 worktree는 절대 건드리지 않아요.

유지된 worktree는 재개할 수 있어요: --session(상대 참조 -1이나 세션 id)을 전달하면 run이 같은 worktree 디렉토리·브랜치에 자동으로 재연결돼요. 재개 시 --worktree를 다시 전달하지 마세요 — 새 worktree를 만들려다 이미 존재해서 실패할 거예요.

docker agent run --exec

에이전트를 비대화형(헤드리스) 모드로 실행. TUI 없음 — 출력은 stdout으로.

$ docker agent run --exec [ config ] [ message... ] [ flags ]

# One-shot task
$ docker agent run --exec agent.yaml "Create a Dockerfile for a Python Flask app"

# With auto-approve
$ docker agent run --exec agent.yaml --yolo "Set up CI/CD pipeline"

# Multi-turn conversation
$ docker agent run --exec agent.yaml "question 1" "question 2" "question 3"

docker agent new

새 에이전트 구성 파일을 대화형으로 생성.

$ docker agent new [ flags ]

# Examples
$ docker agent new
$ docker agent new --model openai/gpt-5
$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15

docker agent getting-started

채팅 UI 안에서 짧은(약 2분) 건너뛸 수 있는 대화형 투어 실행: 메시지 전송, 도구 호출 승인, 명령 팔레트(Ctrl+K), 슬래시 명령, 에이전트 구성 방법. docker agent tour로 별칭. 대화형 터미널 필요.

$ docker agent getting-started

이 명령 또는 실행 중인 TUI 세션 안의 /getting-started 슬래시 명령으로 언제든 다시 재생해요.

docker agent models

--model과 함께 사용 가능한 모델 나열. 기본적으로 자격 증명이 있는 provider의 모델만 표시. 별칭: docker agent models list, docker agent models ls.

$ docker agent models [ flags ]

플래그	기본값	설명
`-p, --provider <id>`	(없음)	provider 이름으로 모델 필터(예: `openai`, `anthropic`, `dmr`, `ollama`, …).
`--format <fmt>`	`table`	출력 형식: `table` 또는 `json`.
`-a, --all`	`false`	자격 증명이 있는 것뿐 아니라 모든 provider의 모델 포함.

# Examples
$ docker agent models # only providers you can use
$ docker agent models --all # every provider the catalog knows about
$ docker agent models --provider openai
$ docker agent models --format json | jq

models gateway가 구성되면(--models-gateway, DOCKER_AGENT_MODELS_GATEWAY, 또는 사용자 구성) 명령은 먼저 게이트웨이의 /v1/models 엔드포인트를 조회해요. 비어 있지 않은 응답은 게이트웨이로 라우팅되는 모델에 대해 권위적이에요: 목록은 게이트웨이가 서빙하는 모델을 보여주고(--provider는 그 안에서 필터), 자체 엔드포인트에서 모델을 서빙하는 구성된 커스텀 provider들이 옆에 나와요. 게이트웨이를 조회할 수 없거나 쓸 모델을 서빙하지 않으면(엔드포인트 미구현, 빈 목록, 잘못된 응답, 시간 초과, 인증 누락) 명령은 직접 구성한 provider(provider API 키, provider 별칭, 커스텀 provider)와 모델 카탈로그로 폴백해요. 한 소스의 실패가 다른 소스가 나열되는 것을 절대 막지 않아요. Docker Desktop 토큰은 게이트웨이가 신뢰할 수 있는 Docker URL을 대상으로 할 때만 전송(및 요구)돼요.

docker agent toolsets

에이전트 구성에서 사용 가능한 내장 toolset 유형 나열. 각 유형은 에이전트 YAML 파일의 toolsets: 아래에서 참조할 수 있어요. 터미널을 떠나지 않고 무엇이 가능한지 발견하는 데 사용해요.

$ docker agent toolsets [ flags ]

플래그	기본값	설명
`--format <fmt>`	`table`	출력 형식: `table` 또는 `json`.

# Examples
$ docker agent toolsets # human-readable table
$ docker agent toolsets --format json | jq # machine-readable (type, summary, docs URL)

docker agent setup

모델을 대화형으로 설정. 네 가지 경로:

내장 클라우드 provider: Docker Agent가 이미 아는 provider(Anthropic, OpenAI, Google, Groq, Hugging Face, ...)를 골라 연결. 자격 증명은 provider마다 다름: 대부분 API 키나 토큰을 받아 Docker Agent env 파일 ~/.config/cagent/.env에 저장하는 반면, chatgpt는 브라우저에서 ChatGPT 계정으로 로그인.
로컬 모델: Docker Model Runner를 확인하고 모델을 pull. API 키 불필요.
커스텀 OpenAI 호환 엔드포인트: 내장되지 않은 엔드포인트(vLLM, LiteLLM, 기업 게이트웨이, ...)를 base URL, API 형식, API 키 변수와 함께 등록 — 사용자 구성에 저장되어 --model <name>/<model>로 그 모델이 어디서든 동작.
Claude Code harness: 공식 claude CLI를 통해 Claude 구독 사용. 마법사는 CLI가 설치·로그인됐는지 확인하고, claude auth login --claudeai 실행을 제안하고(확인 후에만), 즉시 실행 가능한 claude-code-agent.yaml을 작성해요. Coding Harnesses 참조.

채팅을 시작할 정확한 명령으로 끝나요. 시크릿 값은 절대 출력되지 않고, Docker Agent는 Claude CLI의 자격 증명을 절대 읽거나 복사하지 않아요.

마법사는 대화형 run이 쓸 수 있는 모델을 찾지 못할 때도 자동으로 제공돼요(거부 가능; DOCKER_AGENT_NO_SETUP=1로 제공 억제).

$ docker agent setup

docker agent doctor

모델과 자격 증명 설정을 진단. 어떤 모델 provider에 자격 증명이 있고 각 자격 증명이 어디서 오는지(셸 환경, env 파일, Docker Desktop, …), Docker Model Runner에 도달 가능한지와 어떤 모델이 pull됐는지, 자동 선택이 어떤 모델을 고를지 보고해요. 시크릿 값은 절대 출력되지 않아요. 에이전트 실행을 막을 문제가 있으면 0이 아닌 상태로 종료해 스크립트·CI에서 사용 가능하게 해요.

$ docker agent doctor [ agent-file | registry-ref ] [ flags ]

에이전트 파일과 함께, 그 파일이 요구하는 환경 변수(모델 자격 증명과 GITHUB_PERSONAL_ACCESS_TOKEN 같은 도구 시크릿), 각각 설정 여부, 어느 소스에서 왔는지도 나열해요. 파일이 claude-code harness 에이전트를 선언하면 doctor는 추가로 공식 claude CLI가 설치·로그인됐는지 확인하고 버전과 안전한 로그인 메타데이터(인증 방법, API provider, 구독 유형 — 이메일·조직·토큰은 절대 아님)를 보고해요. 누락되거나 로그아웃된 CLI는 claude auth login --claudeai 수정과 함께 문제로 보고돼요.

플래그	기본값	설명
`--json`	`false`	전체 보고서를 JSON 형식으로 출력(스크립팅용).
`--env-from-file <file>`	(없음)	env 파일이 제공하는 변수도 확인.
`--models-gateway <url>`	(없음)	models gateway에 대해 진단(자격 증명이 그것에서 옴).

# Examples
$ docker agent doctor # credential, DMR, and auto-selection state
$ docker agent doctor ./agent.yaml # also check that file's requirements
$ docker agent doctor --json | jq .issues

docker agent serve api

프로그래매틱 접근용 HTTP API 서버 시작. 인자는 단일 에이전트 파일, 레지스트리 참조, 또는 디렉토리일 수 있음 — 디렉토리를 주면 그 안의 모든 .yaml / .yml / .hcl 파일이 /api/agents 아래 별도 항목으로 노출돼요.

$ docker agent serve api <agent-file> | <agents-dir> | <registry-ref> [ flags ]

플래그	기본값	설명
`-l, --listen <addr>`	`127.0.0.1:8080`	수신 주소.
`--auth-token <token>`	(없음)	모든 API 요청에 필요한 Bearer 토큰. 설정하면 모든 요청이 `Authorization: Bearer ***`를 포함해야 해요. 비우면 인증 비활성화(루프백 인터페이스에서만 수신할 때 안전).
`--max-request-size <bytes>`	`1048576` (1 MiB)	최대 요청 본문 크기. 이 한도 초과 요청은 HTTP 413로 거부 — Troubleshooting: HTTP 413 참조.
`--session-workingdir-root <path>`	(없음)	`POST /api/sessions`로 생성된 세션의 `working_dir`을 이 디렉토리와 하위로 한정(검사 전 심링크 해석). 기본 무제한 — `..`를 포함한 원시 값은 거부되지만 깨끗한 호스트 디렉토리는 허용(로컬 단일 사용자 데몬이 의존). 다중 사용자 또는 네트워크 노출 배포에 권장.
`-s, --session-db <path>`	`session.db`	SQLite 세션 데이터베이스 경로(상대 경로는 작업 디렉토리 기준 해석).
`--pull-interval <minutes>`	`0`	OCI/URL 참조를 주기적으로 다시 pull하고 에이전트 정의 새로 고침. `0`은 auto-pull 비활성화.
`--fake <path>`	(없음)	카세트 파일에서 AI 응답 재생(테스트용). `--record`와 상호 배타.
`--record [path]`	(없음)	AI API 상호작용을 카세트 파일에 기록. `--models-gateway`가 구성되면 경유.
`--mcp-oauth-redirect-uri <url>`	(없음)	서버 모드의 unmanaged MCP OAuth 흐름용 OAuth redirect URI. 설정하면 런타임이 PKCE와 code exchange를 프로세스 내에서 구동하고 전체 authorize URL을 elicitation으로 클라이언트에 보내요. Remote MCP 참조.

진단: CAGENT_PPROF_ADDR=127.0.0.1:6060(또는 숨김 플래그 --pprof-addr)을 설정해 /debug/pprof/에서 라이브 Go pprof 서버 시작. 루프백 주소 사용; 비 루프백 바인딩은 보안 경고를 로그해요.

모든 런타임 구성 플래그(--working-dir, --env-from-file, --models-gateway, --hook-*, …)도 받아들여요.

# Examples
$ docker agent serve api agent.yaml
$ docker agent serve api agent.yaml --listen :8080
$ docker agent serve api ./agents/ # directory of agent YAML/HCL configs
$ docker agent serve api ociReference --pull-interval 10 # auto-refresh

전체 HTTP API 참조는 API Server 참조.

docker agent serve mcp

에이전트를 MCP 도구로 노출 — Claude Desktop, Claude Code, 또는 다른 MCP 클라이언트에서 사용. 기본 stdio transport; --http는 스트리밍 HTTP 서버 시작.

$ docker agent serve mcp <config> [ flags ]

플래그	기본값	설명
`-a, --agent <name>`	(모든 에이전트)	노출할 에이전트 이름. 생략하면 구성의 모든 에이전트를 별도 도구로 노출.
`--tool-name <name>`	(에이전트 이름)	클라이언트가 호출하는 MCP 도구 식별자 재정의. 단일 에이전트 노출 시에만 유효.
`--http`	`false`	stdio 대신 스트리밍 HTTP transport 사용.
`--safety <policy>`	`restricted`	HTTP MCP 안전 정책; stdio나 `--attach`에는 효과 없음.
`--auth-token <token>`	(없음)	HTTP MCP 요청에 필요한 Bearer 토큰.
`--insecure-no-auth`	`false`	비 루프백 HTTP MCP 바인딩의 인증 없는 허용.
`-l, --listen <addr>`	`127.0.0.1:8081`	수신 주소(`--http`에서만 사용).
`--mcp-keepalive <dur>`	`0` (비활성화)	MCP keep-alive ping 사이 간격(예: `30s`).
`--attach [target]`	(없음)	pid, 주소, 또는 세션 id로 실행 중인 TUI run에 첨부; 값 없이 주면 가장 최근 run 선택.

모든 런타임 구성 플래그도 받아들여요.

# Examples
$ docker agent serve mcp agent.yaml # stdio transport
$ docker agent serve mcp agent.yaml --http --listen 127.0.0.1:9090 # streaming HTTP
$ docker agent serve mcp agent.yaml --working-dir /path/to/project
$ docker agent serve mcp myorg/coder

자세한 설정은 MCP Mode 참조.

docker agent serve a2a

A2A(Agent-to-Agent) 프로토콜 서버 시작.

$ docker agent serve a2a <config> [ flags ]

플래그	기본값	설명
`-a, --agent <name>`	(팀 기본)	실행할 에이전트 이름. 지정하지 않으면 팀의 첫 에이전트 기본.
`-l, --listen <addr>`	`127.0.0.1:8082`	수신 주소.
`-s, --session-db <path>`	`<data-dir>/session.db`	SQLite 세션 데이터베이스 경로.

모든 런타임 구성 플래그도 받아들여요.

# Examples
$ docker agent serve a2a agent.yaml
$ docker agent serve a2a agent.yaml --listen 127.0.0.1:9000
$ docker agent serve a2a myorg/agent:tag

docker agent serve acp

stdio 위에 ACP(Agent Client Protocol) 서버 시작. 외부 클라이언트가 ACP 프로토콜로 에이전트와 상호작용할 수 있게 해줘요.

$ docker agent serve acp <config> [ flags ]

플래그	기본값	설명
`-s, --session-db <path>`	`<data-dir>/session.db`	SQLite 세션 데이터베이스 경로.

모든 런타임 구성 플래그도 받아들여요.

# Examples
$ docker agent serve acp agent.yaml
$ docker agent serve acp ./team.yaml
$ docker agent serve acp myorg/agent:tag

Agent Client Protocol에 대한 자세한 내용은 ACP 참조.

docker agent serve chat

/v1/chat/completions와 /v1/models의 OpenAI 호환 Chat Completions API로 하나 이상의 에이전트를 노출하는 HTTP 서버 시작. 이미 OpenAI 프로토콜을 말하는 어떤 도구든 — 예를 들어 Open WebUI, curl, OpenAI Python SDK, LangChain — 커스텀 통합 없이 Docker Agent 에이전트를 구동할 수 있어요.

$ docker agent serve chat <config> [ flags ]

플래그	기본값	설명
`-a, --agent <name>`	(모든 에이전트)	노출할 에이전트 이름. 생략하면 구성의 모든 에이전트를 별도 모델로 노출.
`-l, --listen <addr>`	`127.0.0.1:8083`	수신 주소.
`--cors-origin <origin>`	(없음)	허용 CORS origin(예: `https://example.com`). 비우면 CORS 비활성화.
`--api-key <token>`	(없음)	클라이언트가 제시해야 하는 Bearer 토큰(`Authorization: Bearer ***`). 비우면 인증 비활성화.
`--api-key-env <name>`	(없음)	이 비어 있지 않은 환경 변수에서 필수 API 키 읽기.
`--insecure-no-auth`	`false`	비 루프백 바인딩의 인증 없는 허용.
`--safety <policy>`	`restricted`	도구 안전 정책; CLI 값이 에이전트/런타임 구성 재정의.
`--max-request-size <bytes>`	`1048576` (1 MiB)	최대 요청 본문 크기. 이 한도 초과 요청은 HTTP 413로 거부 — Troubleshooting: HTTP 413 참조.
`--request-timeout <dur>`	`5m`	요청당 시간 초과(모델 + 도구 호출 + 스트리밍 포함).
`--conversations-max <n>`	`0`	`X-Conversation-Id` 키로 서버 측에 최대 N개 대화 캐시. `0`은 비활성화 — 클라이언트가 기록을 재전송해야 함.
`--conversation-ttl <dur>`	`30m`	캐시된 대화가 퇴거되는 유휴 TTL.
`--max-idle-runtimes <n>`	`4`	에이전트당 풀링되는 최대 유휴 런타임 수. `0`은 풀링 비활성화.

# Examples
$ docker agent serve chat agent.yaml
$ docker agent serve chat ./team.yaml --agent reviewer
$ docker agent serve chat myorg/agent:tag --listen 127.0.0.1:9090
$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN

# Drive it from any OpenAI-compatible client
$ curl http://127.0.0.1:8083/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}'

전체 기능 참조는 Chat Server 참조.

docker agent board

한 번에 여러 에이전트를 오케스트레이션하는 전체 화면 Kanban TUI 시작. 각 카드는 격리된 git worktree의 자체 tmux 세션에서 에이전트를 실행해요. 카드를 파이프라인(Dev → Review → Push → Done)을 따라 앞으로 옮기면 목적지 열의 프롬프트가 그 카드의 에이전트로 전달돼요. 프로젝트와 열 프롬프트는 전역 구성 파일(~/.config/cagent/config.yaml)에 저장되고 TUI에서 관리할 수 있어요.

$ docker agent board

인자나 플래그를 받지 않아요. tmux와 git이 설치되어 있어야 해요.

키 바인딩, 구성, 워크플로우 세부 사항은 Kanban Board 참조.

OCI 레지스트리를 통해 에이전트 공유.

# Push an agent
$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest

# Pull an agent
$ docker agent share pull docker.io/username/my-agent:latest

# Force pull, overwriting the local copy
$ docker agent share pull docker.io/username/my-agent:latest --force

플래그	적용	설명
`--force`	pull	로컬에 이미 있어도 강제 pull

전체 레지스트리 워크플로우는 Agent Distribution 참조.

docker agent sessions diff

기록된 두 세션을 비교하고 에이전트가 다르게 행동한 첫 지점을 보고 — 어제 동작하던 작업이 오늘 안 되는 이유에 대한 3차 분류(triage) 답.

$ docker agent sessions diff <session-a> <session-b> [ flags ]

$ docker agent sessions diff -1 -2
Comparing a1b2c3d4 (7 turns) against e5f6a7b8 (9 turns)

❌ First divergence at turn 3 (after 3 matching turn(s)).
a1b2c3d4 called:
  read_file({"path":"pkg/cache/cache.go"})
e5f6a7b8 called:
  search_files_content({"query":"persistToDisk","path":"."})

Everything after this point is downstream of the divergence and is not compared.

세션 참조는 전체 ID, 고유 ID 접두사, 또는 가장 최근 run의 -1 같은 상대 형태를 받아들여요.

플래그	기본값	설명
`-s, --session-db`	`<data-dir>/session.db`	세션 데이터베이스 경로
`--json`	`false`	비교를 JSON으로 방출
`--fail-on-divergence`	`false`	두 세션이 갈라지면 0이 아닌 값으로 종료

비교는 어시스턴트의 산문이 아닌 도구 호출 시퀀스에 대한 것이에요: 모델 출력은 비결정적이라 같은 작업의 두 실행은 거의 항상 같은 일을 하면서 표현을 다르게 해요. 위임된 하위 에이전트가 수행한 턴은 시퀀스에 포함돼요. 보고는 첫 갈라짐에서 멈춰요 — 그 이후의 모든 것은 그 차이의 다운스트림이에요.

이것은 두 실행이 어디에서 갈라졌는지 찾는 것이지 왜 인지는 아니에요. 환경을 고정한 채 다른 모델에 대해 세션을 재실행하는 것은 별개의 미구축 기능이에요.

docker agent eval

기록된 세션 디렉토리에 대해 에이전트 평가 실행.

$ docker agent eval <agent-file> | <registry-ref> [ <eval-dir> | ./evals ] [ flags ]

플래그	기본값	설명
`-c, --concurrency`	num CPUs	동시 평가 실행 수
`--judge-model`	`anthropic/claude-opus-5`	LLM-as-a-judge 관련성 점수 모델(형식: `provider/model`).
`--output <dir>`	`<eval-dir>/results`	결과·로그·세션 데이터베이스 디렉토리
`--only <pattern>`	(전체)	이 패턴과 일치하는 파일명의 평가만 실행(반복 가능)
`--base-image`	(기본)	평가 컨테이너용 커스텀 기본 이미지
`--container-runtime`	`docker`	평가 빌드·실행용 컨테이너 런타임 실행 파일(예: `podman`).
`--keep-containers`	`false`	평가 후 컨테이너 유지(`--rm`으로 제거하지 않음).
`-e, --env`	(없음)	컨테이너에 전달할 환경 변수(`KEY` 또는 `KEY=VALUE`, 반복 가능).
`--repeat <n>`	`1`	각 평가 반복 횟수(기준 계산에 유용).
`--baseline <file>`	(없음)	이전에 저장된 run JSON(`<output>/<run>.json`)과 비교하고 회귀 시 0이 아닌 값으로 종료.
`--regression-tolerance <n>`	`0`	`--baseline`이 회귀를 보고하기 전에 집계 품질 비율이 떨어질 수 있는 정도(0–1).

모든 런타임 구성 플래그도 받아들여요.

# Examples
$ docker agent eval agent.yaml # use ./evals
$ docker agent eval agent.yaml ./my-evals # custom directory
$ docker agent eval agent.yaml -c 8 # 8 concurrent evaluations
$ docker agent eval agent.yaml --keep-containers # keep containers for debugging
$ docker agent eval agent.yaml --only "auth*" # only run matching evals
$ docker agent eval agent.yaml --repeat 5 # repeat each eval 5 times
$ docker agent eval agent.yaml --container-runtime podman # use a Docker-compatible runtime such as Podman

평가 세션 생성과 결과 해석은 Evaluation 참조.

docker agent version

docker-agent 설치의 버전과 커밋 해시 출력.

$ docker agent version
docker agent version v1.54.0
Commit: 1737035c

docker agent alias

빠른 접근용 에이전트 별칭 관리.

# List aliases
$ docker agent alias ls

# List aliases as JSON
$ docker agent alias list --json

# Add an alias
$ docker agent alias add pirate /path/to/pirate.yaml
$ docker agent alias add other ociReference

# Add an alias with runtime options
$ docker agent alias add yolo-coder myorg/coder --yolo
$ docker agent alias add careful-coder myorg/coder --safety balanced
$ docker agent alias add fast-coder myorg/coder --model openai/gpt-4o-mini
$ docker agent alias add safe-coder myorg/coder --sandbox
$ docker agent alias add turbo myorg/coder --yolo --model anthropic/claude-sonnet-4-5

# Use an alias
$ docker agent run pirate
$ docker agent run yolo-coder

별칭 옵션: 별칭은 사용 시 자동 적용되는 런타임 옵션을 포함할 수 있어요:

--yolo — 별칭 실행 시 도구 호출 자동 승인(명시적으로 거부되지 않은 한). --safety autonomous의 레거시 별칭.
--safety <mode> — 별칭 실행 시 기본 안전 모드(strict, balanced, restricted, autonomous). 별칭의 yolo 옵션을 이겨요. 둘 다 사용자 구성(aliases.<name>.safety / aliases.<name>.yolo)에 선언적으로 저장되므로 손으로도 편집할 수 있어요.
--model <ref> — 별칭의 모델 재정의
--hide-tool-results — 별칭 실행 시 TUI에서 도구 호출 결과 숨기기
--sandbox — 별칭을 항상 Docker 샌드박스 안에서 실행

별칭 안전 옵션은 새 세션의 기본값이에요: 명령줄의 명시적 --safety / --yolo가 이기고, 이것들은 settings.safety / settings.YOLO와 에이전트 YAML에 선언된 어떤 것도 이기며, 재개된 세션의 모드는 절대 바꾸지 않아요.

별칭 나열 시 옵션은 대괄호로 표시돼요:

$ docker agent alias ls
Registered aliases (3):

  fast-coder → myorg/coder [ model = openai/gpt-4o-mini ]
  turbo → myorg/coder [ yolo, model = anthropic/claude-sonnet-4-5 ]
  yolo-coder → myorg/coder [ yolo ]

Run an alias with: docker agent run <alias>

--json을 전달하면 형식화된 표 대신 JSON 배열로 별칭을 출력해요. 각 항목은 별칭 이름과 옵션을 포함해요:

$ docker agent alias list --json
[
  {
    "name": "fast-coder",
    "path": "myorg/coder",
    "model": "openai/gpt-4o-mini"
  },
  {
    "name": "turbo",
    "path": "myorg/coder",
    "yolo": true,
    "model": "anthropic/claude-sonnet-4-5"
  },
  {
    "name": "yolo-coder",
    "path": "myorg/coder",
    "yolo": true
  }
]

JSON 출력은 이름으로 정렬되고 false/0 값 필드를 생략해요. 스크립팅과 자동화에 유용해요.

팁 — 별칭 옵션 재정의: 명령줄 플래그가 별칭 옵션을 재정의해요. 예를 들어 docker agent run yolo-coder --yolo=false는 별칭이 켜져 있어도 yolo 모드를 비활성화해요.

팁 — 기본 에이전트 설정: 기본 별칭을 만들어 docker agent가 인자 없이 시작하는 것을 커스터마이즈해요:

$ docker agent alias add default /my/default/agent.yaml

그러면 docker agent만 실행하면 그 에이전트가 자동으로 시작돼요.

docker agent sandbox

모든 --sandbox run이 공유하는 설정 관리 — 오늘날은, Blocked by network policy 403을 한 줄의 영구 수정으로 바꾸는 영구 네트워크 allowlist:

# Allow a host on every subsequent --sandbox run.
$ docker agent sandbox allow api.example.com

# Or several at once.
$ docker agent sandbox allow api.example.com registry.npmjs.org:443

# See what's persisted in ~/.config/cagent/config.yaml.
$ docker agent sandbox list

# Drop a host you no longer need.
$ docker agent sandbox deny api.example.com

항목은 게이트웨이, kit 해결 도구 설치 호스트, 에이전트가 선언한 runtime.network_allowlist와 합집합돼요. 시작 요약이 각 소스를 별도로 나열해 어떤 구멍이 어떤 레이어로 뚫렸는지 볼 수 있어요.

docker agent plans

에이전트가 협업하는 플랜을 호스트에서 관리 — 세션을 시작하지 않고. 두 가지 플랜 시스템이 다뤄져요:

공유 플랜(Shared plans) — plan toolset의 명명되고 버전 관리된 문서. 완전 관리 가능: 생성, 업데이트, 상태 설정, 내보내기, 삭제.
세션 플랜(Session plans) — "draft, review, execute" 워크플로우의 세션별 단일 플랜. 여기서는 읽기 전용(list, get, export) — 그들은 세션에 속하고 그 안에서 바뀌어요. 세션 플랜을 대상으로 한 변경은 대신 무엇을 해야 하는지 설명하는 unsupported 오류로 실패해요.

$ docker agent plans <subcommand> [ flags ]

서브커맨드	설명
`list [--session <id>]`	scope, name, status, version, updated time, title과 함께 공유 플랜 나열. `--session`으로 해당 세션의 플랜이 존재하면 먼저 나열. 존재하지만 읽을 수 없는 플랜은 `--json`의 `warnings` 필드처럼 stderr로 경고로 보고되어 누락으로 오인되지 않아요.
`get <name>`	플랜 출력. 콘텐츠는 stdout, 간결한 메타데이터 줄은 stderr로 — 그래서 `> file`은 콘텐츠만 잡아요(바이트 정확 사본은 `export` 사용). `get --session <id>`는 세션의 플랜을 출력하고 이름은 생략(`--scope shared\|session`으로 명시적 구분, `--session`만으로 세션 scope 암시).
`create <name> --file <path>`	`--file`(필수 — CLI는 절대 프롬프트하지 않음; `--file -`는 stdin 읽음)의 콘텐츠로 새 공유 플랜 생성. 생성 전용: 기존 이름은 덮어쓰는 대신 버전 충돌로 실패. `--title`, `--author`, `--status`는 메타데이터 설정.
`update <name> --file <path>`	기존 공유 플랜의 콘텐츠 교체(절대 생성하지 않음). 생략된 `--title` / `--author` / `--status` 플래그는 현재 값을 보존하고, 전달하면(비어도) 덮어써요.
`status <name> <status>`	본문을 건드리지 않고 공유 플랜의 자유 형식 상태 설정(버전 증가).
`export <name> --output <path>`	플랜 콘텐츠를 바이트 정확하게 파일에 기록(부모 생성, 원자적 쓰기). 기존 대상은 거부(`invalid_argument`)되고 그대로 둠. 기존 일반 파일을 원자적으로 교체하려면 `--force` 추가. 두 scope 모두 동작: `export --session <id> --output <path>`.
`delete <name>`	공유 플랜 삭제. `--force` 삭제는 손상된 플랜도 복구.

--file(일반 파일 또는 --file -의 stdin)로 전달된 플랜 콘텐츠는 플랜 저장소 자체가 적용하는 것과 같은 한도인 10 MiB로 제한되고, 디렉토리나 비 일반 파일(장치, named pipe)은 미리 거부돼요. 위반은 invalid_argument 오류로 실패해요.

동시성 가드: 모든 변경(update, status, delete)은 상호 배타적 플래그 둘 중 정확히 하나를 요구해요 — CLI는 헤드리스이고 절대 프롬프트하지 않아요:

--expected-version <n> — 마지막에 읽은 버전(get이나 list에서; ≥ 1이어야 함). 그 사이 플랜이 바뀌었으면 버전 충돌로 실패하고, 현재 버전을 보고하며, 플랜을 그대로 두고 코드 3으로 종료(다른 모든 실패는 1).
--force — 낙관적 잠금 가드 없이 의도적으로 쓰기(라스트 라이터 승리).

create는 가드를 받지 않아요: 본질적으로 생성 전용이고 이름이 이미 있으면 충돌(exit code 3).

JSON 출력: 모든 서브커맨드가 --json을 받아들여요. 성공 문서는 최상위 "schema_version": "1" 마커와 안정적인 service-model 키(plans, plan, export, deleted) — 필드는 snake_case(updated_at, session_id, bytes_written; 0/알 수 없는 updated_at은 생략) — 로 stdout에 가고, 빈 플랜 목록은 []로 인코딩되며 산문이나 ANSI는 섞이지 않아요. 실패는 stderr에 단일 JSON 객체 출력:

{"schema_version":"1","error":{"code":"conflict","message":"...","scope":"shared","name":"p","expected_version":1,"current_version":2}}

code는 conflict(expected_version·current_version 포함), not_found, invalid_argument, unsupported, corrupt, storage, error 중 하나이고 실패가 담고 있으면 scope, name, op가 포함돼요. 서브커맨드 실행 전 수행되는 검증도 다뤄져요: 누락된 필수 플래그, 위반된 --expected-version / --force 그룹 규칙, 잘못된 위치 인자는 --json이 있을 때 같은 JSON 객체(invalid_argument)로 보고돼요. 하나의 잔여물: 플래그는 왼쪽에서 오른쪽으로 파싱되고 첫 번째 알 수 없는 플래그나 잘못된 플래그 값에서 멈추므로, 그런 오류는 명령줄에서 그 앞에 --json이 나타날 때만 JSON으로 보고돼요. plans 서브커맨드가 전혀 해결되기 전에 발생한 오류(예: 알 수 없는 서브커맨드)도 일반 텍스트로 남아요.

# Examples
$ docker agent plans list
$ docker agent plans list --json | jq '.plans[].name'
$ docker agent plans create release --file ./plan.md --title "Release plan" --status draft
$ cat plan.md | docker agent plans create release --file -
$ docker agent plans get release > plan.md # content only; metadata on stderr
$ docker agent plans update release --file ./plan.md --expected-version 1
$ docker agent plans status release done --expected-version 2
$ docker agent plans export release --output ./plan.md
$ docker agent plans export release --output ./plan.md --force # replace an existing file
$ docker agent plans delete release --expected-version 3
$ docker agent plans delete scratch --force
$ docker agent plans get --session <session-id> # a session's plan
$ docker agent plans export --session <session-id> --output ./session-plan.md

플랜은 데이터 디렉토리 아래(기본 ~/.cagent/plans/와 ~/.cagent/session_plans/)에 살므로 --data-dir이 명령이 작동하는 저장소를 선택해요.

docker agent debug

에이전트 구성이 어떻게 해석되는지 검사하고 진단 출력을 생성하는 문제 해결 서브커맨드 — 구성이 기대대로 동작하지 않을 때 유용. debug는 docker agent --help에 나타나지 않지만(진단 표면이지 일상 명령이 아님), 아래 모든 서브커맨드는 안정적이고 완전히 지원돼요.

$ docker agent debug <subcommand> [ flags ]

서브커맨드	설명
`config <agent-file>`	에이전트 구성의 완전히 해석된 표준(canonical) 형태 출력(기본 적용, 참조 해석).
`toolsets <agent-file>`	구성의 각 에이전트가 노출하는 모든 toolset을 각 도구의 이름·설명과 함께 나열.
`skills <agent-file>`	각 에이전트에 대해 발견된 스킬 나열, fork된 스킬 표시.
`title <agent-file> <question>`	TUI가 쓰는 것과 같은 제목 생성 경로(구성된 `title_model` 포함)로 `<question>`의 세션 제목 생성 — 세션을 시작하지 않고. Session Titles 참조.
`auth`	사용 중인 토큰의 파싱된 Docker 인증 정보 출력(source, subject, issuer, expiry, username/email). 머신 판독 출력은 `--json` 추가.
`oauth list`	저장된 MCP OAuth 토큰 나열(resource, scope, expiry, redacted access token). `--json`으로 머신 판독 출력.
`oauth remove <resource-url>`	저장된 MCP OAuth 토큰 제거.
`oauth login <agent-file> <mcp-name>`	구성에 선언된 원격 MCP 서버에 이름 또는 URL로 대화형 OAuth 로그인 수행. Remote MCP Servers 참조.

# Examples
$ docker agent debug config agent.yaml
$ docker agent debug toolsets agent.yaml
$ docker agent debug skills agent.yaml
$ docker agent debug title agent.yaml "How do I configure a fallback model?"
$ docker agent debug auth --json
$ docker agent debug oauth list
$ docker agent debug oauth login agent.yaml github

경고 — debug auth --json은 전체 bearer 토큰을 출력해요: debug auth의 텍스트 출력은 토큰을 짧은 미리보기로 잘라내지만, --json은 완전하고 서툴지않은 JWT를 token 필드에 포함해요. debug auth --json 출력을 로그, 이슈 트래커, 버그 보고에 절대 붙여넣지 마세요 — 그 토큰을 가진 사람은 누구나 Docker에 대해 당신으로서 행동할 수 있어요. 진단 출력을 공유할 때는 일반 텍스트 출력을 사용하거나(또는 직접 token 필드를 서툴게) — debug auth --json 출력을 로그, 이슈 트래커, 버그 보고서에 절대 붙여넣지 마세요.

Source 필드는 토큰이 어디서 왔는지 말해줘요: docker desktop, 또는 docker login이 저장한 액세스 토큰을 교환해 얻었을 때 그 액세스 토큰에서 주조됨. Docker authentication 참조.

config, toolsets, skills, title 서브커맨드는 런타임 구성 플래그(--working-dir, --models-gateway, …)도 받아들이고, title은 제목 생성 전에 구성을 해석하는 데 쓰는 모델을 재정의하는 --model도 추가로 받아들여요.

docker agent completion

bash, zsh, fish, powershell용 셸 완성 스크립트 생성.

$ docker agent completion <bash | zsh | fish | powershell>

# Examples
# Bash: load for the current session
$ source <(docker agent completion bash)

# Zsh: install permanently (adjust the path for your $fpath)
$ docker agent completion zsh > "${fpath[1]}/_docker-agent"

셸별 설치 지침은 docker agent completion <shell> --help를 실행하세요.

자체 업데이트 (Self-update)

독립형 GitHub 릴리스 바이너리에서 설치했을 때 Docker Agent는 스스로 업데이트하도록 옵트인할 수 있어요. 기본적으로 비활성화. DOCKER_AGENT_AUTO_UPDATE를 진실값(1, true, yes, on)으로 설정해 명령이나 셸 세션에서 활성화해요:

$ DOCKER_AGENT_AUTO_UPDATE = 1 docker agent run

활성화하면 모든 명령이 실행 전에 최신 GitHub 릴리스를 확인해요. 더 새로운 릴리스가 있으면 대화형 세션은 설치할지 묻고, 비대화형 세션(CI, 파이프된 입력)은 자동으로 진행돼요. 예/yes를 누르면 Docker Agent가 OS/아키텍처용 자산을 다운로드하고, 체크섬을 검증하며, 현재 바이너리를 교체하고, 같은 인자로 재실행해요. 전체 메커니즘은 fail-safe: 어떤 단계에서든 실패하면 현재 바이너리를 실행하는 것으로 폴백해요. 자체 업데이트는 version, help, --help / -h(서브커맨드별 도움말 포함), completion, Docker CLI 플러그인 메타데이터 핸드셰이크에는 절대 트리거되지 않아요.

전체 워크스루는 Optional Self-Updates 참조. Docker Desktop과 Homebrew 설치는 이미 업데이트를 관리하므로 필요 없어요.

전역 플래그 (Global Flags)

이 플래그들은 모든 docker agent 명령에서 사용할 수 있어요:

플래그	설명
`-d, --debug`	디버그 로깅 활성화(기본 위치: `~/.cagent/cagent.debug.log`).
`--log-file <path>`	커스텀 디버그 로그 위치(`--debug`에서만 사용).
`-o, --otel`	OpenTelemetry 관측 가능성 활성화: traces, metrics, logs. 컬렉터로 내보내려면 `OTEL_EXPORTER_OTLP_ENDPOINT` 필요.
`--cache-dir <path>`	캐시 디렉토리 재정의(기본: macOS에서 `~/Library/Caches/cagent`).
`--config-dir <path>`	구성 디렉토리 재정의(기본: `~/.config/cagent`). `DOCKER_AGENT_CONFIG_DIR`(레거시 `CAGENT_CONFIG_DIR`) env var도 읽음.
`--data-dir <path>`	데이터 디렉토리 재정의(기본: `~/.cagent`. session.db, worktrees, plans 보유).
`--help`	어떤 명령이든 도움말 표시

OpenTelemetry 환경 변수

--otel이 활성화되면 표준 OTel SDK env var가 존중돼요(OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES 등). GenAI 계측을 제어하는 Docker Agent 전용 변수 두 개:

변수	기본값	설명
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	`false`	`true`로 설정하면 프롬프트 텍스트, 모델 응답, 도구 인자, 도구 결과를 span 속성으로 캡처. 이 필드가 PII를 포함할 수 있어 기본 꺼짐.
`OTEL_SEMCONV_STABILITY_OPT_IN`	(이중 방출)	`gen_ai_latest_experimental`로 설정하면 GenAI 시맨틱 규칙에서 스펙 정의 `gen_ai.` 키만 방출. 기본 이중 방출 모드는 기존 대시보드가 계속 동작하도록 `gen_ai.`와 레거시 키 둘 다 방출.

런타임 구성 플래그 (Runtime Configuration Flags)

이 플래그들은 에이전트를 로드하는 모든 명령(run, run --exec, new, eval, serve api, serve mcp, serve a2a, serve acp, serve chat)이 받아들여요. 반복을 피하려고 여기 한 번만 나열해요.

플래그	설명
`--working-dir <path>`	세션의 작업 디렉토리 설정(도구와 상대 경로에 적용).
`--env-from-file <path>`	파일에서 환경 변수 로드(반복 가능).
`--flavor <name>`	구성의 `flavors` 섹션 아래 정의된 YAML 패치인 구성 flavor 활성화(반복 가능, 순서대로 적용). Flavors 참조.
`--code-mode-tools`	JavaScript로 다른 도구를 호출하는 단일 도구 제공(code-mode 도구를 전역으로 강제).
`--models-gateway <addr>`	모델 트래픽을 게이트웨이로 라우팅. `DOCKER_AGENT_MODELS_GATEWAY`(레거시 `CAGENT_MODELS_GATEWAY`) env var 읽음.
`--hook-pre-tool-use <cmd>`	pre-tool-use 훅 명령 추가(반복 가능). Hooks 참조.
`--hook-post-tool-use <cmd>`	post-tool-use 훅 명령 추가(반복 가능).
`--hook-session-start <cmd>`	session-start 훅 명령 추가(반복 가능).
`--hook-session-end <cmd>`	session-end 훅 명령 추가(반복 가능).
`--hook-on-user-input <cmd>`	on-user-input 훅 명령 추가(반복 가능).
`--hook-stop <cmd>`	모델 응답 완료 시 발화하는 stop 훅 명령 추가(반복 가능).
`--mcp-oauth-redirect-uri <url>`	unmanaged OAuth 모드로 실행되는 MCP 서버의 OAuth `redirect_uri`로 광고할 공개 HTTPS URL. 설정하면 docker-agent가 클라이언트가 하길 기대하는 대신 프로세스 내에서 PKCE와 code exchange를 구동해요. Remote MCP 참조.

에이전트 참조 (Agent References)

구성을 받아들이는 명령은 여러 참조 유형을 지원해요:

유형	예
로컬 파일	`./agent.yaml`
OCI 레지스트리	`docker.io/username/agent:latest`
Hub 축약형	`myorg/agent:tag`
별칭	`pirate`(`docker agent alias add` 이후)
기본	(인자 없음) — 프로젝트 구성 또는 내장 기본 에이전트 사용

참고 — 디버깅: 문제가 있나요? 디버그 모드, 로그 분석, 일반적인 해결책은 Troubleshooting 참조.

CLI 레퍼런스