Files
Nick VigilanteandBen Potter 1baff57cb0 fix: resolve docs and code conflicts found in the main docs audit (#32158)
## Summary

Addresses 106 of the 113 conflicts between the docs and the code that
the November audit of `main` found: 102 are fixed and 4 have an interim
docs fix. Every finding was re-checked against the code before it was
fixed. Most fixes are docs-only. Three are small code fixes where the
docs described the intended behavior and the code was wrong, each in its
own commits so it can be split out. No change in this PR alters template
build or agent behavior.

## Changes

Fixes by area (finding counts): templates 28, install 13, integrations
and monitoring 13, auth and security 12, networking 11, Coder Agents 9,
AI governance 7, reference 7, workspaces 6.

Code fixes. Each needs a look from the code owner. If an owner prefers
not to take one, drop its commits and I will change the docs to describe
the current behavior instead.

| Commits | Change | Risk to check |
|---------|--------|---------------|
| `fix: keep built-in listener defaults in packaged coder.env`, and
three follow-up commits | `coder.env` comments out `CODER_HTTP_ADDRESS=`
and the three `CODER_TLS_*` lines, so an untouched package install
listens on `127.0.0.1:3000` as the docs say. Only the
`CODER_HTTP_ADDRESS=` line changed behavior. The TLS options default to
empty, so commenting them out is for consistency. The Lima examples
rewrite the commented line and fail if the line is not found. A test
compares every option that the file sets against the built-in defaults.
| The deb and RPM packages were not built or installed. Every released
package through v2.39.0 ships the empty line, and upgrades keep an
existing file (`config\|noreplace`), so the upgrade pages now say how to
fix it. |
| `fix(cli/clilog): accept log sinks that are all disabled`, and three
follow-up commits | `--log-human=/dev/null` with no other log location
no longer fails with "no loggers provided". It is the documented way to
disable logging. An empty location still fails with that error when no
other sink is set, as before. | Behavior change: with `/dev/null`, the
server and the provisioner daemon can start with no log output. |
| `fix(cli): detect CODER_PROC_PRIO_MGMT by presence`, and a comment
follow-up | Log line only. With the variable set to an empty value, the
agent now logs that process priority management is enabled, which is
what `agentexec` already does. No detection or behavior change. | Low. |

Two option descriptions in `codersdk/deployment.go` are corrected, with
the CLI reference, configuration reference, and golden files
regenerated: the default quiet hours schedule (the max deadline is the
quiet hours window on the next day that the template's autostop
requirement applies) and `--experiments` (`*` opts in to the experiments
marked safe, also in `enterprise/cli/provisionerdaemonstart.go`).

### Code fixes that were reverted after review

Two code fixes from the first version of this PR are reverted in the
branch. The net diff has no change under `agent/` or `coderd/`. The docs
now describe what the code does, and both issues stay open for the
owner.

- **`error` merge strategy for `coder_env` (DOCS-1669).** The fix made
`merge_strategy = "error"` fail whenever a name was set twice, whatever
the resource order. Existing template versions that pair an `error`
entry with a later `replace` or `append` entry would start to fail every
build after `terraform apply`. That is a breaking change that needs its
own PR and release note. The fix and its tests are in `dff8e7c6ce` and
can be cherry-picked. `environment-variables.md` now says the check runs
only when the `error` resource is processed.
- **Nice value before the capability drop (DOCS-1687).** The fix let
`coder agent-exec` apply a negative nice value by calling `setpriority`
before it drops effective capabilities. The current order is deliberate:
with the fix, any local process could run the agent binary with
`--coder-nice=-20` when the binary has the `CAP_SYS_NICE` file
capability. `process-priority.md` now says a nice value below the
agent's own is not applied, and no longer tells admins to grant
`CAP_SYS_NICE`.

## Not included

Seven findings are left out.

- DOCS-1629: covered by #31639.
- DOCS-1703 and DOCS-1724: covered by #31980.
- DOCS-1584, DOCS-1683, DOCS-1685, DOCS-1686: each needs an owner
decision, and no neutral docs wording exists until that decision is
made. The validation comment on each issue names the decision.

Four fixes are interim, so their issues stay open:

- DOCS-1600: the AI Gateway pages now agree that the legacy metric names
are deprecated and "will be removed in a future release". The code still
emits them, and its TODO names v2.37, which has shipped. The owner still
needs to set the removal release.
- DOCS-1689: the page now says **New Template** opens the builder only
for users with the Owner role, because the page gates on read access to
the deployment config. Whether Template Admins should get the builder is
still open.
- DOCS-1669 and DOCS-1687: docs-only for now. Refer to [Code fixes that
were reverted after
review](#code-fixes-that-were-reverted-after-review).

## Review notes

- Claims that describe product intent and need an owner's yes: the
Premium qualifier on per-organization workspace sharing (the API route
has no license check, the dashboard needs multiple organizations),
`organization` port sharing in OSS, the telemetry field list, and the
`1-5` cron range in the prebuilds schedule example.
- Not run end to end: the PostgreSQL TLS procedure on a cluster, the
OpenShift and air-gapped examples, the BSD `date` and `tar` forms on
macOS, the Windows command on the multiple Kubernetes clusters page, and
the keep-alive script in `docs/reference/index.md` (only its comparison
logic was run, against sample values). Nothing was checked on a live
deployment.
- Likely merge conflicts with open PRs: #31990 (`mcp-server.md`,
`feature-stages.md`, `docker-in-workspaces.md`), #31982
(`workspace-management.md`), #31980 (`health-check.md`), #31977
(`manage-provisioner-jobs.md`), #31869 (`airgap.md`), #30486
(`add-envbuilder.md`), and #31326 and #31531 (`codersdk/deployment.go`
and generated files).

