feat: update tasks docs (#18659)

Preview: https://coder.com/docs/@tasks-docs/ai-coder

---------

Co-authored-by: Hugo Dutka <hugo@coder.com>
This commit is contained in:
Ben Potter
2025-07-07 05:21:59 -07:00
committed by GitHub
parent 65809710e5
commit b26c9e2432
25 changed files with 229 additions and 497 deletions

View File

@ -1,95 +0,0 @@
# AI 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.
Coding agents are rapidly emerging to help developers tackle repetitive tasks,
explore codebases, and generate solutions with increasing effectiveness.
You can run these agents in Coder workspaces to leverage the power of cloud resources
and deep integration with your existing development workflows.
## Why Run AI Coding Agents in Coder?
Coder provides unique advantages for running AI coding agents:
- **Consistent environments**: Agents work in the same standardized environments as your developers.
- **Resource optimization**: Leverage powerful cloud resources without taxing local machines.
- **Security and isolation**: Keep sensitive code, API keys, and secrets in controlled environments.
- **Seamless collaboration**: Multiple developers can observe and interact with agent activity.
- **Deep integration**: Status reporting and task management directly in the Coder UI.
- **Scalability**: Run multiple agents across multiple projects simultaneously.
- **Persistent sessions**: Agents can continue working even when developers disconnect.
## Types of Coding Agents
AI coding agents generally fall into two categories, both fully supported in Coder:
### Headless Agents
Headless agents can run without an IDE open, making them ideal for:
- **Background automation**: Execute repetitive tasks without supervision.
- **Resource-efficient development**: Work on projects without keeping an IDE running.
- **CI/CD integration**: Generate code, tests, or documentation as part of automated workflows.
- **Multi-project management**: Monitor and contribute to multiple repositories simultaneously.
Additionally, with Coder, headless agents benefit from:
- Status reporting directly to the Coder dashboard.
- Workspace lifecycle management (auto-stop).
- Resource monitoring and limits to prevent runaway processes.
- API-driven management for enterprise automation.
| Agent | Supported models | Coder integration | Notes |
|---------------|---------------------------------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| Claude Code ⭐ | Anthropic Models Only (+ AWS Bedrock and GCP Vertex AI) | [First class integration](https://registry.coder.com/modules/coder/claude-code) ✅ | Enhanced security through workspace isolation, resource optimization, task status in Coder UI |
| Goose | Most popular AI models + gateways | [First class integration](https://registry.coder.com/modules/coder/goose) ✅ | Simplified setup with Terraform module, environment consistency |
| Aider | Most popular AI models + gateways | [First class integration](https://registry.coder.com/modules/coder/aider) ✅ | Simplified setup with Terraform module, environment consistency |
| OpenHands | Most popular AI models + gateways | In progress ⏳ ⏳ | Coming soon |
[Claude Code](https://github.com/anthropics/claude-code) is our recommended
coding agent due to its strong performance on complex programming tasks.
> [!TIP]
> Any agent can run in a Coder workspace via our [MCP integration](./headless.md),
> even if we don't have a specific module for it yet.
### In-IDE agents
In-IDE agents run within development environments like VS Code, Cursor, or Windsurf.
These are ideal for exploring new codebases, complex problem solving, pair programming,
or rubber-ducking.
| Agent | Supported Models | Coder integration | Coder key advantages |
|-----------------------------|-----------------------------------|------------------------------------------------------------------------|----------------------------------------------------------------|
| Cursor (Agent Mode) | Most popular AI models + gateways | ✅ [Cursor Module](https://registry.coder.com/modules/coder/cursor) | Pre-configured environment, containerized dependencies |
| Windsurf (Agents and Flows) | Most popular AI models + gateways | ✅ [Windsurf Module](https://registry.coder.com/modules/coder/windsurf) | Consistent setup across team, powerful cloud compute |
| Cline | Most popular AI models + gateways | ✅ via VS Code Extension | Enterprise-friendly API key management, consistent environment |
## Agent status reports in the Coder dashboard
Claude Code and Goose can report their status directly to the Coder dashboard:
- Task progress appears in the workspace overview.
- Completion status is visible without opening the terminal.
- Error states are highlighted.
## Get started
Ready to deploy AI coding agents in your Coder deployment?
1. [Create a Coder template for agents](./create-template.md).
1. Configure your chosen agent with appropriate API keys and permissions.
1. Start monitoring agent activity in the Coder dashboard.
## Next Steps
- [Create a Coder template for agents](./create-template.md)
- [Integrate with your issue tracker](./issue-tracker.md)
- [Learn about MCP and adding AI tools](./best-practices.md)

View File

@ -1,71 +1,53 @@
# Model Context Protocols (MCP) and adding AI tools # Best Practices
> [!NOTE] This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization.
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> Join our [Discord channel](https://discord.gg/coder) or
> [contact us](https://coder.com/contact) to get help or share feedback.
## Overview ## Identify Use Cases
Coder templates should be pre-equipped with the tools and dependencies needed To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case.
for development. With AI Agents, this is no exception.
## Prerequisites Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case:
- A Coder deployment with v2.21 or later | Scenario | Description | Examples | Tools |
- A [template configured for AI agents](./create-template.md) |------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| **Automating actions in the IDE** | Supplement tedious development with agents | Small refactors, generating unit tests, writing inline documentation, code search and navigation | [IDE Agents](./ide-agents.md) in Workspaces |
| **Developer-led investigation and setup** | Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work | Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations | [Tasks](./tasks.md), to a full IDE with [Workspaces](../user-guides/workspace-access/index.md) |
| **Prototyping & Business Applications** | User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases | Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development | [Tasks](./tasks.md) |
| **Full background jobs & long-running agents** | Agents that run independently without user interaction for extended periods of time | Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting | [Tasks](./tasks.md) API *(in development)* |
| **External agents and chat clients** | External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing | ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis | [MCP Server](./mcp-server.md) |
## Best Practices ## Provide Agents with Proper Context
- Use the most capable ML models you have access to in order to evaluate Agent While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization.
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/index.md) can be helpful ### Memory
> 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 Coding Agents like Claude Code often refer to a [memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization.
related services.
- Read our recommendations on [securing agents](./securing.md) to avoid
surprises.
## Adding Tools via MCP Look up the docs for the specific agent you're using to learn more about how to provide context to your agents.
Model Context Protocol (MCP) is an emerging standard for adding tools to your ### Tools (Model Context Protocol)
agents.
Follow the documentation for your [agent](./agents.md) to learn how to configure Agents can also use tools, often via [Model Context Protocol](https://modelcontextprotocol.io/introduction) to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog.
MCP servers. See
[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
to browse open source MCP servers.
### Our Favorite MCP Servers Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents.
In internal testing, we have seen significant improvements in agent performance #### Our Favorite MCP Servers
when these tools are added via MCP.
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 - [Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
to open a browser, and check its work by viewing output and taking to open a browser, and check its work by viewing output and taking
screenshots. screenshots.
- [desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP): - [desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP):
Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the background instead of blocking the main thread.
background instead of blocking the main thread.
## Next Steps ## Security & Permissions
- [Supervise Agents in the UI](./coder-dashboard.md) LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously.
- [Supervise Agents in the IDE](./ide-integration.md)
- [Supervise Agents Programmatically](./headless.md) [Learn more about securing agents with Coder Tasks](./security.md)
- [Securing Agents](./securing.md)
## Keep it Simple
Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time.

View File

@ -1,29 +0,0 @@
> [!NOTE]
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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)

View File

@ -1,66 +0,0 @@
# Create a Coder template for agents
> [!NOTE]
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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.
> [!TIP]
>
> Alternatively, you can [use a custom agent](./custom-agents.md) that is
> not in our registry via MCP.
The module uses `experiment_report_tasks` to stream changes to the Coder dashboard:
```hcl
# Enable experimental features
experiment_use_screen = true # Or use experiment_use_tmux = true to use tmux instead
experiment_report_tasks = true
```
## 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)

View File

@ -1,21 +1,11 @@
# Custom Agents # Custom Agents
> [!NOTE] Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks.
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> Join our [Discord channel](https://discord.gg/coder) or
> [contact us](https://coder.com/contact) to get help or share feedback.
Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder.
## Prerequisites ## Prerequisites
- A Coder deployment with v2.21 or later - A Coder deployment with v2.21 or later
- A [Coder workspace / template](./create-template.md) - A [Coder workspace / template](../admin/templates/creating-templates.md)
- A custom agent that supports Model Context Protocol (MCP) - A custom agent that supports Model Context Protocol (MCP)
## Getting Started ## Getting Started
@ -31,8 +21,8 @@ From there, the agent can run the MCP server with the `coder exp mcp server` com
Inside a Coder workspace, run the following commands: Inside a Coder workspace, run the following commands:
```sh ```sh
coder login # be sure to be authenticated with the Coder CLI coder login
export CODER_MCP_APP_STATUS_SLUG=my-agent # needs to be the same as the slug in the coder_app resource export CODER_MCP_APP_STATUS_SLUG=my-agent
# Use your own agent's logic and syntax here: # Use your own agent's logic and syntax here:
any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server" any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server"
@ -40,10 +30,9 @@ any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server"
This will start the MCP server and report activity back to the Coder control plane on behalf of the coder_app resource. This will start the MCP server and report activity back to the Coder control plane on behalf of the coder_app resource.
> See the [Goose module](https://github.com/coder/registry/blob/main/registry/coder/modules/goose/main.tf) source code for a real world example. > [!NOTE]
> See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/goose/main.tf) source code for a real world example.
## Contributing ## Contributing
We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.
See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.

View File

@ -1,57 +0,0 @@
> [!NOTE]
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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 exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder
coder exp mcp configure cursor # Configure Cursor to interact with Coder
```
> MCP is also used for various agents to report activity back to Coder. Learn more about this in [custom agents](./custom-agents.md).
## Coder CLI
Workspaces can be created, started, and stopped via the Coder CLI. See the
[CLI docs](../reference/cli/index.md) for more information.
## REST API
The Coder REST API can be used to manage workspaces and agents. See the
[API docs](../reference/api/index.md) for more information.
## Next Steps
- [Securing Agents](./securing.md)

View File

@ -0,0 +1,26 @@
Learn how to use Coder Workspaces with IDEs and plugins to run coding agents like Cursor, GitHub Copilot, Windsurf, RooCode, and more.
## How it works
Coder Workspaces are full development environments that run on your cloud infrastructure, such as Kubernetes or AWS EC2. Developers can connect with their favorite IDEs with pre-configured extensions and configuration for agentic coding.
![Workspace Page](../images/guides/ai-agents/workspace-page.png)
## Coder versus Local Development
Running coding agents in Coder workspaces provides several advantages over running them locally:
- **Fast, out-of-the-box setup**: LLMs, proxies, and MCP tools can be pre-configured for developers to use immediately, eliminating setup time and configuration hassles.
- **Consistent environments**: All developers use the same standardized environments, ensuring consistent access to tools and resources.
- **Resource optimization**: Leverage powerful cloud resources without taxing local machines.
- **Security and isolation**: Keep sensitive code, API keys, and secrets in controlled environments.
[Learn more about Coder](https://coder.com/cde/compare)
## IDE Support
Follow the Coder Documentation for [Connecting to Workspaces](../user-guides/workspace-access/index.md) to connect to your Coder Workspaces with your favorite IDEs.
## Pre-Configuring Extensions &amp; Plugins
Read our [VS Code module documentation](https://registry.coder.com/modules/coder/vscode-web) for examples on how to pre-install plugins like GitHub Copilot, RooCode, Sourcegraph Cody, and more in Coder workspaces.

View File

@ -1,30 +0,0 @@
> [!NOTE]
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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)

View File

@ -1,37 +1,19 @@
# Use AI Coding Agents in Coder Workspaces # Run AI Coding Agents in Coder
> [!NOTE] Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution.
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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: ## Agents in the IDE
- Protyping web applications or landing pages Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as Cursor, Windsurf, and Zed that include built-in coding agents to work alongside developers. Additionally, template admins can [pre-install extensions](https://registry.coder.com/modules/coder/vscode-web) for agents such as GitHub Copilot and Roo Code.
- Researching / onboarding to a codebase
- Assisting with lightweight refactors
- Writing tests and draft 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. These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor.
![AI Agents in Coder](../images/guides/ai-agents/landing.png) ## Agents with Coder Tasks (Beta)
## Prerequisites In cases where the IDE is secondary, such as protyping or long-running background jobs, agents like Claude Code or Aider are better for the job and new SaaS interfaces like [Devin](https://devin.ai) and [ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging.
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. [Coder Tasks](./tasks.md) is a new interface inside Coder to run and manage coding agents with a chat-based UI. Unlike SaaS-based products, Coder Tasks is self-hosted (included in your Coder deployment) and allows you to run any terminal-based agent such as Claude Code or Codex's Open Source CLI.
- A [Coder deployment](../install/index.md) with v2.21.0 or later ![Coder Tasks UI](../images/guides/ai-agents/tasks-ui.png)
- A Coder [template](../admin/templates/index.md) 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 [Learn more about Coder Tasks](./tasks.md) to how to get started and best practices.
<children></children>

View File

@ -1,61 +0,0 @@
# Create a Coder template for agents
> [!NOTE]
>
> This functionality is in beta and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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/index.md) or [CLI](../reference/cli/index.md) 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)

View File

@ -0,0 +1,33 @@
# MCP Server
Power users can configure Claude Desktop, Cursor, or other external agents to interact with Coder in order to:
- List workspaces
- Create/start/stop workspaces
- Run commands on workspaces
- Check in on agent activity
> [!NOTE]
> See our [toolsdk](https://pkg.go.dev/github.com/coder/coder/v2@v2.24.1/codersdk/toolsdk#pkg-variables) documentation for a full list of tools included in the MCP server
In this model, any custom agent 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
# First log in to Coder.
coder login <https://coder.example.com>
# Configure your client with the Coder MCP
coder exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder
coder exp mcp configure cursor # Configure Cursor to interact with Coder
```
For other agents, run the MCP server with this command:
```sh
coder exp mcp server
```
> [!NOTE]
> The MCP server is authenticated with the same identity as your Coder CLI and can perform any action on the user's behalf. Fine-grained permissions and a remote MCP server are in development. [Contact us](https://coder.com/contact) if this use case is important to you.

View File

@ -1,23 +1,13 @@
> [!NOTE]
>
> This functionality is in early access and is evolving rapidly.
>
> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
> Always review AI-generated content before using it in critical systems.
>
> 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 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 platform for running AI agents just as it is for other cloud development
environments. environments.
## Use Trusted Models ## Use Trusted Models
Most [agents](./agents.md) can be configured to either use a local LLM (e.g. Most agents 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 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 Bedrock). Research which models you are comfortable with and configure your
[Coder templates](./create-template.md) to use those. Coder templates to use those.
## Set up Firewalls and Proxies ## Set up Firewalls and Proxies
@ -29,8 +19,7 @@ not access or upload sensitive information.
Many agents require API keys to access external services. It is recommended to 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. create a separate API key for your agent with the minimum permissions required.
This will likely involve editing your This will likely involve editing your template for Agents to set different scopes or tokens
[template for Agents](./create-template.md) to set different scopes or tokens
from the standard one. from the standard one.
Additional guidance and tooling is coming in future releases of Coder. Additional guidance and tooling is coming in future releases of Coder.
@ -42,7 +31,4 @@ 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 humans to have more privileges and access compared to agents inside the same
workspace. workspace.
Trial agent boundaries in your workspaces by following the instructions in the - [Contact us for more information](https://coder.com/contact) and for early access to agent boundaries
[boundary-releases](https://github.com/coder/boundary-releases) repository.
- [Contact us for more information](https://coder.com/contact)

91
docs/ai-coder/tasks.md Normal file
View File

@ -0,0 +1,91 @@
# Coder Tasks (Beta)
Coder Tasks is an interface for running & managing coding agents such as Claude Code and Aider, powered by Coder workspaces.
![Tasks UI](../images/guides/ai-agents/tasks-ui.png)
Coder Tasks is best for cases where the IDE is secondary, such as prototyping or running long-running background jobs. However, tasks run inside full workspaces so developers can [connect via an IDE](../user-guides/workspace-access) to take a task to completion.
> [!NOTE]
> Coder Tasks is free and open source. If you are a Coder Premium customer or want to run hundreds of tasks in the background, [contact us](https://coder.com/contact) for roadmap information and volume pricing.
## Supported Agents (and Models)
Any terminal-based agent that supports Model Context Protocol (MCP) can be integrated with Coder Tasks, including your own custom agents.
Out of the box, agents like Claude Code, Aider, Goose, and Amazon Q are supported with built-in modules that can be added to a template. [See all agent modules in the Registry](https://registry.coder.com/modules?search=tag%3Aagent)
Enterprise LLM Providers such as AWS Bedrock, GCP Vertex and proxies such as LiteLLM can be used as well in order to keep intellectual property private. Self-hosted models such as llama4 can also be configured with specific agents, such as Aider and Goose.
## Architecture
Each task runs inside its own Coder workspace for isolation purposes. Agents like Claude Code also run in the workspace, and can be pre-installed via a module in the Coder Template. Agents then communicate with your LLM provider, so no GPUs are directly required in your workspaces for inference.
![High-Level Architecture](../images/guides/ai-agents/architecture-high-level.png)
Coder's [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) will pre-install the agent alongside [AgentAPI](https://github.com/coder/agentapi). AgentAPI is an open source project developed by Coder which improves status reporting and the Chat UI, regardless of which agent you use.
## Getting Started with Tasks
### Option 1&rpar; Import and Modify Our Example Template
Our example template is the best way to experiment with Tasks with a [real world demo app](https://github.com/gothinkster/realworld). The application is running in the background and you can experiment with coding agents.
![Tasks UI with realworld app](../images/guides/ai-agents/realworld-ui.png)
Try prompts such as:
- "rewrite the backend in go"
- "document the project structure"
- "change the primary color theme to purple"
To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://registry.coder.com/templates/coder-labs/tasks-docker)
> [!NOTE]
> The Tasks tab will appear automatically after you add a Tasks-compatible template and refresh the page.
### Option 2&rpar; Create or Duplicate Your Own Template
A template becomes a Task template if it defines a `coder_ai_task` resource and a `coder_parameter` named `"AI Prompt"`. Coder analyzes template files during template version import to determine if these requirements are met.
```hcl
data "coder_parameter" "ai_prompt" {
name = "AI Prompt"
type = "string"
}
# Multiple coder_ai_tasks can be defined in a template
resource "coder_ai_task" "claude-code" {
# At most one coder ai task can be instantiated during a workspace build.
# Coder fails the build if it would instantiate more than 1.
count = data.coder_parameter.ai_prompt.value != "" ? 1 : 0
sidebar_app {
# which app to display in the sidebar on the task page
id = coder_app.claude-code.id
}
}
```
> [!NOTE]
> This definition is not final and may change while Tasks is in beta. After any changes, we guarantee backwards compatibility for one minor Coder version. After that, you may need to update your template to continue using it with Tasks.
Because Tasks run unpredictable AI agents, often for background tasks, we recommend creating a separate template for Coder Tasks with limited permissions. You can always duplicate your existing template, then apply separate network policies/firewalls/permissions to the template. From there, follow the docs for one of our [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) in order to add it to your template, configure your LLM provider.
Alternatively, follow our guide for [custom agents](./custom-agents.md)
## Customizing the Task UI
The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `sidebar_app.id` field on the `coder_ai_task` resource.
If a workspace app has the special `"preview"` slug, a navbar will appear above it. This is intended for templates that let users preview a web app theyre working on.
We plan to introduce more customization options in future releases.
## Opting out of Tasks
If you tried Tasks and decided you don't want to use it, you can hide the Tasks tab by starting `coder server` with the `CODER_HIDE_AI_TASKS=true` environment variable or the `--hide-ai-tasks` flag.
## Next Steps
<children></children>

Binary file not shown.

After

Width:  |  Height:  |  Size: 232 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 198 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 243 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 337 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 152 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 537 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 478 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 285 KiB

View File

@ -816,60 +816,41 @@
"description": "Learn how to run and integrate agentic AI coding agents like GPT-Code, OpenDevin, or SWE-Agent in Coder workspaces to boost developer productivity.", "description": "Learn how to run and integrate agentic AI coding agents like GPT-Code, OpenDevin, or SWE-Agent in Coder workspaces to boost developer productivity.",
"path": "./ai-coder/index.md", "path": "./ai-coder/index.md",
"icon_path": "./images/icons/wand.svg", "icon_path": "./images/icons/wand.svg",
"children": [
{
"title": "Best Practices",
"description": "Best Practices running Coding Agents",
"path": "./ai-coder/best-practices.md"
},
{
"title": "In the IDE",
"description": "Run IDE agents with Coder",
"path": "./ai-coder/ide-agents.md"
},
{
"title": "Coder Tasks",
"description": "Run Coding Agents on your Own Infrastructure",
"path": "./ai-coder/tasks.md",
"state": ["beta"], "state": ["beta"],
"children": [ "children": [
{ {
"title": "Learn about coding agents", "title": "Custom Agents",
"description": "Learn about the different agentic AI agents and their tradeoffs", "description": "Run custom agents with Coder Tasks",
"path": "./ai-coder/agents.md"
},
{
"title": "Create a Coder template for agents",
"description": "Create a purpose-built template for your agentic AI agents",
"path": "./ai-coder/create-template.md",
"state": ["beta"]
},
{
"title": "Integrate with your issue tracker",
"description": "Assign tickets to agentic AI agents and interact via code reviews",
"path": "./ai-coder/issue-tracker.md",
"state": ["beta"]
},
{
"title": "Model Context Protocols (MCP) and adding AI tools",
"description": "Improve results by adding tools to your agentic AI agents",
"path": "./ai-coder/best-practices.md",
"state": ["beta"]
},
{
"title": "Supervise agents via Coder UI",
"description": "Interact with agentic agents via the Coder UI",
"path": "./ai-coder/coder-dashboard.md",
"state": ["beta"]
},
{
"title": "Supervise agents via the IDE",
"description": "Interact with agentic agents via VS Code or Cursor",
"path": "./ai-coder/ide-integration.md",
"state": ["beta"]
},
{
"title": "Programmatically manage agents",
"description": "Manage agentic agents via MCP, the Coder CLI, and/or REST API",
"path": "./ai-coder/headless.md",
"state": ["beta"]
},
{
"title": "Securing agents in Coder",
"description": "Learn how to secure agentic agents with boundaries",
"path": "./ai-coder/securing.md",
"state": ["early access"]
},
{
"title": "Custom agents",
"description": "Learn how to use custom agentic agents with Coder",
"path": "./ai-coder/custom-agents.md", "path": "./ai-coder/custom-agents.md",
"state": ["beta"] "state": ["beta"]
},
{
"title": "Security \u0026 Boundaries",
"description": "Learn about security and boundaries when running AI coding agents in Coder",
"path": "./ai-coder/security.md"
}
]
},
{
"title": "MCP Server",
"description": "Connect to agents Coder with a MCP server",
"path": "./ai-coder/mcp-server.md",
"state": ["beta"]
} }
] ]
}, },