Files
coder/docs/coder-agents/platform-controls/index.md
T
Sas Swart 4ac8f0a2aa docs: document how AI Gateway assigns a request's organization (#31925)
Documents how AI Gateway assigns every request to one organization, and
how that organization now decides the effective group, budget,
overrides, and spend. Adds a **Request organization** page and corrects
pages that still described budget resolution as deployment-wide.

Refs AIGOV-753. Describes behavior merged in #30902, #31118, #31119,
#31120, #31121, #31583, and #31584.

## Changes

- New page `docs/ai-governance/ai-gateway/request-organization.md`
(sidebar, after Cost control): resolution order, the effective group
fallback, rejected requests, what the organization controls, a multi-org
worked example, reports that still resolve across all orgs, and the
caveat for standalone gateways older than v2.40.
- `cost-controls.md`: removes "the effective group is deployment-wide",
scopes overrides and effective group resolution to the request's
organization, and adds the reporting caveat.
- `standalone.md`: older replicas check budgets across all
organizations.
- `coder-agents/platform-controls/{index,spend-management}.md`: these
said an override beats every group budget, which is no longer true for
chats in another organization.

## For reviewers

- **Mismatch rejection is not documented.** The ticket and RFC describe
rejecting a workspace/chat org mismatch. A chat can only bind a
workspace in its own org (`coderd/exp_chats.go`), chatd requests resolve
to the chat's org even with a workspace, and no client request can carry
both inputs. The page says the two always agree instead.
- **"v2.40" is inferred.** `release/2.39` is on aibridged API v1.5 and
`main` is on v1.6, so v1.6 ships in v2.40. A 2.39.x backport would make
this wrong.
- **Custom prices.** The price lookup reads per-org prices, but no API
or CLI can set them yet, so the page says custom prices apply in every
org. This needs an update when per-org prices ship.
- **Site-wide reports.** The avatar menu, Agents usage indicator, `GET
/api/v2/users/{user}/ai/spend`, Members tab budget, Groups page combined
limit, and `blocked_users` metric still resolve across all orgs
(`TODO(AIGOV-527)`), so they can disagree with what was enforced.

## Release note draft

```markdown
- AI Gateway budgets and spend follow the request's organization (#31119, #31120, #31121, #31583, #31584)

  > Every AI Gateway request now belongs to one organization: the workspace's organization for workspace session tokens, the chat's organization for Coder Agents, and otherwise the organization of the user's effective group. Budgets, user overrides, and spend apply within that organization only, instead of across all of the user's organizations. Users in one organization see no change. Users in several organizations can hit a smaller budget, or have no limit at all, in another organization's workspaces and chats. Requests are rejected when the user is no longer a member of the workspace's or chat's organization, or of any organization.
  >
  > Migration: Set budgets in every organization your users send AI requests from. Upgrade standalone AI Gateway replicas to v2.40. Older replicas keep checking budgets across all organizations until upgraded.
```

## Validation

`make pre-commit-light`, Vale on the changed files, and `make
lint/docs-manifest` pass. A `doc-check` author self-check found 13
blocking findings, all fixed. Not applied: a suggested test pinning the
site-wide spend endpoint (code change, out of scope for this docs PR).

<details>
<summary>Decision log and verified behavior</summary>

Sources: AIGOV-753, epic AIGOV-749 and its delivered tickets (AIGOV-712
to 716), the canceled AIGOV-717, and the RFC "AI Gateway Model RBAC and
Org-Scoping" (Phase 1).

Verified against `main` (`a3aab79775`):

| Claim | Evidence |
|---|---|
| Order: workspace session token, chat org, site-wide effective group |
`coderd/aibridgedserver/orgresolver.go` `resolveOrganization` |
| Workspace session token = `coder_workspace_owner.session_token` |
`provisionerdserver.WorkspaceSessionTokenName`, `workspaceAttribution`
(API tokens excluded) |
| Rejections return `403 unauthorized` | `coderd/aibridged/http.go`
IsAuthorized failure path |
| Rejected: deleted workspace, not a member of the workspace/chat org or
org deleted, no live org | `orgresolver.go` `ErrUnknownWorkspace`,
`ErrUnknownOrganizationMember`, `ErrNoOrganization` |
| Chat request takes chat org even with a workspace |
`enterprise/aibridged_integration_test.go` "delegated organization with
workspace" |
| With an org, only that org's groups, override, and Everyone group
count | `coderd/aibridge/budget/budget.go`, #31119 |
| Fallback with no budgets: default org, then earliest membership |
`GetUserEveryoneFallbackGroup` |
| Budget counts only spend recorded against its group |
`GetUserAISpendSince` keyed on `effective_group_id` |
| Notifications use the per-request effective group |
`coderd/aibridgedserver/notifications.go` |
| Per-org prices not settable |
`UpsertOrganizationAIProviderModelConfig` has no non-test caller |
| v2.39 gateways: site-wide budget check, no org recorded |
`release/2.39` `coderd/aibridged/http.go`,
`aibridge/recorder/drpc_recorder.go` |

