Skip to content

Commit bd2cb8f

Browse files
dgageotdgageot
committed
docs: fix outdated content and document missing commands
Spotted while auditing the published documentation against the source. Wrong / outdated information: - Fix the Azure provider env var: the `azure` alias defaults to `AZURE_API_KEY` (see pkg/model/provider/aliases.go), not `AZURE_OPENAI_API_KEY`. Updated the providers overview, models concept page, and troubleshooting cheat sheet. - Fix the GitHub Copilot env var: the alias reads `GITHUB_TOKEN` (a PAT with the `copilot` scope), not `gh auth login`-managed creds. - Fix a broken internal link in providers/openai (`/examples/ websocket_transport/` does not exist as a docs page) — point at the YAML on GitHub instead. - Fix a stray extra column delimiter in the Log Analysis table and a missing word in the Port conflicts section of the troubleshooting page. Missing content: - Add Tasks and Model Picker tools to the navigation; both pages already exist under /tools/ but were not linked from the sidebar. - Document `docker agent serve chat` (OpenAI-compatible Chat Completions server) — the command exists but had no public docs. - Document `docker agent version`. - Document the missing `docker agent run` flags surfaced by cmd/root/run.go and cmd/root/flags.go: `--remote`, `--working-dir`, `--env-from-file`, `--code-mode-tools`, `--models-gateway`, `--fake`, `--record`. - Document the global `--cache-dir`, `--config-dir`, `--data-dir` flags from cmd/root/root.go. - Round out the API-key cheat sheet in the troubleshooting page with Nebius, MiniMax, Requesty, GitHub Copilot, and Azure entries (and note that `GOOGLE_API_KEY` and `GEMINI_API_KEY` are both honored). Assisted-By: docker-agent Signed-off-by: David Gageot <david@gageot.net>
1 parent 1737035 commit bd2cb8f

6 files changed

Lines changed: 87 additions & 22 deletions

File tree

‎docs/_data/nav.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@
5353
url: /tools/todo/
5454
- title: Memory
5555
url: /tools/memory/
56+
- title: Tasks
57+
url: /tools/tasks/
5658
- title: Fetch
5759
url: /tools/fetch/
5860
- title: Script
@@ -69,6 +71,8 @@
6971
url: /tools/background-agents/
7072
- title: Handoff
7173
url: /tools/handoff/
74+
- title: Model Picker
75+
url: /tools/model-picker/
7276
- title: OpenAPI
7377
url: /tools/openapi/
7478
- title: A2A

‎docs/community/troubleshooting/index.md‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,14 @@ Each model provider requires its own API key as an environment variable:
7979
| ------------- | --------------------------------------------------- |
8080
| OpenAI | `OPENAI_API_KEY` |
8181
| Anthropic | `ANTHROPIC_API_KEY` |
82-
| Google Gemini | `GOOGLE_API_KEY` |
82+
| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
8383
| Mistral | `MISTRAL_API_KEY` |
8484
| xAI | `XAI_API_KEY` |
85+
| Nebius | `NEBIUS_API_KEY` |
86+
| MiniMax | `MINIMAX_API_KEY` |
87+
| Requesty | `REQUESTY_API_KEY` |
88+
| GitHub Copilot | `GITHUB_TOKEN` (PAT with `copilot` scope) |
89+
| Azure OpenAI | `AZURE_API_KEY` (override with `token_key`) |
8590
| AWS Bedrock | `AWS_BEARER_TOKEN_BEDROCK` or AWS credentials chain |
8691

8792
```bash
@@ -165,7 +170,7 @@ docker-agent validates config at startup and reports errors with line numbers. C
165170

166171
### Port conflicts
167172

168-
When docker-agent as an API server or MCP server, ensure the port is not already in use:
173+
When running docker-agent as an API server or MCP server, ensure the port is not already in use:
169174

170175
```bash
171176
# Check if port 8080 is in use
@@ -231,16 +236,16 @@ $ docker agent share pull docker.io/username/agent:latest
231236

232237
When reviewing debug logs, search for these key patterns:
233238

