Repository navigation
docs: document org-scoped admin configuration for agents - #28482
ethanndickson merged 5 commits into
Conversation
commented
Aug 24, 2026
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.
|
53bcaa9 to
1de9483
Compare
4b50da3 to
0084b6f
Compare
left a comment
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2292147da3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Users with access to an organization's MCP servers can open the **MCP servers** | ||
| settings page. Coder enables the edit controls for the users who can manage the | ||
| selected organization's servers. |
There was a problem hiding this comment.
Restore the deployment-admin caveat for user OIDC
For an organization admin managing an organization-scoped server, this replacement suggests that the available edit controls cover every authentication method, but authorizeUserOIDCMCPServerConfig in coderd/mcp.go rejects creating a server with auth_type=user_oidc without deployment_config:update, and the update path rejects any change touching such a server with HTTP 403. The UI likewise hides that option and disables editing existing user-OIDC servers for organization-only admins. Because this page still documents User OIDC as an authentication method, retain the removed deployment-permission exception.
Useful? React with 👍 / 👎.
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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. |
| 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. | ||
|
|
||
| See [Template Optimization](./template-optimization.md) for best practices on writing |
There was a problem hiding this comment.
| See [Template Optimization](./template-optimization.md) for best practices on writing | |
| Check out [Template Optimization](./template-optimization.md) for best practices on writing |
| 1. Navigate to **AI Settings** > **Coder Agents** > **MCP servers**. | ||
| 1. Click **Add**. | ||
| 1. Navigate to **Admin settings** > **AI** > **Coder Agents** > **MCP servers**. | ||
| 1. Click **Add server**. |
There was a problem hiding this comment.
| 1. Click **Add server**. | |
| 1. Select **Add server**. |
| 1. Navigate to **Admin settings** > **AI** > **Coder Agents** > **MCP servers**. | ||
| 1. Click **Add server**. | ||
| 1. Fill in the configuration fields described below. | ||
| 1. Click **Save**. |
There was a problem hiding this comment.
| 1. Click **Save**. | |
| 1. Select **Save**. |
| 1. Every existing chat model moves to the default organization. | ||
| 1. Every existing MCP server moves to the default organization, with its credentials intact. | ||
| 1. Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access. | ||
| 1. The previous default model becomes the default model of the default organization. | ||
| 1. Coder removes the existing admin and personal model overrides. | ||
| 1. Coder ignores the previous Advisor model override, so you must set it again. | ||
| 1. The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting. |
There was a problem hiding this comment.
| 1. Every existing chat model moves to the default organization. | |
| 1. Every existing MCP server moves to the default organization, with its credentials intact. | |
| 1. Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access. | |
| 1. The previous default model becomes the default model of the default organization. | |
| 1. Coder removes the existing admin and personal model overrides. | |
| 1. Coder ignores the previous Advisor model override, so you must set it again. | |
| 1. The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting. | |
| - Every existing chat model moves to the default organization. | |
| - Every existing MCP server moves to the default organization, with its credentials intact. | |
| - Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access. | |
| - The previous default model becomes the default model of the default organization. | |
| - Coder removes the existing admin and personal model overrides. | |
| - Coder ignores the previous Advisor model override, so you must set it again. | |
| - The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting. |
Nit: suggesting an unordered list here.
|
|
||
| 1. Navigate to **Admin settings** > **AI** > **Models**. | ||
| 1. Click **Add** and select the provider for the new model. | ||
| 1. Click **Add model** and select the provider for the new model. |
There was a problem hiding this comment.
| 1. Click **Add model** and select the provider for the new model. | |
| 1. Select **Add model** and select the provider for the new model. |
| 1. Select the organization that owns the model. | ||
| 1. Open the model, or click **Add model** to create a new one. | ||
| 1. Select **Set as Coder Agents default model**. | ||
| 1. Click **Save**. |
There was a problem hiding this comment.
| 1. Click **Save**. | |
| 1. Select **Save**. |
| 1. Navigate to **Admin settings** > **AI** > **Models**, select the correct | ||
| organization, add at least one model, and set it as the default. |
There was a problem hiding this comment.
| 1. Navigate to **Admin settings** > **AI** > **Models**, select the correct | |
| organization, add at least one model, and set it as the default. | |
| 1. Navigate to **Admin settings** > **AI** > **Models**. | |
| 1. Select the correct organization. | |
| 1. Add at least one model, and set it as the default. |
| List the available models in an organization to verify at least one provider is | ||
| configured and reachable: |
There was a problem hiding this comment.
| List the available models in an organization to verify at least one provider is | |
| configured and reachable: | |
| List the available models in an organization to verify at least one provider is configured and reachable: |
| - [ ] At least one LLM model is configured in the organization and returned by | ||
| `/organizations/{organization}/chats/models` |
There was a problem hiding this comment.
| - [ ] At least one LLM model is configured in the organization and returned by | |
| `/organizations/{organization}/chats/models` | |
| - [ ] At least one LLM model is configured in the organization and returned by `/organizations/{organization}/chats/models` |
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.
…odel wording Remove implementation details from the organization scope documentation. Correct the Advisor and Virtual desktop locations to the Deployment settings section. Correct the Add model and Add server button labels. Replace the star action with the Default badge and the model form option. Document that the first model of an organization becomes its default.
08ca373 to
3a695d6
Compare
commented
Aug 25, 2026
|
Cherry-pick PR created: #28584 ( |
Summary
Documents the organization scoping of Coder Agents admin configuration, and corrects the navigation paths, access wording, and default-model instructions that no longer matched the product. Documentation only, no product code changes.
Follows #28473, which moved the organization model overrides into an Organization settings section on Admin settings > AI > Coder Agents. #28473 is merged, so this targets
main.Closes CODAGT-715
Changes
docs/ai-coder/agents/platform-controls/organizations.md, registered indocs/manifest.json. Covers the deployment/organization scope split, what an upgrade changes, how an organization without models or MCP servers behaves, who configures each scope, and how model and MCP server sharing works.models.md: models are organization-scoped while providers and their credentials stay deployment-wide. Each organization has one default model, and the first model added becomes it. Documents the Default badge and the Set as Coder Agents default model form option in place of the star action that no longer exists, and points model overrides at Organization settings.getting-started.md: replaces the Owner-only claim with the actual access model, adds an organization selection step, and uses the Add model label.platform-controls/index.md: separates deployment-wide controls from organization-scoped controls, documents personal model overrides alongside the model configuration section rather than as an enforcement caveat, and adds--agents-allowedplus theagents-allowed:search filter.platform-controls/advisor.mdandplatform-controls/virtual-desktop.md: the Advisor and Virtual desktop settings are cards in the Deployment settings section of the Coder Agents page, not sidebar entries. Providers is a sidebar item, not a tab.platform-controls/mcp-servers.md: slug uniqueness is per organization, the Add server label is correct, and the page is no longer described as admin-only.architecture.md,index.md,tasks-to-chats-migration.md: organization scope corrections and organization-scoped model routes.AdminSettings.tsxandAISettingsSidebarView.tsx.Review follow-ups
The first revision leaked implementation detail into user-facing pages and contained several claims that did not match the UI. The follow-up commit removed and corrected the following.
Removed as implementation detail:
chat_model_configRBAC resource, its actions, and the token scopes.available,unavailable_reason, andunsupported_providersresponse fields, along with themissing_api_key,fetch_failed, anduser_api_key_requiredvalues.Corrected against the product:
ModelRow.tsx,ModelFormFields.tsx).coderd/exp_chats.go). An organization without a stored default does not fail every chat, so that claim is gone.CoderAgentsPageView.tsx).AISettingsSidebarView.tsx).org, confirmed bymodelOrganizationSearchParam.Left alone deliberately: pre-existing defects outside the introduced text, including the
/api/v2/chatsroute prefixes, create-chat examples missingorganization_id, and the pre-existing MCP permissions table.Testing
pnpm run format-docsandpnpm run lint-docspass.make lint/emdashpasses. No emdash or endash added.grep -rn "Defaults & overrides" docs/returns nothing.site/src/pages/AISettingsPage/andsite/src/modules/management/.This pull request was generated by Coder Agents on behalf of @ethanndickson.