more docs

coder · bpmct · Apr 2, 2025 · Apr 1, 2025 · Apr 1, 2025 · Apr 1, 2025
commit 81b47aa02c815784615e1a17bd5c9e6be08439b5
diff --git a/docs/images/guides/ai-agents/duplicate.png b/docs/images/guides/ai-agents/duplicate.png
diff --git a/docs/images/guides/ai-agents/github-action.png b/docs/images/guides/ai-agents/github-action.png
diff --git a/docs/images/guides/ai-agents/github-pr.png b/docs/images/guides/ai-agents/github-pr.png
diff --git a/docs/images/guides/ai-agents/ide-integration.png b/docs/images/guides/ai-agents/ide-integration.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -749,45 +749,60 @@
 						{
 							"title": "Learn about coding agents",
 							"description": "Learn about the different AI agents and their tradeoffs",
-							"path": "./tutorials/ai-agents/picking-an-agent.md"
+							"path": "./tutorials/ai-agents/agents.md"
 						},
 						{
 							"title": "Create a Coder template for agents",
 							"description": "Create a purpose-built template for your AI agents",
-							"path": "./tutorials/ai-agents/idk.md"
+							"path": "./tutorials/ai-agents/create-template.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
 							"title": "Integrate with your issue tracker",
 							"description": "Assign tickets to AI agents and interact via code reviews",
-							"path": "./tutorials/ai-agents/integrating-with-github.md"
+							"path": "./tutorials/ai-agents/issue-tracker.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
-							"title": "Adding tools via MCP",
+							"title": "Best practices & adding tools via MCP",
 							"description": "Improve results by adding tools to your agents",
-							"path": "./tutorials/ai-agents/adding-tools-via-mcp.md"
+							"path": "./tutorials/ai-agents/best-practices.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
 							"title": "Supervise agents via Coder UI",
 							"description": "Interact with agents via the Coder UI",
-							"path": "./tutorials/ai-agents/managing-via-ui.md"
+							"path": "./tutorials/ai-agents/coder-dashboard.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
 							"title": "Supervise agents via the IDE",
 							"description": "Interact with agents via VS Code or Cursor",
-							"path": "./tutorials/ai-agents/managing-via-ide.md"
+							"path": "./tutorials/ai-agents/ide-integration.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
 							"title": "Programatically manage agents",
 							"description": "Manage agents via MCP, the Coder CLI, and/or REST API",
-							"path": "./tutorials/ai-agents/programmatically-managing-agents.md"
+							"path": "./tutorials/ai-agents/headless.md",
+							"state": [
+								"early access"
+							]
 						},
 						{
-							"title": "Securing agents with Boundaries",
+							"title": "Securing agents in Coder",
 							"description": "Learn how to secure agents with boundaries",
-							"path": "./tutorials/ai-agents/securing-agents-with-boundaries.md",
-							"state": [
-								"premium"
-							]
+							"path": "./tutorials/ai-agents/securing.md"
 						}
 					]
 				},

