From 1ce6f0a0ceeaff6c40904ff0cb72f983eb8476ec Mon Sep 17 00:00:00 2001 From: Ethan Dickson Date: Mon, 24 Aug 2026 15:42:43 +0000 Subject: [PATCH 1/5] docs(docs/ai-coder/agents): document org-scoped agent settings Coder Agents settings now belong to an organization. Document the new scope split, the permissions that control edit access, and the new Organization settings section that holds model overrides. Add a new "Organization scope" page. Update the models, getting started, platform controls, MCP servers, advisor, architecture, and migration pages for the new scope. Correct stale breadcrumbs and API routes. --- docs/ai-coder/agents/architecture.md | 12 +- docs/ai-coder/agents/getting-started.md | 15 +- docs/ai-coder/agents/index.md | 16 +- docs/ai-coder/agents/models.md | 75 ++++---- .../agents/platform-controls/advisor.md | 10 +- .../platform-controls/chat-debug-logging.md | 2 +- .../agents/platform-controls/index.md | 61 ++++--- .../agents/platform-controls/mcp-servers.md | 18 +- .../agents/platform-controls/organizations.md | 167 ++++++++++++++++++ .../platform-controls/virtual-desktop.md | 2 +- .../agents/tasks-to-chats-migration.md | 75 ++++---- docs/manifest.json | 5 + 12 files changed, 332 insertions(+), 126 deletions(-) create mode 100644 docs/ai-coder/agents/platform-controls/organizations.md diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index 225aa8344f7..45b0083e5ce 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -290,12 +290,12 @@ plane, not from the workspace's network. ### Centralized enforcement -Administrators control which models are available, the system prompt, and tool -configuration from the control plane. Developers can select from the set of -admin-enabled models when starting or continuing a chat, but cannot add their -own providers or override system prompts or tool permissions. When an -administrator removes a model or modifies the system prompt, the change applies -to all agent sessions immediately. +Administrators control which models are available, the system prompt, and tool configuration from the control plane. +The system prompt and the tool configuration are deployment-wide. +The model list belongs to an organization, so a chat can only use the models of its own organization. +Developers can select from the set of admin-enabled models when starting or continuing a chat, but cannot add their own providers or override system prompts or tool permissions. +When an administrator removes a model or modifies the system prompt, the change applies to all affected agent sessions immediately. +Refer to [Organization scope](./platform-controls/organizations.md) for the settings that belong to each scope. ### User identity on every action diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index 080ef8936bc..0bbff832636 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -17,6 +17,7 @@ Before you begin, confirm the following: [descriptive name and description](./platform-controls/template-optimization.md) for the agent to select when provisioning workspaces. - **Admin access** to the Coder deployment for configuring providers. +- **Organization Admin** role, or the **Owner** role, in each organization where you configure models. - **Coder Agents User role** assigned to each user who needs to interact with Coder Agents. This role is granted **per organization**. Owners and organization admins can assign it from **Admin settings** > **Organizations** > _[your organization]_ > @@ -26,9 +27,9 @@ Before you begin, confirm the following: ## Step 1: Configure an LLM provider and model > [!IMPORTANT] -> Configuring providers, models, and system prompts requires the -> **Owner** role (Coder administrator). Non-admin users cannot access the -> admin Settings panel or modify deployment-level Agents configuration. +> Configuring providers and system prompts requires the **Owner** role (Coder administrator). +> Configuring models requires the **Owner** role, or the **Organization Admin** role in the organization that owns the models. +> Other users cannot open the admin settings panel or change Agents configuration. To configure Coder Agents: @@ -36,10 +37,16 @@ To configure Coder Agents: 1. Add or update a provider with its credentials and upstream endpoint, then save it. 1. Navigate to **Admin settings** > **AI** > **Models**. +1. Select the organization that owns the models. + Coder shows the organization picker when you can access more than 1 organization. 1. Click **Add** and configure at least one model with its identifier, display name, and context limit. 1. Click the **star icon** next to a model to set it as the default. +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](./platform-controls/organizations.md) for the settings that stay deployment-wide. + Detailed instructions for each provider and model option are in the [Models](./models.md) documentation. @@ -189,7 +196,7 @@ deployment. Use this to encode organizational conventions: - Required review processes before merging. - Any guardrails specific to your environment. -Configure the system prompt from **AI Settings** > **Coder Agents** > **Instructions** +Configure the system prompt from **Admin settings** > **AI** > **Coder Agents** > **Instructions** or via the API at `PUT /api/v2/chats/config/system-prompt`. See [Platform Controls](./platform-controls/index.md) for details. diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index 3ec3776242e..1b9fb27600d 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -14,9 +14,9 @@ Your browser does not support the video tag. ## What Coder Agents is and isn't -It is a standalone agent written in Go that implements standard -agentic patterns — sub-agent delegation, context compaction, file editing, and -shell execution — and works with any LLM provider you configure. +It is a standalone agent written in Go. +It implements standard agentic patterns, such as sub-agent delegation, context compaction, file editing, and shell execution. +It works with any LLM provider you configure. It is not a wrapper around third-party agent tools like Claude Code or Codex. @@ -90,6 +90,8 @@ creates a workspace automatically. Template visibility is scoped to the user's r Platform teams control template routing by writing clear template descriptions. For example, a description like "Use this template for Python backend services in the payments repo" helps the agent select the correct infrastructure. +Administrators can also block agents on a template, which hides it from the agent completely. +Refer to [Platform Controls](./platform-controls/index.md#template-routing) for that setting. **Examples of what triggers workspace creation:** @@ -166,7 +168,7 @@ entirely: else. The workspace never needs to reach the internet for AI functionality. - **Centralized, enforced control.** Platform teams configure models, system prompts, and tool permissions from the control plane. These settings are - enforced server-side — they are not user preferences that developers can + enforced server-side, so they are not user preferences that developers can override. - **User identity is always attached.** Every action the agent takes — PRs opened, code pushed, commands run — is tied to the user who submitted the @@ -217,8 +219,10 @@ and models from the Coder dashboard or API. Supported providers include: Most providers support custom base URLs, which allows integration with enterprise LLM proxies, self-hosted model endpoints, and internal gateways. -Administrators can configure multiple providers simultaneously and set a default -model. Developers select from enabled models when starting a chat. +Administrators can configure multiple providers simultaneously and set a default model in each organization. +Developers select from enabled models when starting a chat. +Providers are deployment-wide, and models belong to an organization. +Refer to [Organization scope](./platform-controls/organizations.md) for details. Screenshot of the provider/model configuration in the Agents settings diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md index 855bbedc6ab..548626ae47c 100644 --- a/docs/ai-coder/agents/models.md +++ b/docs/ai-coder/agents/models.md @@ -1,10 +1,10 @@ # Models -Administrators configure LLM providers from **Admin settings** > **AI** and -Coder Agents models from **Admin settings** > **AI** > **Models**. Providers, -models, and centrally managed credentials are deployment-wide settings managed -by platform teams. Developers select from the set of models that an administrator has -enabled. +Administrators configure LLM providers from **Admin settings** > **AI** and Coder Agents models from **Admin settings** > **AI** > **Models**. +Providers and centrally managed credentials are deployment-wide settings managed by platform teams. +Each model belongs to 1 organization, so every organization has its own model list. +Developers select from the set of models that an administrator has enabled in their organization. +Refer to [Organization scope](./platform-controls/organizations.md) for the split between deployment-wide and organization-scoped settings. Optionally, administrators can enable AI Gateway Bring Your Own Key (BYOK) so developers can supply personal API keys for providers. See @@ -43,8 +43,8 @@ add one of the supported provider types above instead. ### Add a provider -LLM providers are managed from the deployment AI settings, not from the Agents -settings page. +LLM providers are managed from the deployment AI settings, not from the Agents settings page. +A provider is deployment-wide, and the models that reference it are organization-scoped. 1. Navigate to **Admin settings** > **AI**. 1. Select **Providers**. @@ -55,8 +55,9 @@ settings page. [endpoint/base URL](#endpointbase-url-for-openai-compatible-providers). 1. Click **Save**. -After saving a provider, add an Agents model for it from **Admin settings** > -**AI** > **Models**. For provider-specific setup, including AWS Bedrock, see +After saving a provider, add an Agents model for it from **Admin settings** > **AI** > **Models**. +Select the organization that owns the new model before you add it. +For provider-specific setup, including AWS Bedrock, refer to [AI Gateway provider configuration](../ai-gateway/providers.md#provider-types). ## Endpoint/base URL for OpenAI-compatible providers @@ -102,8 +103,8 @@ on this security model. ## Credential selection -Coder Agents use the AI providers configured by administrators. Provider API -keys entered by administrators are centralized credentials for the deployment. +Coder Agents use the AI providers configured by administrators. +Provider API keys entered by administrators are centralized credentials for the deployment, and every organization's models share them. BYOK for Coder Agents is controlled by the [global AI Gateway BYOK setting](../ai-gateway/auth.md#bring-your-own-key-byok), @@ -151,6 +152,15 @@ Members with model share permission can grant model read access to members and g Coder applies the member and group changes when you save. Removing all entries clears the model's access list, so members without another read grant lose access on their next request. +### Model permissions + +Models use the `chat_model_config` RBAC resource, which supports the `create`, `read`, `update`, `delete`, and `share` actions. +Owners and organization admins hold every action. +Auditors and organization auditors hold `read`. +Other members reach a model only through its access list. +API tokens can carry the public `chat_model_config:read` and `chat_model_config:share` scopes. +Refer to [Organization scope](./platform-controls/organizations.md#permissions) for the full permission model. + ### Model visibility and runtime availability Management visibility and runtime availability are separate. @@ -159,6 +169,8 @@ A member can see a model in settings through its access list even when the model The Agents model selector includes the model only when its exact provider configuration has usable credentials for that member. Coder evaluates providers by provider UUID, so 2 providers of the same type can have different availability. An unavailable provider can remain visible with a redacted reason while its models are omitted from the selector. +The organization model response reports `available` for each provider and, when the provider is unavailable, an `unavailable_reason` of `missing_api_key`, `fetch_failed`, or `user_api_key_required`. +The same response lists `unsupported_providers`, which are configured provider types that Coder Agents cannot use. Model APIs identify each configured model with a UUID. The provider's model identifier, such as `gpt-5.3-codex`, doesn't replace this model UUID. @@ -188,9 +200,10 @@ provider. ### Set a default model -Click the **star icon** next to a model in the models list to make it the -default. The default model is pre-selected when developers start a new chat. -Only one model can be the default at a time. +Click the **star icon** next to a model in the models list to make it the default. +The default model is pre-selected when developers start a new chat in that organization. +Each organization has its own default model, and only 1 model can be the default in an organization at a time. +An organization without a default model cannot start a chat, so set a default in every organization that uses Coder Agents. ### Models with a missing or disabled provider @@ -280,15 +293,14 @@ fields appear dynamically in the admin UI when you select a provider. ## How developers select models -Developers see a model selector dropdown when starting or continuing a chat on -the Agents page. The selector shows only models from providers that have valid -credentials configured. Models are grouped by provider if multiple providers -are active. +Developers see a model selector dropdown when starting or continuing a chat on the Agents page. +The selector shows only models in the chat's organization that come from providers with valid credentials. +Models are grouped by provider if multiple providers are active. The model selector uses the following precedence to pre-select a model: 1. **Last used model**, stored in the browser's local storage. -1. **Admin-designated default**, the model marked with the star icon. +1. **Admin-designated default**, the model marked with the star icon in that organization. 1. **First available model**, if no default is set and no history exists. Developers cannot add their own providers or models. If no models are @@ -297,19 +309,20 @@ contact an administrator. ## Model overrides -Beyond the chat-level model picker, Coder Agents supports two override -layers. Both are stored per organization and resolve from the chat's -organization: +Beyond the chat-level model picker, Coder Agents supports two override layers. +Both are stored per organization and resolve from the chat's organization: + +- **Admin overrides** (per organization): Pin specific contexts to a particular model. + Configure them in the **Organization settings** section of **Admin settings** > **AI** > **Coder Agents**. + Coder shows an organization picker in that section when you can access more than 1 organization. +- **Personal overrides** (per user and organization, opt-in by admin): Let users override the model for their own root chats and delegated subagents. + Admins enable the deployment-wide toggle in the **Deployment settings** section of the same page. + Once the toggle is on, each user sees an **Agents** tab in their personal **Agents** > **Settings**. + Users in more than one organization pick which organization to configure. -- **Admin overrides** (per organization): Pin specific contexts to a - particular model. Configure them on the **Defaults & overrides** tab - under **AI Settings** > **Models** for the selected organization. -- **Personal overrides** (per user and organization, opt-in by admin): - Let users override the model for their own root chats and delegated - subagents. Admins enable the deployment-wide toggle under - **AI Settings** > **Coder Agents**; once on, each user sees an - **Agents** tab in their personal **Agents** > **Settings**. Users in - more than one organization pick which organization to configure. +The **Coder Agents** page is visible to deployment admins and to organization members with model access. +To change an organization override, you need permission to edit that organization's models. +The **Deployment settings** section is visible only to deployment admins. > [!IMPORTANT] > When a deployment upgrades from the older deployment-wide override diff --git a/docs/ai-coder/agents/platform-controls/advisor.md b/docs/ai-coder/agents/platform-controls/advisor.md index aabdaae0875..0bf9b34a454 100644 --- a/docs/ai-coder/agents/platform-controls/advisor.md +++ b/docs/ai-coder/agents/platform-controls/advisor.md @@ -30,7 +30,7 @@ after repeated failures, or risk reduction before a destructive operation. ## Configuration Once the experiment is enabled, configure the advisor's runtime limits -under **AI Settings** > **Coder Agents** > **Advisor**. These limits apply +under **Admin settings** > **AI** > **Coder Agents** > **Advisor**. These limits apply deployment-wide. | Field | Default | Notes | @@ -38,11 +38,9 @@ deployment-wide. | Max uses per turn | `0` (unlimited) | Caps how many times the root agent can call the advisor in a single chat turn. Must be a non-negative integer. | | Max output tokens | `0` (server default) | Caps the advisor model's response length. `0` uses the server default of 16,384 tokens. Must be a non-negative integer. | -The advisor model and its reasoning effort are organization-scoped -[model overrides](../models.md#model-overrides). Configure them on the -**Defaults & overrides** tab under **AI Settings** > **Models** for the -selected organization. When no override is set, the advisor reuses the -root agent's model. +The advisor model and its reasoning effort are organization-scoped [model overrides](../models.md#model-overrides). +Configure them in the **Organization settings** section of **Admin settings** > **AI** > **Coder Agents** for the selected organization. +When no override is set, the advisor reuses the root agent's model. The advisor is not available in plan mode or to subagents. Failed advisor invocations refund the per-turn budget. diff --git a/docs/ai-coder/agents/platform-controls/chat-debug-logging.md b/docs/ai-coder/agents/platform-controls/chat-debug-logging.md index a5389c3ae90..36b485e47c9 100644 --- a/docs/ai-coder/agents/platform-controls/chat-debug-logging.md +++ b/docs/ai-coder/agents/platform-controls/chat-debug-logging.md @@ -11,7 +11,7 @@ Off by default. Three layers control whether it runs for a given chat: on for every chat. The runtime admin and user toggles become read-only. 1. **Runtime admin gate.** With the deployment override unset, the *Let users record chat debug logs* toggle decides whether users can opt - in. Configure it under **AI Settings** > **Lifecycle**, or at + in. Configure it under **Admin settings** > **AI** > **Coder Agents** > **Lifecycle**, or at `GET/PUT /api/v2/chats/config/debug-logging`. 1. **Per-user toggle.** Users with the admin gate enabled can turn debug logging on for their own chats from **Agents** > **Settings** > **General** diff --git a/docs/ai-coder/agents/platform-controls/index.md b/docs/ai-coder/agents/platform-controls/index.md index 0a9237d0abc..778dc70f59a 100644 --- a/docs/ai-coder/agents/platform-controls/index.md +++ b/docs/ai-coder/agents/platform-controls/index.md @@ -8,18 +8,19 @@ burden. This means: -- **All agent configuration is admin-level.** Providers, models, system prompts, - and tool permissions are set by platform teams from the control plane. These - are not user preferences — they are deployment-wide policies. +- **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 admins own the deployment-wide policies, and organization admins own the models and MCP servers of their organization. + Refer to [Organization scope](./organizations.md) 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. + 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 may - optionally supply their own key — but this is an opt-in policy decision, not + 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. This is a deliberate - distinction — a setting that a user can change is a preference, not a policy. +- **Enforcement, not defaults.** Settings configured by administrators are enforced server-side. + Developers cannot override them, except through the personal model overrides that an administrator turns on. + 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 @@ -36,15 +37,19 @@ 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. See +supply their own key from the Agents settings page. Refer to [User API keys (BYOK)](../models.md#user-api-keys-byok) for details. -See [Models](../models.md) for setup instructions. +Refer to [Models](../models.md) for setup instructions. +Refer to [Organization scope](./organizations.md) for the permissions and the upgrade behavior. ### System prompt @@ -52,7 +57,7 @@ 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 **AI Settings** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers do not see or interact with it. +This setting is available under **Admin settings** > **AI** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers do not see or interact with it. ### Plan mode instructions @@ -61,7 +66,7 @@ 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 **AI Settings** > **Coder Agents** > **Instructions**. Developers do not edit it directly. +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: @@ -74,18 +79,22 @@ 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 +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 **Agents** > **Settings** > **Manage Agents** > **Templates**. +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