## Testing

- `make pre-commit` (gen, fmt, lint, slim build), before the PR opened
and again after the review changes.
- `go test` for `./cli/clilog/...`, `./codersdk/`, `./cli/`
(`TestServer`, `TestAgent`, and golden files), and `./enterprise/cli/`
(provisioner, server, and help golden files). `./agent/agentexec/...`
and `./coderd/provisionerdserver/...` pass after the reverts. Linux
only. CI covers macOS and Windows.
- The `coder.env` test fails against the file on `main` and passes
against the new one. It reads the file with `godotenv`, which accepts
CRLF line endings.
- An empty `CODER_HTTP_ADDRESS=` was confirmed end to end with a full
build of the server (output below).
- The new `sed` and `grep` lines in the Lima examples were run with GNU
tools against the old and the new form of `coder.env`. The Lima VMs were
not started.
- `--log-human=/dev/null` and `CODER_LOGGING_HUMAN=` were confirmed with
the same build (output below).
- `coder agent-exec --coder-nice=-5 -- echo` from a full build, as a
non-root user: `coder-agent: failed to adjust niceness to -5 ...:
permission denied` on stderr, the command output on stdout, exit code 0.
- `postgres-ssl.md` rendered with the GitHub Markdown API: two ordered
lists with three and five items, where `main` has six lists.
- markdownlint, the table formatter, `make lint/emdash`, `make
lint/docs-html`, `make lint/docs-manifest`, `make lint/docs-redirects`,
`make lint/style-claims`, and Vale on the changed lines.
- A doc-check self-review of the docs diff by four independent
reviewers. It found six problems, which are fixed. The accuracy and
coverage lenses ran on every area. The language and structure lenses ran
in full on only part of the diff.

<details>
<summary>Test and terminal output for the code fixes (Linux)</summary>