diff --git a/docs/tutorials/ai-agents/README.md b/docs/tutorials/ai-agents/README.md
@@ -1,12 +1,21 @@
 # Run AI Agents in Coder (Early Access)
 
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
 AI Coding Agents such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Goose](https://block.github.io/goose/), and [Aider](https://github.com/paul-gauthier/aider) are becoming increasingly popular for:
 
 - Protyping web applications or landing pages
 - Researching / onboarding to a codebase
 - Assisting with lightweight refactors
 - Writing tests and documentation
-- Well-defined "good first issues"
+- Small, well-defined chores
 
 With Coder, you can self-host AI agents in isolated development environments with proper context and tooling around your existing developer workflows. Whether you are a regulated enterprise or an individual developer, running AI agents at scale with Coder is much more productive and secure than running them locally.
 

diff --git a/docs/tutorials/ai-agents/agents.md b/docs/tutorials/ai-agents/agents.md
@@ -0,0 +1,52 @@
+# Coding Agents
+
+> [!NOTE]
+>
+> This page is not exhaustive and the landscape is evolving rapidly. Please
+> [open an issue](https://github.com/coder/coder/issues/new) or submit a pull
+> request if you'd like to see your favorite agent added or updated.
+
+There are several types of coding agents emerging:
+
+- **Headless agents** can run without an IDE open and are great for rapid
+  prototyping, background tasks, and chat-based supervision.
+- **In-IDE agents** require developers keep their IDE opens and are great for
+  interactive, focused coding on more complex tasks.
+
+## Headless agents
+
+Headless agents can run without an IDE open, or alongside any IDE. They
+typically run as CLI commands or web apps. With Coder, developers can interact
+with agents via any preferred tool such as via PR comments, within the IDE,
+inside the Coder UI, or even via the REST API or an MCP client such as Claude
+Desktop or Cursor.
+
+| Agent          | Supported Models                                        | Coder Support                                                      | Limitations                                             |
+| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
+| Claude Code ⭐ | Anthropic Models Only (+ AWS Bedrock and GCP Vertex AI) | First class integration ✅                                         | Beta (research preview)                                 |
+| Goose          | Most popular AI models + gateways                       | First class integration ✅                                         | Less effective compared to Claude Code                  |
+| Aider          | Most popular AI models + gateways                       | Requires [MCP Plugin](https://github.com/lutzleonhardt/mcpm-aider) | Can only run 1-2 defined commands (e.g. build and test) |
+| OpenHands      | Most popular AI models + gateways                       | In progress ⏳                                                     | Challenging setup, no MCP support                       |
+
+[Claude Code](https://github.com/anthropics/claude-code) is our recommended
+coding agent due to its strong performance on complex programming tasks.
+
+## In-IDE agents
+
+Coding agents can also run within an IDE, such as VS Code, Cursor or Windsurf.
+These editors and extensions are fully supported in Coder and work well for more
+complex and focused tasks where an IDE is strictly required.
+
+| Agent                       | Supported Models                  | Coder Support                                                 |
+| --------------------------- | --------------------------------- | ------------------------------------------------------------- |
+| Cursor (Agent Mode)         | Most popular AI models + gateways | ✅ [Cursor Module](https://registry.coder.com/modules/cursor) |
+| Windsurf (Agents and Flows) | Most popular AI models + gateways | ✅ via Remote SSH                                             |
+| Cline                       | Most popular AI models + gateways | ✅ via VS Code Extension                                      |
+
+In-IDE agents do not require a special template as they cannot be used in a
+headless fashion. However, they can still be run in isolated Coder workspaces
+and report activity to the Coder UI.
+
+## Next Steps
+
+- [Create a Coder template for agents](./create-template.md)
diff --git a/docs/tutorials/ai-agents/best-practices.md b/docs/tutorials/ai-agents/best-practices.md
@@ -0,0 +1,68 @@
+# Best Practices & Adding Tools via MCP
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
+## Overview
+
+Coder templates should be pre-equipped with the tools and dependencies needed
+for development. With AI Agents, this is no exception.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Best Practices
+
+- Since agents are still early, it is best to use the most capable ML models you
+  have access to in order to evaluate their performance.
+- Set a system prompt with the `AI_SYSTEM_PROMPT` environment in your template
+- Within your repositories, write a `.cursorrules`, `CLAUDE.md` or similar file
+  to guide the agent's behavior.
+- To read issue descriptions or pull request comments, install the proper CLI
+  (e.g. `gh`) in your image/template.
+- Ensure your [template](./create-template.md) is truly pre-configured for
+  development without manual intervention (e.g. repos are cloned, dependencies
+  are built, secrets are added/mocked, etc.)
+  > Note: [External authentication](../../admin/auth.md) can be helpful to
+  > authenticate with third-party services such as GitHub or JFrog.
+- Give your agent the proper tools via MCP to interact with your codebase and
+  related services.
+- Read our recommendations on [securing agents](./securing.md) to avoid
+  surprises.
+
+## Adding Tools via MCP
+
+Model Context Protocol (MCP) is an emerging standard for adding tools to your
+agents.
+
+Follow the documentation for your [agent](./agents.md) to learn how to configure
+MCP servers. See
+[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
+to browse open source MCP servers.
+
+### Our Favorite MCP Servers
+
+In internal testing, we have seen significant improvements in agent performance
+when these tools are added via MCP.
+
+- [Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
+  to open a browser, and check its work by viewing output and taking
+  screenshots.
+- [desktop-commander](https://github.com/desktop-commander/desktop-commander):
+  Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the
+  background instead of blocking the main thread.
+
+## Next Steps
+
+- [Supervise Agents in the UI](./coder-dashboard.md)
+- [Supervise Agents in the IDE](./ide-integration.md)
+- [Supervise Agents Programatically](./headless.md)
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/coder-dashboard.md b/docs/tutorials/ai-agents/coder-dashboard.md
@@ -0,0 +1,27 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you can view
+status and switch between workspaces from the Coder dashboard.
+
+- TODO
+- TODO
+
+## Next Steps
+
+- [Supervise Agents in the IDE](./ide-integration.md)
+- [Supervise Agents Programatically](./headless.md)
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/create-template.md b/docs/tutorials/ai-agents/create-template.md
@@ -0,0 +1,57 @@
+# Create a Coder template for agents
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
+## Overview
+
+This tutorial will guide you through the process of creating a Coder template
+for agents.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A template that is pre-configured for your projects
+- You have selected an [agent](./agents.md) based on your needs
+
+## 1. Duplicate an existing template
+
+It is best to create a seperate template for AI agents based on an existing
+template that has all of the tools and dependencies installed.
+
+This can be done in the Coder UI:
+
+![Duplicate template](../../images/guides/ai-agents/duplicate.png)
+
+## 2. Add a module for supported agents
+
+We currently publish a module for Claude Code and Goose. Additional modules are
+[coming soon](./agents.md).
+
+- [Add the Claude Code module](https://registry.coder.com/modules/claude-code)
+- [Add the Goose module](https://registry.coder.com/modules/goose)
+
+Follow the instructions in the Coder Registry to install the module. Be sure to
+enable the `experiment_use_screen` and `experiment_report_tasks` variables to
+report status back to the Coder control plane.
+
+> Alternatively, you can report status from a custom agent back to the Coder
+> control plane via our MCP server. For more information,
+> [join our Discord](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact).
+
+## 3. Confirm tasks are streaming in the Coder UI
+
+The Coder dashboard should now show tasks being reported by the agent.
+
+![AI Agents in Coder](../../images/guides//ai-agents/landing.png)
+
+## Next Steps
+
+- [Integrate with your issue tracker](./issue-tracker.md)
diff --git a/docs/tutorials/ai-agents/headless.md b/docs/tutorials/ai-agents/headless.md
@@ -0,0 +1,54 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you can manage
+it programatically via the MCP server, Coder CLI, and/or REST API.
+
+## MCP Server
+
+Power users can configure [Claude Desktop](https://claude.ai/download), Cursor,
+or other tools with MCP support to interact with Coder in order to:
+
+- List workspaces
+- Create/start/stop workspaces
+- Run commands on workspaces
+- Check in on agent activity
+
+In this model, an [IDE Agent](./agents.md#ide-agent) could interact with a
+remote Coder workspace, or Coder can be used in a remote pipeline or larger
+workflow.
+
+The Coder CLI has options to automatically configure MCP servers for you. On
+your local machine, run the following command:
+
+```sh
+coder mcp claude-desktop # Configure Claude Desktop to interact with Coder
+coder mcp cursor # Configure Cursor to interact with Coder
+```
+
+## Coder CLI
+
+Workspaces can be created, started, and stopped via the Coder CLI. See the
+[CLI docs](../../reference/cli/) for more information.
+
+## REST API
+
+The Coder REST API can be used to manage workspaces and agents. See the
+[API docs](../../reference/api/) for more information.
+
+## Next Steps
+
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/ide-integration.md b/docs/tutorials/ai-agents/ide-integration.md
@@ -0,0 +1,28 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) for support or feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+- VS Code, Windsurf, or Cursor IDE with the
+  [Coder Extension](https://github.com/coder/vscode-coder/releases) v1.6.0+
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you view status
+and switch between workspaces from the IDE. This can be very helpful for
+reviewing code, working along with the agent, and more.
+
+![IDE Integration](../../images/guides/ai-agents/ide-integration.png)
+
+## Next Steps
+
+- [Programatically manage agents](./headless.md)
+- [Securing Agents with Boundaries](./securing.md)