gordon: revise gordon docs for gordon v2 by dvdksn · Pull Request #24074 · docker/docs

dvdksn · 2026-02-04T12:12:08Z

https://deploy-preview-24074--docsdocker.netlify.app/ai/gordon/

netlify · 2026-02-04T12:12:14Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`88d0d59`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/698f393057492d0008551974
😎 Deploy Preview	https://deploy-preview-24074--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions

Documentation Review

This is a comprehensive revision for Gordon v2/GA. The documentation is well-structured and clear overall. I found a few issues in the newly added content that could improve clarity.

Summary

CONFIRMED: 1 medium-severity issue (undefined term)
LIKELY: 3 medium-severity issues (consistency, clarity)

All issues are in newly added content.

github-actions · 2026-02-09T17:23:21Z

content/manuals/ai/gordon/how-to/configure-tools.md

+
+![Advanced tool configuration](../images/gordon_advanced_tool_config.avif?w=500px&border=true)
+
+Gordon still requests approval before running allow-listed tools, unless YOLO


Undefined term

The phrase "YOLO mode" is used here without explanation. While it's defined later in permissions.md ("bypass permission checking altogether"), readers of this page may not understand what it means.

Consider:

Defining it on first use: "YOLO mode (auto-approve mode that bypasses permission checks)"

Linking to the permissions page where it's explained

Using the more descriptive "auto-approve mode" consistently

github-actions · 2026-02-09T17:23:22Z

content/manuals/ai/gordon/_index.md

- Data is anonymized and cannot be traced back to you or your account.
- Docker does not use this data to train AI models or share it with third
-  parties.
+   ![Gordon running in Docker Desktop](./images/gordon_gui.avif)


Inconsistent image formatting

This image reference lacks the ?border=true parameter that's used for the terminal screenshot at line 72. The permissions image at line 84 also lacks it.

For consistency, consider either:

Adding ?border=true to all screenshots

Removing it from all screenshots

Documenting when borders should/shouldn't be used

github-actions · 2026-02-09T17:23:22Z

content/manuals/ai/gordon/usage-and-limits.md

+| Business     | 6x               | Six times Personal tier usage        |
+
+> [!NOTE]
+> Limits are per user, not per organization for Team and Business


Potentially unclear tier distinction

The note mentions "Limits are per user, not per organization for Team and Business" but the table shows Pro and Team both have 3x multipliers. While the distinction is about scope (per-user vs per-organization) rather than the multiplier value, this could confuse readers.

Consider clarifying: "Team provides the same multiplier as Pro (3x), but limits apply per individual user rather than being shared across the organization."

github-actions · 2026-02-09T17:23:22Z

content/manuals/ai/gordon/how-to/permissions.md

+
+Command execution:
+Commands run with your user permissions. Gordon has no elevated privileges
+unless you explicitly grant them. Avoid granting `sudo` access without careful


Vague security guidance

The warning "Avoid granting sudo access without careful review" doesn't specify what constitutes careful review. While the "Verify before approving" checklist below provides general guidance, it doesn't specifically address sudo concerns.

Consider making this more actionable: "Avoid granting sudo access. If necessary, verify the command is essential, understand its full scope, and confirm there's no alternative without elevated privileges."

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

dvdksn · 2026-02-13T14:47:55Z

content/manuals/ai/gordon/_index.md

+title: Gordon
+description: AI agent for Docker workflows - execute tasks, debug issues, and
+  manage containers with intelligent assistance
+weight: 1


trungutt · 2026-02-13T14:54:13Z

content/manuals/ai/gordon/concepts/capabilities.md

+- **Root**: Coordinator that interprets requests and routes to the right agent
+- **Coding agent**: General-purpose agent that handles software development,
+  Docker operations, containerization, and Dockerfile optimization


note: This isn't the case anymore. We only have one main agent. The coding agent doesn't exist any longer. We still have DHI migration agent.

This is the definition of Gordon agent currently https://github.com/docker/gordon/blob/main/gordon.yaml.
We should modify this section accordingly.

Thank you, will get this updated.