```console
$ go test ./codersdk/ -run TestPackagedCoderEnvKeepsDefaults -count=1 -v
--- PASS: TestPackagedCoderEnvKeepsDefaults (0.00s)
ok  	github.com/coder/coder/v2/codersdk	0.071s

$ go test ./cli/clilog/ -run TestBuilder -count=1 -v
--- PASS: TestBuilder (0.00s)
    --- PASS: TestBuilder/NoSinks (0.00s)
        --- PASS: TestBuilder/NoSinks/JSONDevNull (0.00s)
        --- PASS: TestBuilder/NoSinks/StackdriverDevNull (0.00s)
        --- PASS: TestBuilder/NoSinks/NoConfiguration (0.00s)
        --- PASS: TestBuilder/NoSinks/HumanDevNull (0.00s)
    --- PASS: TestBuilder/WithHuman (0.00s)
    --- PASS: TestBuilder/WithFilter (0.00s)
    --- PASS: TestBuilder/WithJSON (0.00s)
    --- PASS: TestBuilder/Verbose (0.00s)
    --- PASS: TestBuilder/FromDeploymentValues (0.01s)
        --- PASS: TestBuilder/FromDeploymentValues/Defaults (0.00s)
        --- PASS: TestBuilder/FromDeploymentValues/EmptyHumanEnv (0.00s)
        --- PASS: TestBuilder/FromDeploymentValues/Override (0.00s)
ok  	github.com/coder/coder/v2/cli/clilog	0.171s

$ TMPDIR=$HOME/.cache/agentexec-tmp go test ./agent/agentexec/... ./coderd/provisionerdserver/... -count=1
ok  	github.com/coder/coder/v2/agent/agentexec	4.236s
ok  	github.com/coder/coder/v2/coderd/provisionerdserver	2.404s

# Full build of the server (go build ./cmd/coder). An empty value stops it before it connects to the database.
$ CODER_HTTP_ADDRESS= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable'
Encountered an error running "coder server", see "coder server --help" for more information
error: TLS is disabled. Enable with --tls-enable or specify a HTTP address

# With the variable unset, the server passes that check and goes on to the database.
$ coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable'
2026-11-13 02:19:41.901 [warn]  ping postgres: retrying  error="dial tcp 127.0.0.1:1: connect: connection refused"  try=11
Encountered an error running "coder server", see "coder server --help" for more information
error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused

# An empty log location with no other sink still stops the server.
$ CODER_LOGGING_HUMAN= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable'
Encountered an error running "coder server", see "coder server --help" for more information
error: make logger: no loggers provided, use /dev/null to disable logging

# /dev/null passes the logger check. The server prints no log lines and goes on to the database.
$ coder server --log-human=/dev/null --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable'
Encountered an error running "coder server", see "coder server --help" for more information
error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused
```

</details>

## Linear

Fixes DOCS-1583, DOCS-1585, DOCS-1586, DOCS-1587, DOCS-1588, DOCS-1589,
DOCS-1590, DOCS-1591, DOCS-1592, DOCS-1593, DOCS-1594, DOCS-1595,
DOCS-1596, DOCS-1597, DOCS-1598, DOCS-1599, DOCS-1601, DOCS-1602,
DOCS-1603, DOCS-1604, DOCS-1605, DOCS-1606, DOCS-1607, DOCS-1608,
DOCS-1609, DOCS-1614, DOCS-1618, DOCS-1619, DOCS-1620, DOCS-1624,
DOCS-1635, DOCS-1639, DOCS-1644, DOCS-1651, DOCS-1652, DOCS-1653,
DOCS-1654, DOCS-1655, DOCS-1656, DOCS-1657, DOCS-1658, DOCS-1659,
DOCS-1660, DOCS-1661, DOCS-1662, DOCS-1663, DOCS-1664, DOCS-1665,
DOCS-1666, DOCS-1667, DOCS-1668, DOCS-1670, DOCS-1671, DOCS-1672,
DOCS-1673, DOCS-1674, DOCS-1675, DOCS-1676, DOCS-1677, DOCS-1678,
DOCS-1679, DOCS-1680, DOCS-1681, DOCS-1682, DOCS-1684, DOCS-1688,
DOCS-1690, DOCS-1691, DOCS-1692, DOCS-1693, DOCS-1694, DOCS-1695,
DOCS-1696, DOCS-1697, DOCS-1698, DOCS-1699, DOCS-1700, DOCS-1701,
DOCS-1702, DOCS-1704, DOCS-1705, DOCS-1706, DOCS-1707, DOCS-1708,
DOCS-1709, DOCS-1710, DOCS-1711, DOCS-1712, DOCS-1713, DOCS-1714,
DOCS-1715, DOCS-1716, DOCS-1717, DOCS-1718, DOCS-1719, DOCS-1720,
DOCS-1721, DOCS-1722, DOCS-1723, DOCS-1725, DOCS-1726, DOCS-1727

Part of DOCS-1600, DOCS-1689, DOCS-1669, DOCS-1687

<details>
<summary>Decision log</summary>

### Scope