Page vs. section: a dedicated explanation page, because
`cost-controls.md` is already long and RFC Phases 3 and 4 (model RBAC,
"require organization scope") will build on the same resolution rules.

</details>

---

*This PR was generated by Coder Agents on behalf of @SasSwart.*
2026-11-17 09:51:14 +02:00

15 KiB

title
title
Platform controls

Design philosophy

Coder Agents is built on a simple premise: platform teams should have full control over how agents operate, and developers should have zero configuration burden.

This means:

  • All agent configuration is admin-level. Providers, models, system prompts, and tool permissions are set by administrators from the control plane. These are not user preferences. Deployment administrators own the deployment-wide policies. Users with organization configuration access own the models and the Model Context Protocol (MCP) servers of their organization. Refer to Organization scope for the split between the 2 scopes.
  • Developers never need to configure anything by default. A developer just describes the work they want done. They do not need to pick a provider or write a system prompt. The platform team has already set all of that up. When a platform team enables user API keys for a provider, developers can optionally supply their own key, but this is an opt-in policy decision, not a requirement.
  • Enforcement, not defaults. Settings configured by administrators are enforced server-side. Developers cannot override them. A setting that a user can change is a preference, not a policy.

This is an architectural decision, not just a product choice. Because the agent loop runs in the control plane rather than inside developer workspaces, there is no local configuration for developers to modify and no agent software for them to reconfigure. The control plane is the single source of truth for how agents behave.

What platform teams control today

Providers and models

Administrators configure which large language model (LLM) providers and models are available from the Coder dashboard. This includes API keys, base URLs (for enterprise proxies or self-hosted models), and per-model parameters like context limits, thinking budgets, and reasoning effort.

Providers are deployment-wide. Models belong to an organization, so each organization has its own model list and its own default model.

Developers select from the set of models an administrator has enabled. They cannot add their own providers or access models that have not been explicitly configured.

When an administrator enables user API keys on a provider, developers can supply their own key from the Agents settings page. Refer to User API keys (BYOK) for details.

An administrator can also enable personal model overrides, which let a developer select a different model for their own chats. Coder disables personal model overrides until an administrator enables them.

Refer to Models for setup instructions. Refer to Organization scope for the organization scope and the upgrade behavior.

System prompt

Administrators can set a system prompt that applies to all agent sessions. This is useful for establishing organizational conventions: coding standards, commit message formats, preferred libraries, or repository-specific context.

This setting is available under Admin settings > AI > Coder Agents > Instructions and is only accessible to administrators. Developers can't access or interact with it.

Organization administrators can also set organization instructions that apply only to chats in their organization. Coder adds them after the deployment system prompt and never uses them in place of it. Set them in the Organization instructions section of the same page. If you have access to more than one organization, select the organization first.

Coder stores both prompts when it creates a chat, in this order:

  1. The deployment system prompt.
  2. The organization instructions, when the chat's organization has them.

A change to either prompt applies to chats created afterward. Existing chats keep the prompts they started with. Subagents receive the current prompts of their parent chat's organization when they start.

The organization instructions are exposed over the chat configuration API:

  • GET /api/v2/organizations/{organization}/chats/config/system-prompt
  • PUT /api/v2/organizations/{organization}/chats/config/system-prompt

Plan mode instructions

Administrators can add deployment-wide instructions that apply only when a chat enters plan mode. These instructions supplement the built-in planning behavior and are useful for organization-specific planning requirements such as required plan sections, approval checkpoints, or review workflows.

This setting is available under Admin settings > AI > Coder Agents > Instructions. Developers do not edit it directly.

The same value is exposed over the chat configuration API:

  • GET /api/v2/chats/config/plan-mode-instructions
  • PUT /api/v2/chats/config/plan-mode-instructions

Template routing

Platform teams control which templates are available to agents and how the agent selects them. When a developer describes a task, the agent reads template descriptions to determine which template to provision.

By writing clear template descriptions, for example, "Use this template for Python backend services in the payments repo", platform teams can guide the agent toward the correct infrastructure without requiring developers to understand template selection at all.

Administrators can also restrict which templates are available to agents at Admin settings > AI > Coder Agents > Templates. Use the switch for each template in the list. The same control is available on each individual template's settings page as Allow Coder Agents to create workspaces using this template. Templates allow agents by default. When you disable the control, the agent cannot read the template or provision workspaces from it. This is separate from what developers observe when manually creating workspaces, so you can apply stricter policies to agent-created workspaces without affecting the manual workspace experience.

The same control is available outside the dashboard. Use coder templates create --agents-allowed=false or coder templates edit --agents-allowed=false <template> for a single template. Use the search filter agents-allowed:false on GET /api/v2/templates to list the templates that block agents.

Refer to Template Optimization for best practices on writing discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use.

MCP servers

Administrators can register external MCP (Model Context Protocol) servers that provide additional tools for agent chat sessions. This includes configuring authentication, controlling which tools are exposed via allow/deny lists, and setting availability policies that determine whether a server is mandatory, opt-out, or opt-in for each chat.

Each organization has its own set of MCP servers.

Refer to MCP Servers for configuration details.

