Skip to content

docs: fix outdated content and document missing commands #2600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dgageot merged 1 commit into from
Apr 30, 2026
Merged

docs: fix outdated content and document missing commands #2600

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/_data/nav.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@
url: /tools/todo/
- title: Memory
url: /tools/memory/
- title: Tasks
url: /tools/tasks/
- title: Fetch
url: /tools/fetch/
- title: Script
Expand All @@ -69,6 +71,8 @@
url: /tools/background-agents/
- title: Handoff
url: /tools/handoff/
- title: Model Picker
url: /tools/model-picker/
- title: OpenAPI
url: /tools/openapi/
- title: A2A
Expand Down
27 changes: 16 additions & 11 deletions docs/community/troubleshooting/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,14 @@ Each model provider requires its own API key as an environment variable:
| ------------- | --------------------------------------------------- |
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GOOGLE_API_KEY` |
| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| xAI | `XAI_API_KEY` |
| Nebius | `NEBIUS_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| Requesty | `REQUESTY_API_KEY` |
| GitHub Copilot | `GITHUB_TOKEN` (PAT with `copilot` scope) |
| Azure OpenAI | `AZURE_API_KEY` (override with `token_key`) |
| AWS Bedrock | `AWS_BEARER_TOKEN_BEDROCK` or AWS credentials chain |

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

### Port conflicts

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

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

When reviewing debug logs, search for these key patterns:

| Log Pattern | What It Indicates |
| --------------------------- | ------------------------------------------------------------------------------ | ---------------- |
| `"Starting runtime stream"` | Agent execution beginning |
| `"Tool call"` | A tool is being executed |
| `"Tool call result"` | Tool execution completed |
| `"Stream stopped"` | Agent finished processing |
| Log Pattern | What It Indicates |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `"Starting runtime stream"` | Agent execution beginning |
| `"Tool call"` | A tool is being executed |
| `"Tool call result"` | Tool execution completed |
| `"Stream stopped"` | Agent finished processing |
| `HTTP 429` | Rate limiting — consider adding a [fallback model]({{ '/configuration/agents/' | relative_url }}) |
| `context canceled` | Operation was interrupted (timeout or user cancel) |
| `[RAG Manager]` | RAG retrieval operations |
| `[Reranker]` | Reranking operations |
| `context canceled` | Operation was interrupted (timeout or user cancel) |
| `[RAG Manager]` | RAG retrieval operations |
| `[Reranker]` | Reranking operations |

<div class="callout callout-warning" markdown="1">
<div class="callout-title">⚠️ Still stuck?
Expand Down
4 changes: 2 additions & 2 deletions docs/concepts/models/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@ Named models let you configure temperature, token limits, thinking budgets, and
| Nebius | `nebius` | Open-source and specialised models | `NEBIUS_API_KEY` |
| MiniMax | `minimax` | MiniMax models | `MINIMAX_API_KEY` |
| Requesty | `requesty` | Multi-provider gateway | `REQUESTY_API_KEY` |
| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_OPENAI_API_KEY` + `base_url` |
| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_API_KEY` + `base_url` |
| Ollama | `ollama` | Any local Ollama model | None (local; optional `base_url`) |
| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | GitHub CLI auth (`gh auth login`) |
| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) |

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

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

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

### `docker agent serve chat`

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.

```bash
$ docker agent serve chat [config] [flags]
```

| Flag | Default | Description |
| ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `-a, --agent <name>` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate model. |
| `-l, --listen <addr>` | `127.0.0.1:8083` | Address to listen on. |
| `--cors-origin <origin>` | (none) | Allowed CORS origin (e.g. `https://example.com`). Empty disables CORS. |
| `--api-key <token>` | (none) | Required Bearer token clients must present (`Authorization: Bearer <token>`). Empty disables auth. |
| `--api-key-env <name>` | (none) | Read the API key from this environment variable instead of the command line. |
| `--max-request-size <bytes>` | `1048576` (1 MiB) | Maximum request body size. |
| `--request-timeout <dur>` | `5m` | Per-request timeout (covers model + tool calls + streaming). |
| `--conversations-max <n>` | `0` | Cache up to N conversations server-side, keyed by `X-Conversation-Id`. `0` disables — clients must resend history. |
| `--conversation-ttl <dur>` | `30m` | Idle TTL after which a cached conversation is evicted. |
| `--max-idle-runtimes <n>` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. |

```bash
# Examples
$ docker agent serve chat agent.yaml
$ docker agent serve chat ./team.yaml --agent reviewer
$ docker agent serve chat agentcatalog/pirate --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"}]}'
```

### `docker agent share push` / `docker agent share pull`

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

### `docker agent version`

Print the version and commit hash for your `docker-agent` install.

```bash
$ docker agent version
docker agent version v1.54.0
Copy link
Copy Markdown

@docker-agent docker-agent Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Hardcoded version number in example will become stale

The docker agent version example uses a specific real version number (v1.54.0) and commit hash (1737035c). These will be outdated as soon as the next release ships, and users may be confused when their actual output differs from the docs.

Consider using placeholder values instead:

$ docker agent version
docker agent version vX.Y.Z
Commit: <commit-hash>

Commit: 1737035c
```

### `docker agent alias`

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

## Global Flags

| Flag | Description |
| ------------------------- | ------------------------------------------------------------ |
| `-d, --debug` | Enable debug logging (default: `~/.cagent/cagent.debug.log`) |
| `--log-file &lt;path&gt;` | Custom debug log location |
| `-o, --otel` | Enable OpenTelemetry tracing |
| `--help` | Show help for any command |
These flags are available on every `docker agent` command:

| Flag | Description |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `-d, --debug` | Enable debug logging (default location: `~/.cagent/cagent.debug.log`) |
| `--log-file <path>` | Custom debug log location (only used with `--debug`) |
| `-o, --otel` | Enable OpenTelemetry tracing |
| `--cache-dir <path>` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) |
| `--config-dir <path>` | Override the config directory (default: `~/.config/cagent`) |
| `--data-dir <path>` | Override the data directory (default: `~/.cagent`) |
| `--help` | Show help for any command |

## Agent References

Expand Down
2 changes: 1 addition & 1 deletion docs/providers/openai/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,4 +106,4 @@ models:

### Example

See [`examples/websocket_transport.yaml`]({{ '/examples/websocket_transport/' | relative_url }}) for a complete example.
See [`examples/websocket_transport.yaml`](https://github.com/docker/docker-agent/blob/main/examples/websocket_transport.yaml) for a complete example.
4 changes: 2 additions & 2 deletions docs/providers/overview/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,9 @@ docker-agent also includes built-in aliases for these providers:
| Nebius | `nebius` | `NEBIUS_API_KEY` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
| Requesty | `requesty` | `REQUESTY_API_KEY` |
| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` + `base_url` |
| Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` |
| Ollama | `ollama` | None (local; optional `base_url`) |
| GitHub Copilot | `github-copilot` | GitHub CLI auth (`gh auth login`) |
| GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` (PAT with `copilot` scope) |

```bash
# Use built-in providers inline
Expand Down
Loading