trungutt · 2026-02-13T14:56:00Z

content/manuals/ai/gordon/concepts/capabilities.md

+Commands run with your user permissions. Gordon cannot access `sudo` unless
+you've explicitly granted it.
+
+## Filesystem access


note: It'll be interesting to connect with @stanislavHamara to know more about how Gordon handles granular permissions in Gordon. Gordon can allow users to revoke permissions previously granted etc

trungutt · 2026-02-13T14:58:07Z

content/manuals/ai/gordon/concepts/data-privacy.md

+### Personal (free) subscription
+
+Conversation threads are stored to improve the service. Individual queries and
+responses are retained as part of your conversation history.


note: We should mention specific duration of storage.

trungutt · 2026-02-13T14:59:08Z

content/manuals/ai/gordon/concepts/data-privacy.md

+
+- Enable or disable Gordon for the organization
+- Set usage limits by subscription tier
+- Configure tool access and permissions


note: I don't think we can "Configure tool access and permissions". Previous two possibilities are valid though.

trungutt · 2026-02-13T14:59:36Z

content/manuals/ai/gordon/concepts/data-privacy.md

+Individual users:
+
+1. Open Docker Desktop Settings.
+2. Navigate to the **Beta features** section.


note: Does it need to be moved to AI section? @derekmisler

when it's officially GA we'll move it there, but we opted to keep it under Beta for now.

good catch

trungutt · 2026-02-13T15:00:20Z

content/manuals/ai/gordon/how-to/configure-tools.md

+- Enabled tools: Gordon can propose actions using these tools (subject to
+  your approval)
+- Disabled tools: Gordon cannot use these tools, and will not request
+  permission to use them


note: We should talk about permission with @stanislavHamara

trungutt · 2026-02-13T15:01:07Z

content/manuals/ai/gordon/how-to/docker-desktop.md

+1. Open Docker Desktop.
+2. Select **Ask Gordon** in the sidebar.
+3. Type your question or request in the input field.
+4. Press <kbd>Enter</kbd> or select the send button.


note: We should mention login is required to use Gordon.

github-actions bot added the area/ai label Feb 4, 2026

dvdksn added the status/do-not-merge Pull requests that are awaiting some event or decision before they can be merged. label Feb 4, 2026

dvdksn force-pushed the gordon-ga branch from c49cc23 to a353604 Compare February 4, 2026 12:14

github-actions bot added the area/desktop Issue affects a desktop edition of Docker. E.g docker for mac label Feb 4, 2026

dvdksn force-pushed the gordon-ga branch from a353604 to 150aa27 Compare February 4, 2026 12:16

dvdksn requested review from krissetto, nunocoracao and rumpl February 9, 2026 17:07

dvdksn marked this pull request as ready for review February 9, 2026 17:08

dvdksn requested a review from aevesdocker as a code owner February 9, 2026 17:08

dvdksn requested a review from a team February 9, 2026 17:08

dvdksn added the status/review label Feb 9, 2026

github-actions bot reviewed Feb 9, 2026

View reviewed changes

dvdksn force-pushed the gordon-ga branch 2 times, most recently from 5430c70 to db666fb Compare February 10, 2026 15:47

gordon: revise gordon docs for gordon v2

88d0d59

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

dvdksn force-pushed the gordon-ga branch from db666fb to 88d0d59 Compare February 13, 2026 14:46

dvdksn changed the title ~~gordon: revise gordon docs for gordon v2/ga~~ gordon: revise gordon docs for gordon v2 Feb 13, 2026

dvdksn commented Feb 13, 2026

View reviewed changes

trungutt reviewed Feb 13, 2026

View reviewed changes


		![Advanced tool configuration](../images/gordon_advanced_tool_config.avif?w=500px&border=true)

		Gordon still requests approval before running allow-listed tools, unless YOLO

Conversation

dvdksn commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Documentation Review

Summary

Uh oh!

github-actions bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dvdksn commented Feb 4, 2026 •

edited

Loading

netlify bot commented Feb 4, 2026 •

edited

Loading