234-
| Log Pattern | What It Indicates |
235-
| --------------------------- | ------------------------------------------------------------------------------ | ---------------- |
236-
| `"Starting runtime stream"` | Agent execution beginning |
237-
| `"Tool call"` | A tool is being executed |
238-
| `"Tool call result"` | Tool execution completed |
239-
| `"Stream stopped"` | Agent finished processing |
239+
| Log Pattern | What It Indicates |
240+
| --------------------------- | ------------------------------------------------------------------------------------------------ |
241+
| `"Starting runtime stream"` | Agent execution beginning |
242+
| `"Tool call"` | A tool is being executed |
243+
| `"Tool call result"` | Tool execution completed |
244+
| `"Stream stopped"` | Agent finished processing |
240245
| `HTTP 429` | Rate limiting — consider adding a [fallback model]({{ '/configuration/agents/' | relative_url }}) |
241-
| `context canceled` | Operation was interrupted (timeout or user cancel) |
242-
| `[RAG Manager]` | RAG retrieval operations |
243-
| `[Reranker]` | Reranking operations |
246+
| `context canceled` | Operation was interrupted (timeout or user cancel) |
247+
| `[RAG Manager]` | RAG retrieval operations |
248+
| `[Reranker]` | Reranking operations |
244249

245250
<div class="callout callout-warning" markdown="1">
246251
<div class="callout-title">⚠️ Still stuck?

‎docs/concepts/models/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ Named models let you configure temperature, token limits, thinking budgets, and
5757
| Nebius | `nebius` | Open-source and specialised models | `NEBIUS_API_KEY` |
5858
| MiniMax | `minimax` | MiniMax models | `MINIMAX_API_KEY` |
5959
| Requesty | `requesty` | Multi-provider gateway | `REQUESTY_API_KEY` |
60-
| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_OPENAI_API_KEY` + `base_url` |
60+
| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_API_KEY` + `base_url` |
6161
| Ollama | `ollama` | Any local Ollama model | None (local; optional `base_url`) |
62-
| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | GitHub CLI auth (`gh auth login`) |
62+
| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) |
6363

6464
See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section for detailed configuration guides.
6565

‎docs/features/cli/index.md‎

Lines changed: 62 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,18 +35,25 @@ $ docker agent run [config] [message...] [flags]
3535
| `--prompt-file <path>` | Include file contents as additional system context (repeatable) |
3636
| `--attach <path>` | Attach an image file to the initial message |
3737
| `--dry-run` | Initialize the agent without executing anything (useful for validating a config) |
38+
| `--remote <addr>` | Use a remote runtime at the given address instead of running the agent locally |
3839
| `--lean` | Use a simplified TUI with minimal chrome |
3940
| `--json` | Output results as newline-delimited JSON (use with `--exec`) |
4041
| `--hide-tool-calls` | Hide tool calls in the output |
4142
| `--hide-tool-results` | Hide tool call results in the output |
4243
| `--sandbox` | Run the agent inside a Docker sandbox (see [Sandbox]({{ '/configuration/sandbox/' | relative_url }})) |
4344
| `--template <image>` | Template image for the sandbox (default: `docker/sandbox-templates:docker-agent`) |
4445
| `--sbx` | Prefer the `sbx` CLI backend when available (default `true`; set `--sbx=false` to force `docker sandbox`) |
46+
| `--working-dir <path>` | Set the working directory for the session (applies to tools and relative paths) |
47+
| `--env-from-file <path>` | Load environment variables from file (repeatable) |
48+
| `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally) |
49+
| `--models-gateway <addr>` | Route model traffic through a gateway. Also reads `DOCKER_AGENT_MODELS_GATEWAY` env var. |
4550
| `--hook-pre-tool-use <cmd>` | Add a pre-tool-use hook command (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). |
4651
| `--hook-post-tool-use <cmd>` | Add a post-tool-use hook command (repeatable) |
4752
| `--hook-session-start <cmd>` | Add a session-start hook command (repeatable) |
4853
| `--hook-session-end <cmd>` | Add a session-end hook command (repeatable) |
4954
| `--hook-on-user-input <cmd>` | Add an on-user-input hook command (repeatable) |
55+
| `--fake <path>` | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. |
56+
| `--record [path]` | Record AI API interactions to a cassette file (auto-generates filename if no path given) |
5057
| `-d, --debug` | Enable debug logging |
5158
| `--log-file <path>` | Custom debug log location |
5259
| `-o, --otel` | Enable OpenTelemetry tracing |
@@ -176,6 +183,40 @@ $ docker agent serve acp agent.yaml
176183

177184
See [ACP]({{ '/features/acp/' | relative_url }}) for details on the Agent Client Protocol.
178185

186+
### `docker agent serve chat`
187+
188+
Start an HTTP server that exposes one or more agents through an **OpenAI-compatible Chat Completions API** at `/v1/chat/completions` and `/v1/models`. This lets any tool that already speaks the OpenAI protocol — for example [Open WebUI](https://github.com/open-webui/open-webui), `curl`, the OpenAI Python SDK, or LangChain — drive a docker-agent agent without any custom integration.
189+
190+
```bash
191+
$ docker agent serve chat [config] [flags]
192+
```
193+
194+
| Flag | Default | Description |
195+
| ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
196+
| `-a, --agent <name>` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate model. |
197+
| `-l, --listen <addr>` | `127.0.0.1:8083` | Address to listen on. |
198+
| `--cors-origin <origin>` | (none) | Allowed CORS origin (e.g. `https://example.com`). Empty disables CORS. |
199+
| `--api-key <token>` | (none) | Required Bearer token clients must present (`Authorization: Bearer <token>`). Empty disables auth. |
200+
| `--api-key-env <name>` | (none) | Read the API key from this environment variable instead of the command line. |
201+
| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size. |
202+
| `--request-timeout <dur>` | `5m` | Per-request timeout (covers model + tool calls + streaming). |
203+
| `--conversations-max <n>` | `0` | Cache up to N conversations server-side, keyed by `X-Conversation-Id`. `0` disables — clients must resend history. |
204+
| `--conversation-ttl <dur>` | `30m` | Idle TTL after which a cached conversation is evicted. |
205+
| `--max-idle-runtimes <n>` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. |
206+
207+
```bash
208+
# Examples
209+
$ docker agent serve chat agent.yaml
210+
$ docker agent serve chat ./team.yaml --agent reviewer
211+
$ docker agent serve chat agentcatalog/pirate --listen 127.0.0.1:9090
212+
$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN
213+
214+
# Drive it from any OpenAI-compatible client
215+
$ curl http://127.0.0.1:8083/v1/chat/completions \
216+
-H 'Content-Type: application/json' \
217+
-d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}'
218+
```
219+
179220
### `docker agent share push` / `docker agent share pull`
180221