- One PR for all findings, as agreed with the reviewer. The code fixes
are separate commits so an owner can ask for any of them to move to its
own PR. Nothing in the PR is a breaking change, so the title has no `!`.
- A finding was skipped only when an open PR already covers it, or when
every available wording would assert an undecided product behavior.
- Each validation comment on the Linear issues records the evidence, the
corrections to the original finding, and what was not verified.

### Docs or code

- The default was a docs-only fix that describes what the code does.
- A code fix was chosen when the docs describe a behavior the code
plainly intended and the code change is small and testable: the packaged
env file, the log sink check, and the log line for the environment
variable presence check.
- The `error` merge strategy and the nice value ordering started as code
fixes and went back to docs-only after review. The first breaks existing
template versions. The second weakens a deliberate security ordering.
- The SCIM `userName` finding (DOCS-1609) took the docs path. The
handler is unchanged.

### Wording choices worth a second look

- `feature-stages.md` says `--experiments=*` enables only the
experiments marked safe, and points to the "Get safe experiments" API.
It does not list the other experiments, because the list would drift and
those experiments are hidden on purpose. The `--experiments` flag help
now says the same.
- `agent-metadata.md` replaces the writes-per-second formula with a
description of the batcher (each server replica writes one statement
every 5 seconds, or sooner at 500 entries).
- `extending-templates/index.md` no longer calls `startup_script`
deprecated. The provider documents it as an alias for a `coder_script`.
- `postgres-ssl.md` separates client verification from server
verification, so the server verification steps work alone.
- `rpm.md`, `upgrade.md`, and the 2.29 to 2.34 ESR upgrade page explain
the empty `CODER_HTTP_ADDRESS=` line that older packages shipped,
because upgrades keep the old file. The behavior changed in v2.34.0 with
the serpent upgrade in #24926.
- The keep-alive script in `docs/reference/index.md` reads the current
deadline and skips the request when it is already later. The comparison
is on text, so it applies only when the API returns a UTC timestamp,
which needs the database to use the UTC time zone. Otherwise the script
sets the deadline on every pass, as it did before, and the page says so.
- `external-auth.md` anchors the new GitHub Enterprise regex example.
The older unanchored examples on that page and on `git-providers.md` are
not changed here.

### Self-review findings that were rejected

- "The builder opens for Template Admins": the Templates page needs a
successful deployment config read, which the Template Admin role does
not have.
- "Organization Admins can set AI model prices": the price write
authorizes against a site-level object, which organization-scoped grants
do not match.
- "The provisioner chart sets no default resources":
`helm/libcoder/templates/_coder.yaml` applies 2000m and 4096Mi when
`coder.resources` is empty.

### Automated review, round 1

The `coder-agents-review` app left 45 findings on `8853332`. Fixed: the
two reverts above, the anchored regex, the `coder.env` follow-ups (Lima
examples, upgrade notes, a comment in the file, and a test that covers
every option in the file), the clilog change, the two option
descriptions, and the docs findings (CORS behavior, token lifetime
example, keep-alive script, agent metadata, refresh token errors,
`switch` form type, `dbcrypt` skip list, and a stray line in a YAML
example).

Declined, with the reason on each thread:

