CAGENT_PPROF_ADDR is kept as a legacy alias. The new cop enforces the
DOCKER_AGENT_ prefix convention for all new environment variables.
Assisted-By: claude-sonnet-4-5
Mirrors the --max-request-size flag that serve chat already has.
- Add Option/WithMaxRequestBytes to pkg/server via functional-options
(variadic, so all existing NewWithManager/New call sites compile
untouched and keep the 1 MiB default).
- Register --max-request-size PersistentFlag on the serve api command
(int64 bytes, default 1<<20) and thread the value through server.New.
- BodyLimit middleware is global on the echo instance, so the cap applies
consistently to every /api route including POST /api/sessions/:id/messages.
- Oversized requests return HTTP 413 (Request Entity Too Large).
- Tests: existing default-cap test kept; new table tests for custom cap
on the messages route, plus zero/negative fallback to 1 MiB.
- Docs: add --max-request-size row to the api-server CLI Flags table.
Closes#3937
Validate raw working directory values before path normalization, classify client path failures as bad requests, and document the clean-path requirement.
Add a dedicated opt-in root for session working directories created through the HTTP control plane. Resolve symlinks and reject paths outside the configured root while preserving unrestricted local-daemon behavior by default.\n\nDocument the deployment boundary and cover traversal, sibling, symlink, and compatibility cases.
Replace all agentcatalog/pirate and agentcatalog/* examples with generic
myorg/agent:tag placeholders across code, docs, schema, and tests. Rename
examples/sub-agents-from-catalog.yaml to sub-agents-from-registry.yaml and
skip it in teamloader tests since the placeholder repo doesn't exist.
Assisted-By: claude-sonnet-4-5
Replace prose/front-matter uses of 'docker-agent' with 'Docker Agent'
across docs/features/{a2a,acp,api-server,chat-server,cli,evaluation,
mcp-mode,remote-mcp,skills,snapshots,tui}. Also fixes one stale
command typo in remote-mcp (`docker-agent serve api` -> `docker agent
serve api`, matching the correct form used elsewhere on the same page).
Preserved unchanged: canonical/alias URLs, docker/docker-agent repo and
examples/ links, the docker-agent binary name, sandbox template image
refs, the literal MCP elicitation meta keys (docker-agent/type,
docker-agent/server_url, docker-agent/authorize_url,
docker-agent/state), a literal API JSON response value
("owned_by":"docker-agent"), config filenames, and CLI anchor links
(#docker-agent-serve-chat).
session.Session.mu now makes AddMessage/branch/fork race-free against a
live RunStream, but a message injected or edited mid-stream (mid-tool-call
in particular) can still desynchronize the in-flight turn from what the
model/tools expect. As defense in depth on top of the locking, reject the
mutation outright while the session has an active stream.
The check reuses the same activeRuntimes.streaming lock RunSession already
uses to serialize concurrent RunSession calls (TryLock/Unlock), so it can
never race a stream that starts between the check and the mutation: both
require sm.mux, which AddMessage/UpdateMessage hold for their entire body.
The existing ErrSessionBusy sentinel (already mapped to 409 for runAgent)
is reused and now also returned by AddMessage/UpdateMessage; server.go maps
it to 409 Conflict for both endpoints.
Documents the two message endpoints (previously missing from the API
reference) and their new 409 behavior.
Refs #3590
The Jekyll layout renders a canonical link when a page sets
canonical: front matter (added with the preview banner in #3413), but
no page carried a value yet. Set it on all 90 content pages mounted
on docs.docker.com so search engines treat the stable docs as
authoritative, completing phase 3.2 of #3371.
Every generated URL was verified to return 200 on docs.docker.com,
and the rendered site carries the tag on exactly those 90 pages
(homepage and 404 excluded). docs.docker.com itself ignores the
param: its head template always canonicalizes to the page permalink.
Companion change for the Hugo module mount in docker/docs (#3371,
phase 2.1). Mounted pages must match docs.docker.com conventions:
- drop the body H1: both layouts now render the front matter title
(the Jekyll layout prints it like docs.docker.com does; the homepage
keeps its hero)
- add weight front matter derived from the _data/nav.yml order so the
docs.docker.com sidebar matches the github.io navigation
- add linkTitle where the nav label differs from the page title
- add section _index.md files with title, description, and weight;
Jekyll ignores underscore-prefixed files so github.io is unaffected
- add aliases mapping the docs.docker.com URLs of the hand-authored
pages being replaced (tutorial, best-practices, evals, local-models,
model-providers, rag, sharing-agents, integrations/*, reference/*)
onto their mounted equivalents so no URL breaks
Implements the source-side cleanup for the docs.docker.com Hugo module
mount (#3371, phase 1.1):
- replace Liquid relative_url links with plain relative Markdown links
- drop permalink front matter (paths already match the URLs)
- convert HTML callouts to GitHub-style alerts (NOTE, TIP, IMPORTANT,
WARNING), keeping custom titles as a bold lead line
- replace theme HTML card and feature grids with Markdown lists
- add keywords front matter to every content page
- document the new callout, link, and availability badge conventions
in STYLE.md
- tune the markdownlint config to the house style; docs lints clean
Also fixes pre-existing issues surfaced by the conversion: an undefined
site.examples_url variable, a malformed Liquid URL, two absolute links
that bypassed the baseurl, two broken heading anchors, HTML entities
rendering literally inside code spans, and a dead Docker Sandboxes URL.
The github.io homepage (index.md) and 404.md intentionally keep Jekyll
Liquid and theme HTML: they are never mounted on docs.docker.com.
Reflects changes from PR #3310: feat(server): accept title in POST /api/sessions to skip LLM title generation
Updates the sessions endpoint table to document the optional title field
accepted by POST /api/sessions, and adds an example showing that a
pre-supplied title is stored verbatim and skips LLM title generation.
POST /api/sessions/:id/fork now takes a 0-based ordinal counting only
user-role messages instead of an index into the flat all-roles list.
Clients only have to know which of the user's turns they clicked on;
the server translates that into the underlying item index.
This decouples the contract from the precise layout of tool responses
and assistant turns, which a streaming client cannot fully observe
until persistence completes.
- go-sdk: add note that omitting name: in a theme YAML falls back to
the filename stem as the picker display name
- dmr: clarify 'configured default' as the model: key in the agent YAML
- api-server: define sub-session in the fork validation bullet
Add a callout to the API Server page and an inline note to the CLI
reference describing CAGENT_PPROF_ADDR / --pprof-addr: a hidden flag
that starts a Go pprof HTTP server at /debug/pprof/ for heap/goroutine
profiling on long-running serve api deployments.
Signed-off-by: Arnaud Héritier <aheritier@users.noreply.github.com>
Add POST /api/sessions/:id/fork to the Sessions endpoint table and
document the Session Forking section: request body, message_index
semantics (exclusive cut), response shape, title numbering, and
validation errors (non-user message, out-of-range, sub-session).
Signed-off-by: Arnaud Héritier <aheritier@users.noreply.github.com>
The attached control plane (docker agent run --listen) and the new
session endpoints were undocumented. Document them on the API Server
page:
- Driving a running TUI with --listen (TCP or unix:// socket) and run
discovery via the run registry.
- The session event stream (/events): per-event sequence ids, resuming
with Last-Event-ID / ?since=, the gap signal, and the terminal
session_exited event.
- Snapshot-then-tail (/snapshot + last_event_seq) for gapless resync.
- Session-scoped readiness via /status?wait=.
- Idempotent follow-ups via the Idempotency-Key header.
Add /status, /snapshot and /events to the sessions table, and add a
--listen row to the run flags in the CLI reference pointing here.
Replace the dedicated PATCH/POST /api/sessions/:id/model endpoints with a model field on the runAgent request. The override is applied before user messages are persisted, preventing orphaned messages on validation failure. RemoteRuntime queues overrides internally and forwards them on the next turn.
- Remove SetSessionModelRequest/Response types
- Add RunAgentRequest with messages and optional model field
- Update Client.RunAgent() to accept model parameter
- Remove Client.SetAgentModel()
- Update RemoteRuntime to queue pending overrides
- Fold model logic into SessionManager.RunSession()
- Remove dedicated /model endpoints and handler
- Update API documentation and tests
Add GET/PATCH/POST /api/sessions/:id/model(s) to the endpoint table.
POST is accepted for backward compatibility with RemoteRuntime's
historical SetAgentModel implementation.
Assisted-By: docker-agent
Bring the docs site in line with Docker's official design system and
rewrite the homepage so first-time visitors can answer "what is this
and why should I care?" in under 30 seconds.
No application/runtime code is touched — every change is in `docs/`.
## Branding
* **Fonts** — switch from Inter / JetBrains Mono to **Roboto Flex**
(the variable-axis sans docs.docker.com self-hosts) and **Roboto
Mono**. Both pulled from Google Fonts.
* **Color tokens** — introduce a structured palette of named tokens
derived from the official brand kit (Docker-Logos-1.zip):
--blue-100..700 anchored on Ocean Blue `#2560FF`
--navy-900..600 anchored on Deep Blue `#00153C`
--gray-100..900 lifted verbatim from docs.docker.com (#E7EAEF,
#C8CFDA, …, #1E2129) so chrome feels like the same family.
* **Dark theme** matches docs.docker.com: neutral charcoal page bg
`#10151B`, sidebar/cards `#1E2129`, body text `#C8CFDA`, headings
white, links `#4B83F1`. Brand navy is reserved for the hero, the
primary button and the info-callout dark backgrounds.
* **Light theme** also calibrated to docs.docker.com: page+sidebar+
main on the same `#E7EAEF` (gray-100) surface (matches their
footer / navbar-active), cards on white, headings `#1F242D`,
body copy `#3F4750` (their `oklch(37.3% .034 259.733)`).
* **Moby mark** — the hand-authored whale SVG didn't match Docker's
official asset (it was missing the eight containers stacked on the
whale's back). Ship the actual `docker-mark-ocean-blue.svg` from
the brand kit instead, plus a white variant for dark backgrounds.
* **Callouts** — redesigned in docs.docker.com style: rounded panel
with a filled circular icon badge in the top-left and a strong
title row. `info`, `tip` and `warning` now match the same exact
background colors docs.docker.com uses in dark mode (`#00153C`,
`#11371A`, `#643700`).
* **Header** — Docker Agent wordmark + Moby mark, left-aligned at the
page padding edge so it doesn't drift on wide monitors.
* **Sidebar** — value tagline at the top ("Run AI agents like
containers."), nav links at 16px / weight 400 (was 13.2px), pure
white sidebar text on dark mode for higher contrast.
* **Right-column TOC** — restyled like docs.docker.com:
"Edit this page" link with pencil icon at the top, pointing at
GitHub's web editor (resolved at build time via `<meta
name="docs-edit-url">` and `{{ page.path }}`).
"Table of contents" heading at `1.05rem` weight 500 (was a tiny
uppercase eyebrow).
Links at `.875rem`, gray-600 / gray-100, with a 2px gray-300
left-border + weight 500 on the active entry.
* **Ecosystem footer** — three-column footer with links to Docker
Desktop, Hub, Scout, Build Cloud, docs.docker.com, the agent
catalog on Hub, the Docker blog, status, terms and privacy.
* **Page chrome** — light-theme code blocks honor the theme (warm
`#F6F8FA` + matching syntax palette); footer is moved out of
`<main>` so it isn't part of the ARIA `main` landmark; skip-link
target gets `scroll-margin-top` so keyboard users land below the
header.
## Messaging
* **Hero** leads with the docker-run analogy:
> **Docker Agent is to AI agents what `docker run` is to containers.**
> Define an agent in a YAML file, run it with one command, share it
> through any OCI registry — the same workflow you already use for
> images.
* **Demo GIF** moved above the fold so the TUI is visible without
scrolling.
* **30-second elevator panel** — four cards under the hero:
what it is / what it isn't / who it's for / what you get.
* **Without / With Docker Agent** code comparison: ~30 lines of
Python+Anthropic glue versus 8 lines of YAML + `docker agent run`.
* **"Why" rows** — abstract copy replaced with concrete pain → fix
pairs ("I rebuilt the same agent loop in three projects" →
"Reusable YAML, declare once, run everywhere").
* **Use cases** — a 4-card row showing the typical shapes (coding /
ops / data / custom workflows), each linking to the most relevant
follow-up page.
* **How it works** — adds an SVG flow diagram
(`agent.yaml → docker agent run → [Model ↔ Tools ↔ Sub-agents] →
stream`) using `currentColor` so it reads in both themes.
* **Glossary box** explaining Agent / Tool / MCP / A2A / TUI / OCI
inline so first-time readers don't bounce on the jargon.
* **Ecosystem tiles** — cross-links to Docker Hub (agent catalog),
Docker Desktop, Docker Model Runner and Docker Scout, anchoring
Docker Agent in the broader product family.
* **Icon set** — emoji feature/usecase/card icons replaced with
Lucide-style line icons in tinted Docker-Blue squares.
* **STYLE.md** — added to codify "Docker Agent" (prose) vs
`docker agent` (CLI) naming, voice, code samples and a small
glossary so subsequent contributors don't have to guess. The
introduction and quickstart pages are reconciled to the new
convention.
* **Bulk callout edit** — every `<div class="callout-title">` across
56 content pages had its leading `ℹ️ / 💡 / ⚠️` emoji stripped,
because the new icon-badge callout already provides one.
## Meta
* `<title>` and meta description tightened for SEO: home page now
reads "Docker Agent — Run AI agents from YAML, like containers"
and the description fits Google's ~155-char snippet budget.
`og:site_name` and Twitter card metadata added for nicer link
previews.
- Bump example Anthropic model from claude-sonnet-4-0 to claude-sonnet-4-5
(the recommended default per docs/providers/anthropic/index.md) across
guides, configuration, tools, features, and the home page.
- Replace the broken modelname.ai link in the OpenAI provider page with
the correct modelnames.ai and the official OpenAI models doc.
- Update the Bedrock IAM-role example from the long-deprecated
anthropic.claude-3-sonnet-20240229-v1:0 model to the current
global.anthropic.claude-sonnet-4-5-20250929-v1:0 used elsewhere on
the page.
- Add a dedicated docs/features/chat/ page for 'docker agent serve chat'
(the OpenAI-compatible chat-completions server), wire it into the
navigation, and cross-link it from the CLI reference and API server
pages.
Assisted-By: docker-agent
Audit of every claim in https://github.com/docker/cagent/issues/2464 against
the source code, followed by targeted fixes. All 35 real issues plus one
broken cross-reference discovered during review are addressed here.
Schema / overview
- Bump the config schema version to 8 in docs/configuration/overview and
agent-schema.json (enum, examples, description) to match
pkg/config/latest/parse.go (currentVersion = 8).
- Document the top-level `mcps:` section for reusable MCP server
definitions (pkg/config/latest/types.go, Config.MCPs).
- Remove the non-existent `rag:` agent-level property from the agent
reference — RAG is now attached via `toolsets:`.
- Document `skills` accepting either a boolean or a list of sources
(SkillsConfig supports "local" plus HTTP/HTTPS URLs).
- Show `ask:` in the main permissions YAML example.
Providers
- Fix Nebius base URL (.com, not .ai) to match pkg/model/provider/provider.go.
- Fix the provider auto-detection priority order in guides/tips
(Anthropic → OpenAI → Google → Mistral → Amazon Bedrock → DMR per
pkg/config/auto.go).
- Add the missing built-in aliases (requesty, azure, ollama,
github-copilot) to the providers overview and concepts/models tables.
- Document `GEMINI_API_KEY` and the Vertex AI env vars for Google.
- List `claude-opus-4-7` and `claude-haiku-4-5` in the Anthropic
models table.
- Add the `apac.` inference profile prefix to the Bedrock doc.
- Remove the false "medium thinking by default" claim from Mistral —
default thinking is only applied to OpenAI o-series models.
- Add `xhigh`, `max`, and `adaptive/<level>` to the thinking-effort
lists in OpenAI, xAI, and configuration/models.
CLI and features
- Align Docker Desktop minimum version to 4.63+ in the installation doc.
- Document the `docker agent models` command and the missing `docker
agent run` flags (--lean, --sandbox, --template, --sbx, --json,
--session-db, --attach, --dry-run, --hide-tool-calls,
--hide-tool-results).
- Document `serve mcp` `--http` and `--listen` flags.
- Document `serve a2a` and `serve acp` runtime flags (--working-dir,
--env-from-file, --models-gateway, --code-mode-tools, --hook-*,
--agent, --listen, --session-db).
- Describe the real sandbox backend (docker sandbox / sbx CLI) and add
--template / --sbx flags.
- Fix the default `--judge-model` string to
`anthropic/claude-opus-4-5-20251101` per cmd/root/eval.go.
- Document the `/api/sessions/:id/steer`, `/followup`, and
`/api/agents/:id/:agent_name/tools/count` endpoints.
- Document the OAuth config block for remote MCP servers that don't
support Dynamic Client Registration.
- Expand the secrets priority chain with the credential helper and
Docker Desktop providers (pkg/environment/default.go).
TUI
- Remove the non-existent Ctrl+L audio keybinding.
- Add the missing slash commands: /clear, /copy-last, /fork,
/permissions, /tools, /split-diff, /speak (plus /quit and /q aliases).
- Add tab/multi-agent and yolo/sidebar keybindings
(Ctrl+T/W/N/P, Ctrl+1–9, Ctrl+S, Ctrl+B, Ctrl+Y, Ctrl+O, Ctrl+G).
Tools
- Rewrite the `handoff` tool reference: it is local peer-to-peer,
auto-enabled by `handoffs:`, not an A2A remote toolset with
url/timeout fields.
- Document the `fetch` tool as GET-only with `urls`, `format`, and
per-call `timeout` parameters, and a 1 MB / robots.txt note.
- Add `create_directory` and `remove_directory` to the filesystem
tools table.
- Document the shell toolset's background-job tools
(`run_background_job`, `list_background_jobs`, `view_background_job`,
`stop_background_job`) plus `cwd`/`timeout` parameters.
- Document parameters for `background_agents` (agent/task/
expected_output/task_id), `transfer_task` (agent/task/
expected_output), and `user_prompt` (title).
- Mark `name` as optional and document `headers` on the `a2a` toolset.
- Add `rag`, `openapi`, `tasks`, and `model_picker` to the
configuration/tools and concepts/tools tables.
- Add the missing `/tools/tasks/` and `/tools/model-picker/` reference
pages (cross-referenced from the tables above).
Go SDK
- Fix the `builtin.NewShellTool` example to use the actual 2-argument
signature from pkg/tools/builtin/shell.go.
Assisted-By: docker-agent
Add markdown="1" attribute to all callout div elements so that
kramdown processes markdown syntax (bold, italic, links) inside
HTML blocks. Without this attribute, content like **bold** and
*italic* was rendered as plain text on the documentation website.
Fixes#2282
Assisted-By: docker-agent
Document that :agent is the config filename without the .yaml extension and
:name is the optional sub-agent name (defaults to root). Add concrete
examples for single-agent and multi-agent configurations.
Fixes#2074
Assisted-By: docker-agent
Thinking is now solely driven by the model's thinking_budget config.
If a model has thinking_budget set or requires thinking (e.g. o-series),
it uses thinking. There is no longer a per-session toggle.
Removed:
- /think slash command from TUI
- Session.Thinking field and WithThinking option
- options.WithThinking model option and applyOverrides
- Thinking toggle from sidebar, server API, session state
- ThinkingConfigured from agent and teamloader
- All related handlers, messages, and tests
Assisted-By: docker-agent
David Gageot
Arnaud Héritier
Arnaud Héritier
Sayt-0
Arnaud Héritier
Trung Nguyen
docker-agent
David Gageot
Guillaume Tardif