181222
Share agents via OCI registries.
@@ -204,6 +245,16 @@ $ docker agent eval agent.yaml --only "auth*" # Only run matching eva
204245
$ docker agent eval agent.yaml --repeat 5 # Repeat each eval 5 times
205246
```
206247

248+
### `docker agent version`
249+
250+
Print the version and commit hash for your `docker-agent` install.
251+
252+
```bash
253+
$ docker agent version
254+
docker agent version v1.54.0
255+
Commit: 1737035c
256+
```
257+
207258
### `docker agent alias`
208259

209260
Manage agent aliases for quick access.
@@ -262,12 +313,17 @@ Run an alias with: docker agent run <alias>
262313

263314
## Global Flags
264315

265-
| Flag | Description |
266-
| ------------------------- | ------------------------------------------------------------ |
267-
| `-d, --debug` | Enable debug logging (default: `~/.cagent/cagent.debug.log`) |
268-
| `--log-file &lt;path&gt;` | Custom debug log location |
269-
| `-o, --otel` | Enable OpenTelemetry tracing |
270-
| `--help` | Show help for any command |
316+
These flags are available on every `docker agent` command:
317+
318+
| Flag | Description |
319+
| ------------------------- | -------------------------------------------------------------------------------------- |
320+
| `-d, --debug` | Enable debug logging (default location: `~/.cagent/cagent.debug.log`) |
321+
| `--log-file <path>` | Custom debug log location (only used with `--debug`) |
322+
| `-o, --otel` | Enable OpenTelemetry tracing |
323+
| `--cache-dir <path>` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) |
324+
| `--config-dir <path>` | Override the config directory (default: `~/.config/cagent`) |
325+
| `--data-dir <path>` | Override the data directory (default: `~/.cagent`) |
326+
| `--help` | Show help for any command |
271327

272328
## Agent References
273329

‎docs/providers/openai/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,4 +106,4 @@ models:
106106

107107
### Example
108108

109-
See [`examples/websocket_transport.yaml`]({{ '/examples/websocket_transport/' | relative_url }}) for a complete example.
109+
See [`examples/websocket_transport.yaml`](https://github.com/docker/docker-agent/blob/main/examples/websocket_transport.yaml) for a complete example.

‎docs/providers/overview/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,9 +64,9 @@ docker-agent also includes built-in aliases for these providers:
6464
| Nebius | `nebius` | `NEBIUS_API_KEY` |
6565
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
6666
| Requesty | `requesty` | `REQUESTY_API_KEY` |
67-
| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` + `base_url` |
67+
| Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` |
6868
| Ollama | `ollama` | None (local; optional `base_url`) |
69-
| GitHub Copilot | `github-copilot` | GitHub CLI auth (`gh auth login`) |
69+
| GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` (PAT with `copilot` scope) |
7070

7171
```bash
7272
# Use built-in providers inline

0 commit comments

Comments
 (0)