- Refactoring the `agentexec` logging and renaming its log field: not
related to a docs conflict.
- Rewording the "process priority management not enabled (linux-only)"
log message: the docs quote the message, and the wording predates this
PR.
- Problems in code and docs that this PR does not change (the
`Capabilities` subtest, the Helm values comment, the AWS provider path
in `airgap.md`, and others in the review's out-of-scope list).

### Automated review, round 2

The app left 14 new findings on `04925bd`, and accepted the three
declined threads on `cli/agent.go`. All 14 are fixed. The main one: the
round 1 change that removed the "no loggers provided" error went too
far, because an empty log location would then start a server with no
logs. The error is back for every case except `/dev/null`.

Reported by the app as out of scope and not changed: the swagger
annotation for `GET /api/v2/experiments/available` declares an array,
but the handler returns an object with a `safe` array. Three Storybook
fixtures keep the old `--experiments` description.

### Automated review, round 3

The app confirmed that all round 2 findings are fixed, and left 10 small
findings on `f55cb6d` (8 P4, 2 Nit). All are fixed: the TLS condition
and the release range in the `coder.env` notes, one place for the
`/dev/null` rule in `clilog`, two test cases, a clearer test failure,
and the CPU example in `agent-metadata.md`.

### Automated review, rounds 4 and 5

Round 4 left one P4 on `8fffb38` (name the `--trace` option in the
logging note), which is fixed. Round 5 on `2ce754e` reports no new
findings and says every earlier finding is fixed or closed. The app did
not post an approval: it leaves its out-of-scope items and the code
fixes to a human reviewer. Two threads on `cli/agent.go` stay open on
purpose for the code owner.

### Doc-check review

The doc-check workflow left 12 comments on `2ce754e` (10 blocking, 2
suggestions). All are fixed in `c888885`: "refer to" or "visit" in place
of "see" for cross-references on the lines this PR added, the **New
template** label as the dashboard shows it, one instruction per step in
the server verification procedure of `postgres-ssl.md`, and two wording
changes in `process-priority.md`. The `CAP_SYS_NICE` sentence keeps a
short reason, which differs from the suggested text.

The `coder-agents-review` app then reviewed that commit (rounds 6 and
7). Round 6 left two P4 findings, fixed in `30b2c79`: the `failed to
adjust niceness` message is described once, in the troubleshooting
entry, with where it appears, and the client verification steps in
`postgres-ssl.md` render as one numbered list. Round 7 reports no new
findings. `2a6035c` then softens one sentence from that fix, because the
agent logs the stderr of devcontainer CLI commands. The app was not run
again on that commit.

### Adjacent gaps found and not fixed here

- `add-envbuilder.md` has the same `zip` command that
`template-from-scratch.md` had.
- `template-from-scratch.md` leaves the reader in `build/` after `cd
$_`, before a step that runs from `template-tour`.

</details>

---

_Generated by Coder Agents on behalf of @nickvigilante._

---------

Co-authored-by: Ben Potter <me@bpmct.net>
2026-11-13 21:34:59 +00:00

27 KiB

title
title
Models

Administrators configure large language model (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 an organization. Each 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 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 User API keys below.

Providers

Each LLM provider has a type, credentials, and an endpoint/base URL for the upstream provider or proxy.

Coder supports the following provider types:

Provider Description
Anthropic Claude models via Anthropic API
OpenAI GPT and o-series models via OpenAI API
Google Gemini models via Google AI API
Azure OpenAI OpenAI models hosted on Azure
AWS Bedrock Models via AWS Bedrock
OpenAI Compatible Any endpoint implementing the OpenAI API
OpenRouter Multi-model routing via OpenRouter
Vercel AI Gateway Models via Vercel AI SDK

The OpenAI Compatible type is a catch-all for any service that exposes an OpenAI-compatible chat completions endpoint. Use it to connect to self-hosted models, internal gateways, or third-party proxies like LiteLLM.

Coder Agents route model requests through AI Gateway automatically by using the provider configuration stored in Coder's database.

Some provider types work as AI Gateway proxy targets but cannot back Coder Agents. GitHub Copilot, for example, authenticates with a per-request token that only an official Copilot client can mint, so the server-side Agents harness cannot use it. Configuring such a provider does not unlock Agents. 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. A provider is deployment-wide, while the models that reference it are organization-scoped.

  1. Navigate to Admin settings > AI.
  2. Select Providers.
  3. Select Add provider.
  4. Select the provider type.
  5. Enter a unique lowercase provider name, the credentials, and the upstream provider or proxy endpoint/base URL.
  6. Select Save.

After saving a provider, add an Agents model for it from Admin settings > AI > Models. Select the organization that should own the new model before you add it. For provider-specific setup, including AWS Bedrock, refer to AI Gateway provider configuration.

Endpoint/base URL for OpenAI-compatible providers

Provider configuration stores an absolute HTTP(S) endpoint/base URL. Syntax validation confirms that the value is a URL, but it does not prove the upstream implements the APIs Coder sends.

For the default Agents path through AI Gateway, set the endpoint/base URL to the upstream provider or proxy endpoint. Do not set it to Coder's public AI Gateway route, such as https://<coder-host>/api/v2/ai-gateway/openai/v1.

OpenAI-shaped provider types require the upstream OpenAI-compatible prefix in the endpoint/base URL because Coder appends request suffixes such as /chat/completions, /responses, and /models. This applies to OpenAI, Azure OpenAI, Google, OpenAI Compatible, OpenRouter, and Vercel AI Gateway provider types.

Examples:

Provider type Example endpoint/base URL
OpenAI https://api.openai.com/v1/
Azure OpenAI https://<resource-name>.openai.azure.com/openai/v1
Google Gemini OpenAI-compatible API https://generativelanguage.googleapis.com/v1beta/openai/
OpenRouter https://openrouter.ai/api/v1
Vercel AI Gateway https://ai-gateway.vercel.sh/v1
Generic OpenAI-compatible proxy https://provider.example.com/v1

Confirm the exact endpoint/base URL in your provider or proxy documentation.

Provider credentials and security

Provider API keys entered in the dashboard are stored encrypted in the Coder database. They are never exposed to workspaces, developers, or the browser after initial entry. The dashboard shows only whether a key is set, not the key itself.

Because the agent loop runs in the control plane, workspaces never need direct access to LLM providers. See Architecture for details 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.

BYOK for Coder Agents is controlled by the global AI Gateway BYOK setting, not by per-provider key policy flags. When BYOK is enabled, users can save a personal API key for any enabled AI provider. When BYOK is disabled, saved user keys are ignored and users cannot add or update personal keys.

For AWS Bedrock providers, the personal key is an AWS Bedrock API key. AI Gateway forwards it as a bearer token, which authenticates that user's requests instead of the deployment-managed AWS credentials (SigV4). This applies to every model family Bedrock serves, including Anthropic and OpenAI models.

For each provider request, Coder selects credentials in this order:

  1. If BYOK is enabled and the user saved a personal key for the provider, Coder uses it.
  2. Otherwise, Coder uses centralized provider credentials when they are configured.
  3. If neither a usable user key nor centralized credentials exist, the provider is unavailable for that user.

Models

Each model belongs to a provider and has its own configuration for context limits, generation parameters, and provider-specific options.

Select an organization

Model settings use the stable path /ai/settings/models and the org query parameter to select an organization. For example, /ai/settings/models?org=engineering opens the models that you can read in the engineering organization.

If the requested organization isn't accessible, Coder selects your accessible default organization or your first accessible organization. Coder shows the organization picker when you can access more than 1 organization.

Members with model read access can open the model list and model details. Coder shows model fields as read-only unless the member also has update permission. Create, update, delete, and share permissions control their corresponding actions independently.

Manage model permissions

Members with model share permission can let members and groups in the selected organization use the model.

Model access lists control which models a member can use in Coder Agents. Chat permissions come from the Coder Agents User role, which every member except service accounts holds by default. See Control who can use Coder Agents. A member without read access to at least one model in the organization can't use the feature. New models grant read access to the whole organization by default.

  1. Navigate to Admin settings > AI > Models.
  2. Select the organization that owns the model.
  3. Select the model.
  4. Open Model actions and select Manage permissions.
  5. Add or remove organization members and groups.
  6. Select Save permissions.

Coder applies the member and group changes when you save. Removing all entries clears the model's access list, so members without another access grant cannot use the model on their next request.

Model visibility and runtime availability

Management visibility and runtime availability are separate. A member can see a model in settings through its access list even when the model isn't available for chat.

The Agents model selector includes the model only when its exact provider configuration has usable credentials for that member. Coder evaluates providers by provider universally unique identifier (UUID), so 2 providers of the same type can have different availability. An unavailable provider can remain visible while its models are omitted from the selector.

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.

Migrate model API clients

Model collection APIs require an organization name or ID in the path. Update clients that use the removed default-organization routes as follows:

Removed route Replacement Response change
GET /api/experimental/chats/models GET /api/v2/organizations/{organization}/chats/models The response remains an OrganizationChatModelsResponse.
GET /api/experimental/chats/model-configs GET /api/v2/organizations/{organization}/chats/models The response changes from a ChatModel array to an OrganizationChatModelsResponse. Read configured models from models.
POST /api/experimental/chats/model-configs POST /api/v2/organizations/{organization}/chats/models The request and ChatModel response shapes remain the same.

Replace {organization} with the organization name or ID that owns the models. The collection response also includes provider descriptors and unsupported provider details.

Add a model

  1. Navigate to Admin settings > AI > Models.
  2. Select Add model and select the provider for the new model.
  3. Enter the Model Identifier, the exact model string your provider expects (for example, claude-opus-4-6, gpt-5.3-codex).
  4. Set a Display Name so developers see a human-readable label in the model selector.
  5. Set the Context Limit, the maximum number of tokens in the model's context window (for example, 200000 for Claude Sonnet).
  6. Configure any provider-specific options (see below).
  7. Select Save.
Screenshot of the models list in the Agents settings

The models list shows all configured models grouped by provider.

Screenshot of the add model form

Adding a model requires a model identifier, display name, and context limit. Provider-specific options appear dynamically based on the selected provider.

Set a default model

Each organization has one default model. The first model that you add to an organization becomes that organization's default model. The models list marks the current default with a Default badge. The default model is pre-selected when developers start a new chat in the organization.

To change the default model from the Models page:

  1. Navigate to Admin settings > AI > Models.
  2. Select the organization that owns the model.
  3. Open the model, or select Add model to create a new one.
  4. Select Set as Coder Agents default model.
  5. Select Save.

To change it from the Coder Agents page, navigate to Admin settings > AI > Coder Agents, pick a model in the Default model row of Organization settings, and select Save. If the current default is disabled or its provider is unavailable, the row shows a warning and still lets you pick another model.

Models with a missing or disabled provider

The Models list reflects whether each model can actually be used:

  • When a model's connected provider has been deleted, the Provider column shows Unset.
  • When a model's provider is missing or disabled, an Unavailable badge appears beside the model name. The badge's tooltip explains whether the provider was deleted or disabled. Such a model cannot serve chat requests.
  • When a model is disabled, a Disabled badge appears beside the model name.

To reconnect a model to a working provider, open the model from the list, pick a new provider from the Provider dropdown, and select Save. The Save button is enabled as soon as the selected provider differs from the model's current provider, even if no other field is edited.

Model options

Every model has a set of general options and provider-specific options. The admin UI generates these fields automatically from the provider's configuration schema, so the available options always match the provider type.

General options

These options apply to all providers:

Option Description
Model Identifier The API model string sent to the provider (e.g., claude-opus-4-6).
Display Name The label shown to developers in the model selector.
Context Limit Maximum tokens in the context window. Used to determine when context compaction triggers.
Compression Threshold Percentage (0-100) of context usage at which the agent compresses older messages into a summary.
Max Output Tokens Maximum tokens generated per model response.
Temperature Controls randomness. Lower values produce more deterministic output.
Top P Nucleus sampling threshold.
Top K Limits token selection to the top K candidates.
Presence Penalty Penalizes tokens that have already appeared in the conversation.
Frequency Penalty Penalizes tokens proportional to how often they have appeared.

Each model has two reasoning effort settings. Default Reasoning Effort applies when the user has not selected a level. Max Reasoning Effort is the highest level a user can select. Both accept none, minimal, low, medium, high, xhigh, or max.

Provider-specific options

Each provider type exposes additional options relevant to its models. These fields appear dynamically in the admin UI when you select a provider.

Anthropic

Option Description
Thinking Budget Tokens Maximum tokens allocated for extended thinking.
1M Context Window Sends the anthropic-beta: context-1m-2025-08-07 header to unlock the 1M token context window on supported Claude models. Pair it with a raised Context Limit, which still controls compaction. Long-context pricing can apply.

OpenAI

Option Description
Max Completion Tokens Cap on completion tokens for Chat Completions requests.
Parallel Tool Calls Whether the model can call multiple tools at once.
Reasoning Mode Set to pro to use OpenAI's Pro reasoning mode. Supported from the GPT-5.6 Sol generation; requests fail on models that do not support it. Pro increases model work, latency, and token usage. It requires the Responses API and a reasoning model, so it is rejected when the Use Responses API or Reasoning Model override is set to Off.

Google

Option Description
Thinking Budget Maximum tokens for the model's internal reasoning.
Include Thoughts Whether to include thinking traces in the response.

OpenRouter

Option Description
Reasoning Enabled Enable extended reasoning mode.

Vercel AI Gateway

Option Description
Reasoning Enabled Enable extended reasoning mode.

Note

Azure OpenAI uses the same options as OpenAI except Reasoning Mode. AWS Bedrock uses the same model configuration options as Anthropic (thinking budget).

Prompt caching

Coder Agents adds Anthropic prompt cache breakpoints automatically. There's nothing to configure. Claude models receive them on the Anthropic and AWS Bedrock providers. They also receive them on OpenRouter, Vercel AI Gateway, and OpenAI Compatible providers when the model identifier is Anthropic-family, for example anthropic/claude-haiku-4.5 or claude-sonnet-4-5. Cached tokens are reported as cache_read_tokens in each assistant message's usage and as cache-read input tokens in AI Gateway session usage, where they're priced at the model's cache-read rate.

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 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.
  2. Organization default, the model marked with the Default badge.
  3. First available model, if no default is set and no history exists.

Developers cannot add their own providers or models. If no models are configured, the chat interface displays a message directing developers to 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:

  • 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.

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 storage, existing admin and personal overrides are deleted rather than migrated. Admins and users must re-select their override models in settings after the upgrade.

The configurable contexts:

Context Layer Applies to
General Admin + user Write-capable subagents (spawn_agent with type=general).
Explore Admin + user Read-only subagents (spawn_agent with type=explore).
Title generation Admin only Chat titles, turn status labels, and chat summaries.
Compaction Admin only Conversation summarization near the context limit.
Advisor Admin only The advisor.
Computer use Admin only Computer use subagents (spawn_agent with type=computer_use). Requires the chat-virtual-desktop experiment.
Root User only The user's own root chats.

Resolution order, evaluated per chat or subagent from the chat's organization:

  1. Explicit model_config_id on the spawn_agent tool call (general and explore subagents only).
  2. Personal override (when the admin gate is on and a model is set).
  3. Admin override.
  4. The chat's selected model (or the organization default for new chats).

If a referenced model is later disabled or deleted, that layer is skipped and resolution falls through to the next, with two exceptions: an unusable explicit spawn_agent model_config_id fails the tool call, and an unusable title generation override skips titles, status labels, and summaries instead of falling back. Agents discover selectable models (and their reasoning effort ranges) with the list_subagent_models tool, which only returns enabled models usable with the chat owner's credentials. Computer use subagents reject explicit model selection and skip the chat's selected model: they run on the Computer use admin override, or on the organization default model when no override is set or the override model is unavailable.

Note

Both override layers might change between releases. Admin overrides are available through the API at /api/v2/organizations/{organization}/chats/model-overrides and personal overrides at /api/v2/organizations/{organization}/members/{user}/chats/model-overrides.

User API keys (BYOK)

When AI Gateway BYOK is enabled, developers can supply personal API keys for any enabled AI provider from the Agents settings page.

Manage personal API keys

  1. Navigate to the Agents page in the Coder dashboard.
  2. Open Settings and select the API Keys tab.
  3. Each enabled provider is listed with a status indicator:
    • Key saved, your personal key is active and will be used for requests to that provider.
    • Shared key, no personal key is set and Coder is using deployment-managed credentials for that provider.
    • No key, no personal key or deployment-managed credential is available. Add a personal key before you use models from this provider.
  4. Enter your API key and select Save.

Personal API keys are encrypted at rest using the same database encryption used for deployment-managed provider secrets. The dashboard never displays a saved key, only whether one is set.

Remove a personal key

Select Remove on the provider card in the API Keys settings tab. Subsequent requests use deployment-managed credentials when they are configured for that provider. If no deployment-managed credential is available, add a new personal key before you use models from that provider.

Use an LLM proxy

Organizations that route LLM traffic through a centralized proxy, such as LiteLLM or an internal gateway, can point a provider's Endpoint or Base URL at that upstream proxy endpoint. Enter the API key your proxy expects.

Use the OpenAI Compatible provider type if your proxy serves multiple model families through a single OpenAI-compatible endpoint. Include the proxy provider's documented OpenAI-compatible path prefix, such as /v1, when required.

This lets you keep existing proxy-level features like per-user budgets, rate limiting, and audit logging while using Coder Agents as the developer interface.