Workspace autostop fallback

Administrators can set a default autostop timer for agent-created workspaces that do not define one in their template. Template-defined autostop rules always take precedence. Active conversations extend the stop time automatically.

This setting is available under Admin settings > AI > Coder Agents > Lifecycle. The maximum configurable value is 30 days. When disabled, workspaces follow their template's autostop rules (or none, if the template does not define any).

Concurrent agents

Community and Premium licenses support up to 5 concurrently active agents. Coder doesn't limit how long those agents can run or how many tasks they complete over time. Additional agents queue until an agent session becomes available. With concurrent agents, individuals and small teams can experiment with Coder Agents at no additional cost.

Queued agents show a banner in the chat and start automatically when capacity frees. Subtasks delegated by an agent don't count toward this limit. Those subtasks run in a separate pool of up to 10 concurrent subtasks.

AI Premium licenses remove this limit and include a deployment-wide allotment of Agent Hours. Agent Hours are shared across the deployment, and agents can run concurrently 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.

Spend management

AI Gateway budgets cap each user's AI spend, including Coder Agents chats, over a monthly period. Coder sets budgets per group, and the deployment policy selects the group with the largest spend limit when a user belongs to several budgeted groups. A per-user override takes priority over the group budgets in its assigned group's organization, and a chat uses the budgets of the chat's organization.

Budgets are the only spend cap for Coder Agents chats. Chats no longer enforce a separate limit of their own, and existing native limit values are not migrated to budgets. Budget controls in the Coder UI, the group budget endpoints, and the AI spend status endpoints all require a license that includes AI Gateway.

Refer to Spend management for details.

Turn and payload limits

These deployment-wide limits apply to every chat. The defaults suit most deployments, and you can change any of them with a server flag, environment variable, or YAML key. Each value must be at least 1, and the server fails to start if a value is 0 or negative:

Limit Default Setting
Steps (model responses) per chat turn 1200 CODER_CHAT_MAX_STEPS_PER_TURN
Consecutive retries after a failed model generation 25 CODER_CHAT_MAX_GENERATION_RETRIES
Queued messages per chat 20 CODER_CHAT_MAX_QUEUED_MESSAGES_PER_CHAT
Files linked to a chat 50 CODER_CHAT_MAX_ATTACHMENTS_PER_CHAT
System prompt, organization and plan mode instructions, and custom prompt size 128 KiB CODER_CHAT_MAX_PROMPT_BYTES
Concurrent virtual desktop recording uploads per server 25 CODER_CHAT_MAX_CONCURRENT_RECORDING_UPLOADS

The concurrent agent pools described above are licensing limits, not deployment settings.

Git providers

Coder Agents leverages your existing external authentication configuration to power the in-chat diff viewer. Self-hosted GitHub Enterprise deployments require additional configuration for this feature.

See Git Providers for details.

Data retention

Administrators can configure a retention period for archived conversations. When enabled, archived conversations and orphaned files older than the retention period are automatically purged. The default is 30 days.

This setting is available under Admin settings > AI > Coder Agents > Lifecycle. Refer to Data Retention for details.

Experiments

Administrators enable experimental features using the --experiments flag on coder server (or the CODER_EXPERIMENTS environment variable). Once enabled, runtime configuration for those features is available under Admin settings > AI > Coder Agents.

See the following pages for experiment-gated features:

For chat debug logging (not experiment-gated), see Chat debug logging.

Where we are headed

The controls above cover providers, models, system prompts, templates, MCP servers, AI Gateway budgets, and data retention. We are continuing to invest in platform controls based on what feedback we get from customers deploying agents in regulated and enterprise environments.

Infrastructure-level enforcement

We believe that security-critical behaviors should not depend on the system prompt. A system prompt can instruct an agent to "always format branch names like... ," but there is no guarantee the agent will comply every time.

For controls that matter (network boundaries, git push targets, allowed hostnames), we intend to enforce them at the infrastructure and network layer. Examples of what this looks like:

  • Network-restricted templates for agent workloads. Because the AI comes from the control plane, agent workspaces do not need outbound access to LLM providers. You can create templates that only permit access to your git provider and nothing else.

Why we take this approach

The common pattern in the industry today is that each developer installs and configures their own coding agent inside their development environment. This creates several problems for platform teams:

  • No standardization. Different developers use different agents with different configurations. There is no unified way to enforce conventions or improve the experience across the organization.
  • Security is ad-hoc. If the agent runs inside the workspace, it has access to whatever the workspace has access to (API keys, network endpoints, credentials). Restricting this requires per-workspace configuration that is difficult to maintain at scale.
  • Feedback is anecdotal. Without centralized analytics, platform teams have no way to know which models perform best, which prompts cause failures, or how much agents are costing the organization.
  • Configuration is a developer burden. Developers (especially those who are not power users) should not need to think about which agent to install, which API key to use, or how to configure a system prompt. They should describe the work they want done.

As models improve and the differences between agent harnesses continue to shrink, we believe the leverage shifts toward user experience and platform-level controls: which models to offer, how to enforce security, and how to use analytics to continuously improve the development experience across the organization.