diff --git a/docs/images/guides/ai-agents/duplicate.png b/docs/images/guides/ai-agents/duplicate.png new file mode 100644 index 0000000000000..0122671424792 Binary files /dev/null and b/docs/images/guides/ai-agents/duplicate.png differ diff --git a/docs/images/guides/ai-agents/github-action.png b/docs/images/guides/ai-agents/github-action.png new file mode 100644 index 0000000000000..8ad695c137614 Binary files /dev/null and b/docs/images/guides/ai-agents/github-action.png differ diff --git a/docs/images/guides/ai-agents/github-pr.png b/docs/images/guides/ai-agents/github-pr.png new file mode 100644 index 0000000000000..3c4785e56a559 Binary files /dev/null and b/docs/images/guides/ai-agents/github-pr.png differ diff --git a/docs/images/guides/ai-agents/ide-integration.png b/docs/images/guides/ai-agents/ide-integration.png new file mode 100644 index 0000000000000..2ddd85c786e79 Binary files /dev/null and b/docs/images/guides/ai-agents/ide-integration.png differ diff --git a/docs/images/guides/ai-agents/landing.png b/docs/images/guides/ai-agents/landing.png new file mode 100644 index 0000000000000..b1c09a4f222c7 Binary files /dev/null and b/docs/images/guides/ai-agents/landing.png differ diff --git a/docs/images/guides/ai-agents/workspace-details.png b/docs/images/guides/ai-agents/workspace-details.png new file mode 100644 index 0000000000000..71e22d9604303 Binary files /dev/null and b/docs/images/guides/ai-agents/workspace-details.png differ diff --git a/docs/images/guides/ai-agents/workspaces-list.png b/docs/images/guides/ai-agents/workspaces-list.png new file mode 100644 index 0000000000000..32e07d0c41cf9 Binary files /dev/null and b/docs/images/guides/ai-agents/workspaces-list.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 7b15d7ac81754..a4032402e18a4 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -693,6 +693,60 @@ "description": "Learn how to install and run Coder quickly", "path": "./tutorials/quickstart.md" }, + { + "title": "Run AI Coding Agents with Coder", + "description": "Learn how to run and secure agents in Coder", + "path": "./tutorials/ai-agents/README.md", + "state": ["early access"], + "children": [ + { + "title": "Learn about coding agents", + "description": "Learn about the different AI agents and their tradeoffs", + "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/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/issue-tracker.md", + "state": ["early access"] + }, + { + "title": "Best practices \u0026 adding tools via MCP", + "description": "Improve results by adding tools to your agents", + "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/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/ide-integration.md", + "state": ["early access"] + }, + { + "title": "Programmatically manage agents", + "description": "Manage agents via MCP, the Coder CLI, and/or REST API", + "path": "./tutorials/ai-agents/headless.md", + "state": ["early access"] + }, + { + "title": "Securing agents in Coder", + "description": "Learn how to secure agents with boundaries", + "path": "./tutorials/ai-agents/securing.md" + } + ] + }, { "title": "Write a Template from Scratch", "description": "Learn how to author Coder templates", diff --git a/docs/tutorials/ai-agents/README.md b/docs/tutorials/ai-agents/README.md new file mode 100644 index 0000000000000..ca0234dd91416 --- /dev/null +++ b/docs/tutorials/ai-agents/README.md @@ -0,0 +1,36 @@ +# 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) to get help or share 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 +- 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. + +![AI Agents in Coder](../../images/guides//ai-agents/landing.png) + +## Prerequisites + +Coder is free and open source for developers, with a [premium plan](https://coder.com/pricing) for enterprises. You can self-host a Coder deployment in your own cloud provider. + +- A [Coder deployment](../../install/) with v2.21.0 or later +- A Coder [template](../../admin/templates/) for your project(s). +- Access to at least one ML model (e.g. Anthropic Claude, Google Gemini, OpenAI) + - Cloud Model Providers (AWS Bedrock, GCP Vertex AI, Azure OpenAI) are supported with some agents + - Self-hosted models (e.g. llama3) and AI proxies (OpenRouter) are supported with some agents + +## Table of Contents + + diff --git a/docs/tutorials/ai-agents/agents.md b/docs/tutorials/ai-agents/agents.md new file mode 100644 index 0000000000000..2a2aa8c216107 --- /dev/null +++ b/docs/tutorials/ai-agents/agents.md @@ -0,0 +1,55 @@ +# 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 | In progress ⏳ | 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. + +> Note: Any agent can run in a Coder workspace via our +> [MCP integration](./headless.md). + +## 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 are not 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 new file mode 100644 index 0000000000000..2c75f91d6c0f9 --- /dev/null +++ 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) to get help or share 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/external-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/wonderwhy-er/DesktopCommanderMCP): + 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 Programmatically](./headless.md) +- [Securing Agents](./securing.md) diff --git a/docs/tutorials/ai-agents/coder-dashboard.md b/docs/tutorials/ai-agents/coder-dashboard.md new file mode 100644 index 0000000000000..598f58d006523 --- /dev/null +++ b/docs/tutorials/ai-agents/coder-dashboard.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) to get help or share 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. + +![Coder Dashboard](../../images/guides/ai-agents/workspaces-list.png) + +![Workspace Details](../../images/guides/ai-agents/workspace-details.png) + +## Next Steps + +- [Supervise Agents in the IDE](./ide-integration.md) +- [Supervise Agents Programmatically](./headless.md) +- [Securing Agents](./securing.md) diff --git a/docs/tutorials/ai-agents/create-template.md b/docs/tutorials/ai-agents/create-template.md new file mode 100644 index 0000000000000..6a203593575eb --- /dev/null +++ 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) to get help or share 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 separate 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 new file mode 100644 index 0000000000000..e7fdb03e33633 --- /dev/null +++ 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) to get help or share 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 programmatically 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#in-ide-agents) could interact with a +remote Coder workspace, or Coder can be used in a remote pipeline or a 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 new file mode 100644 index 0000000000000..5634fe71732d9 --- /dev/null +++ b/docs/tutorials/ai-agents/ide-integration.md @@ -0,0 +1,29 @@ +> [!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) to get help or share 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+ or + the [experimental AI VSIX](https://github.com/coder/vscode-coder/releases/) + +## Overview + +Once you have an agent running and reporting activity to Coder, you can view the +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 + +- [Programmatically manage agents](./headless.md) +- [Securing Agents with Boundaries](./securing.md) diff --git a/docs/tutorials/ai-agents/issue-tracker.md b/docs/tutorials/ai-agents/issue-tracker.md new file mode 100644 index 0000000000000..ba4af3bad9828 --- /dev/null +++ b/docs/tutorials/ai-agents/issue-tracker.md @@ -0,0 +1,60 @@ +# 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) to get help or share feedback. + +## Overview + +Coder has first-class support for managing agents through Github, but can also +integrate with other issue trackers. Use our action to interact with agents +directly in issues and PRs. + +## Prerequisites + +- A Coder deployment with v2.21 or later +- A [template configured for AI agents](./create-template.md) + +## GitHub + +### GitHub Action + +The [start-workspace](https://github.com/coder/start-workspace-action) GitHub +action will create a Coder workspace based on a specific phrase in a comment +(e.g. `@coder`). + +![GitHub Issue](../../images/guides/ai-agents/github-action.png) + +When properly configured with an [AI template](./create-template.md), the agent +will begin working on the issue. + +### Pull Request Support (Coming Soon) + +We're working on adding support for an agent automatically creating pull +requests and responding to your comments. Check back soon or +[join our Discord](https://discord.gg/coder) to stay updated. + +![GitHub Pull Request](../../images/guides/ai-agents/github-pr.png) + +## Integrating with Other Issue Trackers + +While support for other issue trackers is under consideration, you can can use +the [REST API](../../reference/api/) or [CLI](../../reference/cli/) to integrate +with other issue trackers or CI pipelines. + +In addition, an [Open in Coder](../../admin/templates/open-in-coder.md) flow can +be used to generate a URL and/or markdown button in your issue tracker to +automatically create a workspace with specific parameters. + +## Next Steps + +- [Best practices & adding tools via MCP](./best-practices.md) +- [Supervise Agents in the UI](./coder-dashboard.md) +- [Supervise Agents in the IDE](./ide-integration.md) +- [Supervise Agents Programmatically](./headless.md) +- [Securing Agents with Boundaries](./securing.md) diff --git a/docs/tutorials/ai-agents/securing.md b/docs/tutorials/ai-agents/securing.md new file mode 100644 index 0000000000000..f4e1f47ab3985 --- /dev/null +++ b/docs/tutorials/ai-agents/securing.md @@ -0,0 +1,47 @@ +> [!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) to get help or share feedback. + +As the AI landscape is evolving, we are working to ensure Coder remains a secure +platform for running AI agents just as it is for other cloud development +environments. + +## Use Trusted Models + +Most [agents](./agents.md) can be configured to either use a local LLM (e.g. +llama3), an agent proxy (e.g. OpenRouter), or a Cloud-Provided LLM (e.g. AWS +Bedrock). Research which models you are comfortable with and configure your +[Coder templates](./create-template.md) to use those. + +## Set up Firewalls and Proxies + +Many enterprises run Coder workspaces behind a firewall or a proxy to prevent +threats or bad actors. These same protections can be used to ensure AI agents do +not access or upload sensitive information. + +## Separate API keys and scopes for agents + +Many agents require API keys to access external services. It is recommended to +create a separate API key for your agent with the minimum permissions required. +This will likely involve editing your +[template for Agents](./create-template.md) to set different scopes or tokens +from the standard one. + +Additional guidance and tooling is coming in future releases of Coder. + +## Set Up Agent Boundaries (Premium) + +Agent Boundaries add an additional layer and isolation of security between the +agent and the rest of the environment inside of your Coder workspace, allowing +humans to have more privileges and access compared to agents inside the same +workspace. + +Trial agent boundaries in your workspaces by following the instructions in the +[boundary-releases](https://github.com/coder/boundary-releases) repository. + +- [Contact us for more information](https://coder.com/contact) diff --git a/site/src/theme/icons.json b/site/src/theme/icons.json index 3639d73f2fb4b..b83a3320c67df 100644 --- a/site/src/theme/icons.json +++ b/site/src/theme/icons.json @@ -14,6 +14,7 @@ "azure.svg", "bitbucket.svg", "centos.svg", + "claude.svg", "clion.svg", "code.svg", "coder.svg", @@ -49,6 +50,7 @@ "go.svg", "goland.svg", "google.svg", + "goose.svg", "image.svg", "intellij.svg", "java.svg", diff --git a/site/static/icon/claude.svg b/site/static/icon/claude.svg new file mode 100644 index 0000000000000..998fb0d52ffb8 --- /dev/null +++ b/site/static/icon/claude.svg @@ -0,0 +1,4 @@ + + + + diff --git a/site/static/icon/goose.svg b/site/static/icon/goose.svg new file mode 100644 index 0000000000000..cbbe8419a9868 --- /dev/null +++ b/site/static/icon/goose.svg @@ -0,0 +1,4 @@ + + + +