Files
coder/docs/ai-coder/agents/getting-started.md
T
Michael Suchacz 6bae268487 fix: move organization instructions to the Instructions page (#30428)
Moves organization instructions (#30272) from the Coder Agents page to
**AI Settings** > **Coder Agents** > **Instructions**, so every Coder
Agents instruction is managed on one page. The API and stored data are
unchanged.

- **Deployment admins** see a "Deployment instructions" section with the
existing system prompt and plan mode form, then an "Organization
instructions" section. The organization section has an organization
picker when there is more than one organization.
- **Organization admins and auditors** who can read an organization's
chat model configuration get an Instructions entry in the AI settings
sidebar and see only the organization section. Auditors get it
read-only.
- The selected organization is kept in `?org=`, and the sidebar link
carries it over from the other AI settings pages.
- The Coder Agents page goes back to its layout from before #30272. Its
sections and the new page's sections share new `SettingsSection` and
`OrganizationSettingsSection` components.
- Three docs pages point to the new location.

Other behavior changes:

- The deployment section shows a loader while loading and an error alert
when loading or refreshing fails. Before, the page rendered nothing
until both settings loaded.
- The deployment forms no longer have their own accessible names,
because each section is named by its heading.

## Testing

- Vitest for the Instructions page and sidebar link, and stories for the
new states. Breaking each of the 9 main code paths, or removing the
instructions field's accessible name, fails its test.
- The branch merges `main` for #30402, which made the organization
picker a combobox.
- CI passes on `a0cc6a98660`.
- Remote dogfood UAT, [evidence
chat](https://dogfood.cdr.dev/agents/1cbf9da4-9671-4890-ade1-c151a1a69cd7):
**PASS** on `a0d9c3fca46`, 14 scenarios across every role, `?org=`
handling, injected load failures, keyboard use, and a 390 px layout. The
remote agent's FAIL (a double-click on Save sends 2 PUTs) also happens
on the merge base, so it predates this PR. Delta round on `a0cc6a98660`:
**PASS**. When the permission re-check fails, the owner and an
organization admin see the alert above the organization section, and the
unsaved draft stays and saves.
- UAT notes left as is: the fallback for an unreadable `?org=` is
read-only, as on the Coder Agents page; `?org=` matching is
case-sensitive, as on the Models and Spend pages; the old
`/agents/settings/instructions` redirect drops `?org=`; the permission
alert shows the server's error message without saying which check
failed, as on the Models pages.

## Screenshots

From UAT on a test deployment.

| Organization admin | Owner, after a failed refresh (unsaved edit kept)
|
|---|---|
| ![Organization admin sees only the organization
section](https://gist.githubusercontent.com/ibetitsmike/1027eba97c252d6f3e921d2f46debd01/raw/8c6baf5a5b4784cdfecd066fae54af7f4f3c4881/r3-org-admin-instructions.png)
| ![Error alert above the deployment
form](https://gist.githubusercontent.com/ibetitsmike/1027eba97c252d6f3e921d2f46debd01/raw/8c6baf5a5b4784cdfecd066fae54af7f4f3c4881/r3-owner-refresh-error-draft-kept.png)
|
| **Coder Agents page, no instructions card** | **Unavailable `?org=`:
warning and read-only fallback** |
| ![Coder Agents
page](https://gist.githubusercontent.com/ibetitsmike/1027eba97c252d6f3e921d2f46debd01/raw/8c6baf5a5b4784cdfecd066fae54af7f4f3c4881/r3-coder-agents-page.png)
| ![Unavailable organization
warning](https://gist.githubusercontent.com/ibetitsmike/1027eba97c252d6f3e921d2f46debd01/raw/8c6baf5a5b4784cdfecd066fae54af7f4f3c4881/r3-unavailable-org-fallback.png)
|

## Review record

1. `coder-frontend-review` (8 reviewer agents) on `3dd65e828f9`: fixed
in `a0d9c3fca46` (deployment refetch errors were dropped, plus naming,
prop types, test waits, and a single-organization story). Declined:
`SettingsHeader` in `SettingsSection` and merging the sidebar groups
(both change existing layout), and restructuring the moved card (git
would stop detecting the move).
2. `frontend-review` (FE1 to FE10) on `a0d9c3fca46`: every rule passes,
no changes.
3. Codex,
[review](https://github.com/coder/coder/pull/30428#pullrequestreview-5431118231)
on `a0d9c3fca46`: 1 P2, a docs sentence wrote "more than 1" where the
numbers guide spells out "one". Fixed in `0e71b8f16b9`.
4. Codex,
[review](https://github.com/coder/coder/pull/30428#pullrequestreview-5431285875)
on `0e71b8f16b9`: 2 findings, each confirmed by a failing test and fixed
in `a0cc6a98660`. A failed background re-check of organization
permissions showed no alert, unlike the old Coder Agents page and the
Models pages (P2). The page tests found the instructions field by its
value, so removing its accessible name went unnoticed (P1).
5. `coder-frontend-review` (8 reviewer agents) and `frontend-review`
(FE1 to FE10) on `a0cc6a98660`: everything passes, no changes. The round
1 `findByDisplayValue` suggestion is reversed, because FE10 asks for
role and name queries.
6. Codex on `a0cc6a98660`: [no major
issues](https://github.com/coder/coder/pull/30428#issuecomment-6020794170).

> Xum, an AI coding agent, implemented, tested, and opened this PR on
behalf of @ibetitsmike.
2026-10-09 11:14:59 +02:00

16 KiB
Raw Blame History

title
title
Getting started

This guide walks platform teams and administrators through setting up Coder Agents, preparing your deployment, and running your first Coder Agent.

Prerequisites

Before you begin, confirm the following:

  • Coder deployment running the latest release.
  • LLM provider credentials — an API key for at least one supported provider (Anthropic, OpenAI, Google, Azure OpenAI, AWS Bedrock, OpenAI Compatible, OpenRouter, or Vercel AI Gateway).
  • Network access from the control plane to your LLM provider. Workspaces do not need LLM access — only the control plane does.
  • At least one template with a descriptive name and description for the agent to select when provisioning workspaces.
  • Admin access to the Coder deployment for configuring providers.
  • Access to configure models in each organization where you configure models. The Organization Admin role and the Owner role include this access. A custom role with model configuration access also works.
  • Organization membership for each user who uses Coder Agents. Every organization member can use Coder Agents by default. To restrict access, see Control who can use Coder Agents. Users also need read access to at least one model in the organization. New models are shared with the whole organization by default. See Manage model permissions.

Step 1: Configure an LLM provider and model

Important

Deployment administrators configure providers and deployment settings. Users with model configuration access in an organization configure that organization's models. Coder enables the edit controls for the organization that you select. Coder shows the deployment settings only to deployment administrators. Users with model access can view the relevant Models and Coder Agents pages. Users with MCP server access can open the MCP servers page.

To configure Coder Agents:

  1. Navigate to Admin settings > AI and select Providers.
  2. Add or update a provider with its credentials and upstream endpoint, then save it.
  3. Navigate to Admin settings > AI > Models.
  4. Select the correct organization. Coder shows the organization picker when you can access more than 1 organization.
  5. Select Add model and configure at least one model with its identifier, display name, and context limit.

Coder makes the first model of an organization the default model. To change the default later, open a model and select Set as Coder Agents default model, or pick a model in the Default model row under Admin settings > AI > Coder Agents > Organization settings.

Each organization has its own model list and its own default model. Repeat the model steps in every organization that uses Coder Agents. Refer to Organization scope for the settings that stay deployment-wide.

Detailed instructions for each provider and model option are in the Models documentation.

Tip

Start with a single frontier model to validate your setup before adding additional providers.

Step 2: Start your first Coder Agent

  1. Go to the Agents page in the Coder dashboard.
  2. Select a model from the dropdown (your default will be pre-selected).
  3. Type a prompt and send it.

The agent processes the prompt in the control plane. When the conversation and available tools are sufficient, it works without provisioning a workspace. If missing tools, skills, MCP integrations, or context block progress, the agent selects a template and provisions a workspace to continue. It also provisions a workspace for tasks that need file access, command execution, or code changes.

Control who can use Coder Agents

Organization members can use Coder Agents by default. Access comes from the Coder Agents User (agents-access) organization role, which each organization grants to members through its default member roles.

Members who don't hold the role directly lose Coder Agents access when you remove Coder Agents User from the default roles. Role sync assigns roles at sign-in and doesn't store default roles, so members who get the role through role sync regain access at their next sign-in, and mapping the role in advance doesn't shorten the gap.

To limit Coder Agents to a subset of members in an organization (requires a Premium license):

  1. Remove Coder Agents User from the organization's default roles. In the dashboard, go to Admin settings > Organizations > Roles > Default Roles. From the CLI, run coder organizations edit --org <organization> --default-org-member-roles organization-workspace-access, keeping any other default roles in the list.
  2. Grant agents-access to the members who need it:
    • With IdP organization role sync, map an IdP group or role to agents-access.
    • Without role sync, assign Coder Agents User from Admin settings > Organizations > Members.

Keep the following behavior in mind:

  • Removing a user from the mapped IdP group or role removes their Coder Agents access at their next sign-in.
  • Owners and Organization Admins can always use Coder Agents, whatever the default roles are.
  • Service accounts don't inherit agents-access from the default roles. Assign the role to a service account directly if it needs Coder Agents.
  • Members without the role can't use Coder Agents or open chats they created earlier. Their chats are kept and become available again when they regain the role. A chat shared with them stays readable.
  • Model permissions still apply: users also need read access to at least one model.

Optimize your templates

The agent selects templates based on their name, description, and README. It does not read Terraform. Clear, specific descriptions are the most important factor in whether the agent picks the right template.

Update your template descriptions to include:

  • The language, framework, or stack the template targets.
  • Which repository or service it is for, if applicable.
  • What type of work it supports (backend, frontend, data pipeline, etc.).

When 128 characters is not enough, put the most important routing context near the top of the template's README.md. The chat agent's template listing includes a bounded README excerpt (roughly the first 1,000 characters), and template detail includes the README (up to roughly 8,000 characters). Both are reduced to plain text: frontmatter is stripped, link text is kept while link URLs are dropped, images and badges are dropped entirely, and code blocks and tables are preserved as text.

Good examples:

Description Why it works
Python backend services for the payments repo. Includes Poetry, Python 3.12, and PostgreSQL Specific language, repo, and toolchain
React frontend development for the customer portal. Node 20, pnpm, Storybook pre-installed Clear stack, named project, key tools listed
General-purpose Go development environment with Go 1.23, Docker, and common CLI tools Broad but descriptive

Descriptions to avoid:

Description Problem
Team A template v2 No information about what the template is for
Dev environment Too generic to distinguish from other templates
Default Tells the agent nothing

See Template Optimization for the full guide, including dedicated agent templates, network boundaries, credential scoping, and pre-installing dependencies.

Things to know before you start

Plan for change between releases

Coder Agents is generally available. However, APIs, behavior, and configuration may change between releases. As always, you should review release notes and the changelog before upgrading, so changes do not affect production.

Use HTTPS for push notifications

Coder Agents use browser push notifications to alert you when a task completes or needs attention. Most browsers require a secure (HTTPS) origin for the Push API to work. If your access URL uses plain HTTP, push notifications may not function.

This does not affect agents themselves — only the browser notification delivery. If you terminate TLS at a reverse proxy, ensure the access URL is configured with an https:// scheme.

Set a deployment-wide system prompt

Administrators can set a system prompt that applies to all Coder Agents across the deployment. Use this to encode organizational conventions:

  • Coding standards and style guidelines.
  • Commit message formats.
  • Branch naming conventions.
  • Required review processes before merging.
  • Any guardrails specific to your environment.

Configure the system prompt from Admin settings > AI > Coder Agents > Instructions or via the API at PUT /api/v2/chats/config/system-prompt.

In a deployment with several organizations, organization administrators can also add organization instructions under Admin settings > AI > Coder Agents > Instructions. Coder adds them after the deployment system prompt for new chats in that organization. Refer to Platform Controls for details.

Understand the security model

The agent runs in the control plane, not inside workspaces. This means:

  • No LLM API keys in workspaces. Credentials stay in the control plane.
  • No agent software in workspaces. No supply chain risk from third-party agent tools.
  • User identity is always attached. Every action is tied to the user who submitted the prompt — no shared bot accounts.
  • No privilege escalation. The agent has exactly the same permissions as the prompting user.

Agent workspaces inherit the same network access as any manually created workspace. If your templates don't restrict egress, the agent has full internet access from the workspace. Consider creating dedicated agent templates with tighter network policies.

Plan for LLM costs

Every conversation turn sends tokens to your LLM provider. Long-running tasks, sub-agent delegation, and complex multi-step work can consume significant token volume. Consider:

  • Starting with a single model to establish a cost baseline.
  • Capping spend with AI Gateway budgets.
  • Monitoring provider dashboards for usage trends as adoption grows.

Plan for concurrency limits

Community licenses run up to 5 agents at once. Additional agents queue and start automatically when capacity frees. A Premium license with Agent Hours does not impose a concurrency limit unless the Agent Hours hard limit is reached. If the Agent Hours allocation is exhausted without a configured hard limit, Coder warns about usage but does not impose a concurrency limit. When the Agent Hours hard limit is reached, additional agents queue under the concurrency limit. Refer to Concurrent agents for details.

Pilot with a small group

Identify 3–5 developers and a few concrete use cases for the initial rollout. Good starting points:

  • Low-risk, high-visibility tasks — generating unit tests, writing inline documentation, small refactors.
  • Investigation and triage — exploring unfamiliar code, triaging bugs, understanding legacy systems.
  • Prototyping — building proof-of-concept implementations, simple dashboards, internal tools.

To limit Coder Agents to the pilot group, see Control who can use Coder Agents.

Set expectations for how the team reviews agent output. Developers should still review all agent-produced code before merging. The agent is a force multiplier, not a replacement for developer judgment.

Use the API for programmatic automation

The Chats API enables programmatic access to Coder Agents. This is useful for building automations such as:

  • Triggering Coder Agents from CI/CD pipelines when builds fail.
  • Creating Coder Agents from GitHub webhooks on new issues or PRs.
  • Building internal tools or dashboards on top of the API.
  • Scripting batch operations across repositories.

Quick example — create a Coder Agent via the API:

curl -X POST https://coder.example.com/api/v2/chats \
  -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {"type": "text", "text": "Fix the failing tests in the auth service"}
    ]
  }'

Stream updates in real time by connecting to the WebSocket endpoint:

GET /api/v2/chats/{chat}/stream

For service-to-service automation, use API keys rather than developer session tokens. Keep automation credentials narrowly scoped.

To send users to a new chat with a message already written, link to /agents with a prompt query parameter. URL-encode the message (for example, with encodeURIComponent in JavaScript):

https://coder.example.com/agents?prompt=Fix%20the%20failing%20tests%20in%20the%20auth%20service

The link fills in the message box only. Coder doesn't send the message: the user reviews it, can edit it, and selects Send. Because any website can create such a link, a warning in the message box asks the user to take care before sending. The warning disappears once the user edits the message.

If the user isn't signed in, Coder keeps the message through sign-in.

Don't put secrets in these links. URLs end up in browser history and server logs.

Add workspace context with AGENTS.md

Create an AGENTS.md file in the home directory (~/.coder/AGENTS.md) or the workspace agent's working directory to provide persistent context to the agent. This file is automatically read and included in the system prompt for every conversation with a Coder Agent that uses that workspace.

Use it for:

  • Repository-specific build and test instructions.
  • Important architectural decisions or constraints.
  • Links to relevant documentation or runbooks.
  • Any context that helps the agent work effectively in that codebase.

Consider prebuilt workspaces for faster startup

Workspace provisioning is the main source of latency when the agent starts a task. If your templates take more than a minute to provision, consider configuring prebuilt workspaces to maintain a pool of ready-to-use workspaces. The agent gets assigned an already-running workspace instead of provisioning from scratch.

Provide feedback

Report bugs and feature requests as GitHub issues. For deployment-specific problems, such as provider configuration or performance in your environment, use your usual Coder support channel.

Good reports include:

  • What you tried: the prompt, the template, and the model.
  • What happened: the agent's behavior, any errors, and unexpected results.
  • What you expected: the outcome you were looking for.
  • Context: screenshots, chat_id values, or links to the Agents page help the team investigate quickly.

Next steps

  • Architecture — how the control plane, LLM providers, and workspaces interact.
  • Models — configure additional providers and models.
  • Platform Controls — system prompts, template routing, and admin-level configuration.
  • Template Optimization — create agent-friendly templates with network boundaries and scoped credentials.
  • Chats API: build programmatic integrations.