From dc8408912464296d09c42763a7021f0776d94711 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 04:03:56 +0000 Subject: [PATCH 1/7] docs: document remote MCP idle reconnection behaviour (source: #3064) --- docs/configuration/tools/index.md | 2 +- docs/features/remote-mcp/index.md | 6 ++++++ docs/tools/mcp/index.md | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/configuration/tools/index.md b/docs/configuration/tools/index.md index d05ce7b03..1429371fc 100644 --- a/docs/configuration/tools/index.md +++ b/docs/configuration/tools/index.md @@ -262,7 +262,7 @@ toolsets: | Property | Type | Description | | --- | --- | --- | | `profile` | string | One of `resilient` (default), `strict`, `best-effort`. Picks defaults for every other field. | -| `restart` | string | When the supervisor should reconnect after a disconnect: `never`, `on_failure` (default), or `always`. | +| `restart` | string | When the supervisor should reconnect after a disconnect: `never`, `on_failure` (default), or `always`. For **remote** MCP toolsets (Streamable HTTP / SSE), `on_failure` is automatically promoted to `always` so idle-timeout closes reconnect gracefully — `never` is still honored. | | `max_restarts` | int | Maximum consecutive restart attempts before the toolset is marked `Failed`. `0` uses the profile default (5); `-1` means unlimited. | | `backoff.initial` | duration | First wait between attempts (Go duration: `500ms`, `1s`, …). Default: `1s`. | | `backoff.max` | duration | Cap on the wait between attempts. Default: `32s`. | diff --git a/docs/features/remote-mcp/index.md b/docs/features/remote-mcp/index.md index 0b575196c..693511cb1 100644 --- a/docs/features/remote-mcp/index.md +++ b/docs/features/remote-mcp/index.md @@ -52,6 +52,12 @@ For full configuration details, see the [Tool Config]({{ '/configuration/tools/' Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk. +
+
Automatic reconnection after idle timeouts +
+

Remote MCP connections (Streamable HTTP / SSE) automatically reconnect after the server closes an idle connection — no configuration needed. Services like Notion and Linear close idle connections periodically; docker-agent detects the clean close and reconnects with exponential backoff. To tune reconnect behaviour or disable reconnection entirely, use the lifecycle block.

+
+ ### OAuth for servers without Dynamic Client Registration Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)]({{ 'https://datatracker.ietf.org/doc/html/rfc7591' }}) — no configuration is needed, docker-agent handles the flow for you. diff --git a/docs/tools/mcp/index.md b/docs/tools/mcp/index.md index 311768294..50a1fc5fc 100644 --- a/docs/tools/mcp/index.md +++ b/docs/tools/mcp/index.md @@ -217,7 +217,7 @@ See [Per-Toolset Model Routing]({{ '/configuration/tools/#per-toolset-model-rout ### Lifecycle (auto-restart, profiles) -Local stdio and remote MCP servers are supervised: crashed servers reconnect automatically with exponential backoff. Tune the policy with the `lifecycle` block: +Local stdio and remote MCP servers are supervised: crashed servers reconnect automatically with exponential backoff. **Remote** MCP servers (Streamable HTTP / SSE) also reconnect after idle/clean connection closes — services like Notion and Linear periodically close idle connections, and docker-agent reconnects transparently. Tune the policy with the `lifecycle` block: ```yaml toolsets: From 774ebef8bff2c294624e6b8a072981230d482933 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 04:04:17 +0000 Subject: [PATCH 2/7] docs: document Shift+Tab runtime thinking level cycling (source: #3067) --- docs/guides/thinking/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/guides/thinking/index.md b/docs/guides/thinking/index.md index 14f3b13cf..be6e5f68c 100644 --- a/docs/guides/thinking/index.md +++ b/docs/guides/thinking/index.md @@ -304,6 +304,15 @@ models: | Research, difficult math/logic | `xhigh` / `max` | | Long agentic tasks (Anthropic) | `adaptive` | +## Changing Thinking Level at Runtime + +While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config: + +- The level steps through the model's supported range (provider-specific), wrapping around — for example `off → minimal → low → medium → high → xhigh → off` on OpenAI. +- The current level is shown in the sidebar next to the model name (e.g. `openai/gpt-5 • high`). +- This applies as a session override — it is **not** saved to the config file. The next session starts from the level defined in your YAML. +- For models that don't support reasoning, and for remote runtimes, Shift+Tab is a no-op and an informational message is displayed. + ## Sharing Thinking Config Across Models Define a provider with a default `thinking_budget` and all models that reference it inherit it: From ec033c770344fccbc4706db0844623822e6c1541 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 04:04:33 +0000 Subject: [PATCH 3/7] docs: document localhost HTTP URL support for local agent dev (source: #3075) --- docs/concepts/distribution/index.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/concepts/distribution/index.md b/docs/concepts/distribution/index.md index 2db2a8db6..15d7f104c 100644 --- a/docs/concepts/distribution/index.md +++ b/docs/concepts/distribution/index.md @@ -125,3 +125,18 @@ $ docker agent run docker.io/myorg/private-agent:latest

Having issues with push/pull? See Troubleshooting for common registry issues.

+ +## Local Development + +For local development and testing, you can run an agent directly from a local HTTP server without a registry: + +```bash +# Serve an agent config locally +$ python3 -m http.server 8080 + +# Run it directly via HTTP +$ docker agent run http://localhost:8080/agent.yaml +$ docker agent run http://127.0.0.1:8080/agent.yaml +``` + +This is useful for iterating on agent configs served from a local dev server before pushing to a registry. Both `localhost` and `127.0.0.1` addresses are supported with plain `http://` URLs. From 5ea48dcf1a884b43cbc72e65134958531a68a302 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 04:04:48 +0000 Subject: [PATCH 4/7] docs: document automatic Docker Desktop JWT for .docker.com registries (source: #3077) --- docs/concepts/distribution/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/concepts/distribution/index.md b/docs/concepts/distribution/index.md index 15d7f104c..c492f599b 100644 --- a/docs/concepts/distribution/index.md +++ b/docs/concepts/distribution/index.md @@ -119,6 +119,12 @@ $ docker agent share push ./agent.yaml docker.io/myorg/private-agent:latest $ docker agent run docker.io/myorg/private-agent:latest ``` +
+
Docker Desktop credentials +
+

When pulling or running an agent from a .docker.com URL (e.g. hub.docker.com, registry-1.docker.com), docker-agent automatically forwards your Docker Desktop JWT for authentication — no docker login required as long as Docker Desktop is running and signed in.

+
+
Troubleshooting
From b145daebc5a895d926a27178cea5d817e604f90a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 04:05:22 +0000 Subject: [PATCH 5/7] docs: add pkg/tui/components/transcript to Go SDK core packages (source: #3081) --- docs/guides/go-sdk/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md index 9ae6ac8c8..a1c57eda2 100644 --- a/docs/guides/go-sdk/index.md +++ b/docs/guides/go-sdk/index.md @@ -34,6 +34,7 @@ docker-agent can be used as a Go library, allowing you to build AI agents direct | `pkg/tui/components/toolconfirm` | Tool-confirmation policy: `Decision` enum, `BuildPermissionPattern`, key bindings, and rejection-reason presets. Share this instead of copying the permission-pattern logic. | | `pkg/tui/service` | `StaticSessionState` — a `SessionStateReader` with conservative fixed values, for rendering message/tool views outside the full TUI app. Replaces hand-rolled nine-method stubs. | | `pkg/tui/animation` | `Stopper` / `StopView` — animation lifecycle contract. Call `StopAnimation` on views removed from the UI to prevent leaked tick subscriptions. | +| `pkg/tui/components/transcript` | Embedded transcript view with read-only `Messages()` accessor for observing conversation structure in host tests and persistence layers. | ## Embedding TUI Components @@ -42,6 +43,7 @@ When building custom UIs on top of docker-agent's TUI primitives, three packages - **`pkg/tui/components/toolconfirm`** — import this package for the permission-decision policy rather than copying the pattern-building logic. The `Decision` enum, `BuildPermissionPattern` helper, and rejection-reason presets are the canonical source of truth: whatever pattern is shown to the user in the confirmation dialog is exactly the pattern granted to the runtime. - **`pkg/tui/service`** — use `StaticSessionState` as a stub `SessionStateReader` when rendering individual message or tool views outside the full TUI app. It returns conservative fixed values for all nine interface methods, eliminating the need for hand-rolled stubs. - **`pkg/tui/animation`** — implement `animation.Stopper` on any view that owns a tick-based animation. Call `StopAnimation` whenever a view is removed from the UI hierarchy to prevent leaked `time.Tick` subscriptions from firing against a dead view. +- **`pkg/tui/components/transcript`** — embed the transcript view for displaying conversation history. Use the `Messages()` method to read the current slice of transcript messages (treat as read-only — mutations desync renders). This is useful for host-side tests asserting on chat history, and for persistence layers that need to snapshot conversation state. ## Basic Example From 742064f6bbde88681607b166563f3d77d1a22b00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 07:44:31 +0000 Subject: [PATCH 6/7] =?UTF-8?q?docs:=20fix=20'off'=20=E2=86=92=20'none'=20?= =?UTF-8?q?in=20OpenAI=20thinking=20cycle=20example;=20'three'=20=E2=86=92?= =?UTF-8?q?=20'four'=20packages=20(PR=20#3084=20review)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/guides/go-sdk/index.md | 2 +- docs/guides/thinking/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md index a1c57eda2..2e8f8a93e 100644 --- a/docs/guides/go-sdk/index.md +++ b/docs/guides/go-sdk/index.md @@ -38,7 +38,7 @@ docker-agent can be used as a Go library, allowing you to build AI agents direct ## Embedding TUI Components -When building custom UIs on top of docker-agent's TUI primitives, three packages define the contracts that keep the runtime and the UI in sync: +When building custom UIs on top of docker-agent's TUI primitives, four packages define the contracts that keep the runtime and the UI in sync: - **`pkg/tui/components/toolconfirm`** — import this package for the permission-decision policy rather than copying the pattern-building logic. The `Decision` enum, `BuildPermissionPattern` helper, and rejection-reason presets are the canonical source of truth: whatever pattern is shown to the user in the confirmation dialog is exactly the pattern granted to the runtime. - **`pkg/tui/service`** — use `StaticSessionState` as a stub `SessionStateReader` when rendering individual message or tool views outside the full TUI app. It returns conservative fixed values for all nine interface methods, eliminating the need for hand-rolled stubs. diff --git a/docs/guides/thinking/index.md b/docs/guides/thinking/index.md index be6e5f68c..19239fbb4 100644 --- a/docs/guides/thinking/index.md +++ b/docs/guides/thinking/index.md @@ -308,7 +308,7 @@ models: While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config: -- The level steps through the model's supported range (provider-specific), wrapping around — for example `off → minimal → low → medium → high → xhigh → off` on OpenAI. +- The level steps through the model's supported range (provider-specific), wrapping around — for example `none → minimal → low → medium → high → xhigh → none` on OpenAI. - The current level is shown in the sidebar next to the model name (e.g. `openai/gpt-5 • high`). - This applies as a session override — it is **not** saved to the config file. The next session starts from the level defined in your YAML. - For models that don't support reasoning, and for remote runtimes, Shift+Tab is a no-op and an informational message is displayed. From 06889693ae269c228377b32e72d83825942b290e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Fri, 12 Jun 2026 07:44:51 +0000 Subject: [PATCH 7/7] docs: correct Docker Desktop JWT scope to docker.com/.docker.com, not docker.io (PR #3084 review) --- docs/concepts/distribution/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/concepts/distribution/index.md b/docs/concepts/distribution/index.md index c492f599b..9ad2fc1f0 100644 --- a/docs/concepts/distribution/index.md +++ b/docs/concepts/distribution/index.md @@ -122,7 +122,8 @@ $ docker agent run docker.io/myorg/private-agent:latest
Docker Desktop credentials
-

When pulling or running an agent from a .docker.com URL (e.g. hub.docker.com, registry-1.docker.com), docker-agent automatically forwards your Docker Desktop JWT for authentication — no docker login required as long as Docker Desktop is running and signed in.

+

When pulling or running an agent from a docker.com or *.docker.com HTTPS URL (e.g. desktop.docker.com), docker-agent automatically forwards your Docker Desktop JWT for authentication — no explicit login required when Docker Desktop is running and signed in.

+

Note: docker.io (the standard Docker Hub registry domain) is a separate domain and is not covered by automatic JWT forwarding. Agents pulled from docker.io or registry-1.docker.io still require docker login docker.io for private repositories.