opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-10-16 06:37:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand abbreviations on their first use on each page

Browse Source 
Spell out each abbreviation where it first appears on a page, in the
form "Expanded Form (ABBR)", so every page in docs/ passes the
Coder.AbbreviationFirstUse rule that the next commit enables.

Where the first use is a UI label in bold, the label stays as the UI
shows it and the expansion goes elsewhere in the same paragraph or list
item. Reversed forms such as "PKCE (Proof Key for Code Exchange)" are
flipped to the expanded-first form. A few sentences needed a small
rewording to take the expansion: glossary entries that said
"abbreviated CVA" and "abbreviated PAT", hyphenated compounds such as
"EKS-specific", and a parenthetical about SSDs that would otherwise nest
parentheses.

Other changes on touched lines: "IDES" becomes "IDEs", "DERP MAP"
becomes "DERP map", and an em dash in a table row that the table
formatter re-padded becomes a comma, because the em-dash check reads
changed lines.

Assisted-by: AI
This commit is contained in:
Nick Vigilante
2026-10-15 16:28:27 -04:00
parent fa926fcc77
commit dc21767143
173 changed files with 598 additions and 598 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.style/README.md
+2 -2
View File
@@ -55,8 +55,8 @@ Two defense-in-depth changes in `.github/workflows/deploy-docs.yaml` keep the de
The guide deliberately contains the constructs the rules ban, such as Don't examples and banned terms named in headings and prose, so the repo-root `.vale.ini` clears `BasedOnStyles` for `docs/.style/style-guide/**`.
Nothing else under `docs/.style/` is exempt: the landing page, `content-guidelines.md`, the annotation demo, and the Coder rule docs are all linted.
Zero-baseline is therefore measured over `docs/` excluding `docs/.style/style-guide/`.
The exemption applies only when the path resolves to `docs/.style/style-guide/...` from the working directory, which is what `make lint/prose` and CI pass (repo-root-relative `docs/...`).
Other invocation forms bypass the glob and still flag the guide's intentional examples: absolute paths (what editors and LSP integrations pass) and subdirectory-relative paths (for example `vale .style/style-guide/...` run from `docs/`).
The exemption applies only when the path resolves to `docs/.style/style-guide/...` from the working directory, which is what `make lint/prose` and continuous integration (CI) pass (repo-root-relative `docs/...`).
Other invocation forms bypass the glob and still flag the guide's intentional examples: absolute paths (what editors and Language Server Protocol (LSP) integrations pass) and subdirectory-relative paths (for example `vale .style/style-guide/...` run from `docs/`).
Treat those in-editor and subdirectory findings on the guide as expected.
## Editing the content guidelines
docs/.style/content-guidelines.md
+5 -5
View File
@@ -2,7 +2,7 @@
> [!NOTE]
> This is the **canonical** guidance for what belongs in the Coder documentation under `docs/` (published to [coder.com/docs](https://coder.com/docs)) and what doesn't.
> It applies to both human contributors and any LLM-assisted workflow that touches the docs.
> It applies to both human contributors and any large language model (LLM)-assisted workflow that touches the docs.
> When this file conflicts with another style or contributing document in the repository, this file governs.
## How to use this guide
@@ -69,7 +69,7 @@ Untestable claims rot silently.
Docs claims should be checked against the actual implementation, not approximations:
- Exact RBAC action names.
- Exact role-based access control (RBAC) action names.
Example: `template:view_insights`, not "view insights".
- Real thresholds and defaults.
Example: `green < 150ms, yellow 150-300ms, red ≥300ms`, not "around 150&nbsp;ms".
@@ -146,7 +146,7 @@ Practical impact for docs:
The feature is in active development, hidden behind a flag the user wouldn't enable on a real deployment, and may be reverted at any time.
- **Safe experiments and Early Access features** need at least a single docs page covering how to enable the feature, what it does, and known limitations.
- **Beta features** get full docs (how to use, configure, and operate), with the `Beta` label.
- **GA features** get full docs across reference, tutorials, and guides as appropriate.
- **General availability (GA) features** get full docs across reference, tutorials, and guides as appropriate.
*Why:* Holding unsafe-experiment PRs to the docs bar is noise.
Holding Early Access or Beta PRs to a lower bar is drift.
@@ -157,7 +157,7 @@ Use this catalog with the [quick decision checklist](#quick-decision-checklist)
Each entry includes the reason it belongs in the docs.
- **Tutorials that touch programmatic aspects of the product.**
"If I run this group of CLI commands, what's supposed to happen?" and "How do I do X in the product?", each written so it can become a testable, verifiable CI surface.
"If I run this group of CLI commands, what's supposed to happen?" and "How do I do X in the product?", each written so it can become a testable, verifiable continuous integration (CI) surface.
*Why:* A true tutorial serves the user's study and informs action; it teaches the right way to use a command in an approachable, no-risk way that a bare reference page can't.
@@ -213,7 +213,7 @@ Each entry includes the reason it belongs in the docs.
The policy is not "no screenshots"; it is "use screenshots wisely."
Every screenshot must follow all of these rules:
1. No PHI or PII.
1. No protected health information (PHI) or personally identifiable information (PII).
2. No internal secrets leaked without properly obfuscating the text.
3. Capture the minimally necessary surface area.
The more area a
docs/.style/styles/Coder/README.md
+1 -1
View File
@@ -29,7 +29,7 @@ Planned coverage:
- The rule is objectively correct (typo, brand-name casing, banned
substitution).
- The existing-content violation count for the rule reaches zero.
4. A follow-up PR adds a parity CI check that verifies every rule here has a matching section in `style-guide/`.
4. A follow-up PR adds a parity continuous integration (CI) check that verifies every rule here has a matching section in `style-guide/`.
Add the section in the same PR as the rule.
## Reference
docs/README.md
+8 -8
View File
@@ -7,7 +7,7 @@ markdown_url: /docs.md
Coder is a self-hosted platform for running AI coding agents and cloud
development environments on infrastructure you control. It works with any
cloud, IDE, OS, Git provider, and IDP.
cloud, IDE, OS, Git provider, and identity provider (IDP).
![Coder platform showing templates and a running workspace](./images/hero-image.png)
@@ -19,7 +19,7 @@ automatically shut down when not in use. Agents and developers share the same
workspace infrastructure.
- **Defined in Terraform**: Templates describe the infrastructure for each
workspace, from EC2 VMs and Kubernetes Pods to Docker containers.
workspace, from Amazon Elastic Compute Cloud (EC2) virtual machines (VMs) and Kubernetes Pods to Docker containers.
- **Any architecture and OS**: Support ARM and x86-64 across Windows, Linux,
and macOS from a single deployment.
- **Managed by admins**: Platform teams create and maintain templates that
@@ -34,12 +34,12 @@ workspace infrastructure.
[Coder Agents](./ai-coder/agents/index.md) is a native AI coding agent built
into Coder. The agent loop runs in the Coder control plane on your
infrastructure, not in the workspace and not in a vendor's cloud. Developers
interact with agents through the web UI or the REST API for programmatic and
CI-driven workflows.
interact with agents through the web UI or the Representational State Transfer (REST) API for programmatic and
continuous integration (CI)-driven workflows.
- **Self-hosted agent loop**: The control plane handles planning, model
calls, and tool dispatch. Workspaces have zero AI awareness.
- **No API keys in workspaces**: LLM credentials stay in the control plane.
- **No API keys in workspaces**: Large language model (LLM) credentials stay in the control plane.
- **Any model**: Anthropic, OpenAI, Google, Bedrock, or self-hosted
endpoints. Switching is a configuration change.
- **Governance and cost controls**: Centralized model approval, per-user
@@ -91,8 +91,8 @@ This approach provides:
- **Consistency**: Infrastructure tools such as Terraform, nix, Docker, and
Dev Containers produce identical environments for every developer.
- **Security**: Source code stays on private servers. Users and groups are
managed through [SSO](./admin/users/oidc-auth/index.md) and
[RBAC](./admin/users/groups-roles.md#roles).
managed through [single sign-on (SSO)](./admin/users/oidc-auth/index.md) and
[Role-based access control (RBAC)](./admin/users/groups-roles.md#roles).
- **Compatibility**: Workspaces share infrastructure configurations with
staging and production, reducing configuration drift.
- **Accessibility**: Browser-based IDEs and remote IDE extensions let
@@ -113,7 +113,7 @@ For agents, this means platform teams can:
- Run the entire agent loop on their infrastructure, with no SaaS
dependency for orchestration.
- Define MCP servers, skills, and system prompts centrally so every agent
- Define Model Context Protocol (MCP) servers, skills, and system prompts centrally so every agent
session starts with the same tools, policies, and context.
- Keep LLM credentials out of workspaces entirely.
- Tie every agent action to an authenticated user identity.
docs/admin/external-auth.md
+2 -2
View File
@@ -165,7 +165,7 @@ You must add the SSH key to your Git provider.
## PKCE Support
[PKCE (Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) is an OAuth 2.0
[Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) is an OAuth 2.0
security extension that prevents authorization code interception attacks. Coder supports PKCE when
acting as an OAuth client to external identity providers.
@@ -223,7 +223,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.example.com/rest/oauth2/latest/authorize
```
When configuring your Bitbucket OAuth application, set the redirect URI to
When configuring your Bitbucket OAuth application, set the redirect Uniform Resource Identifier (URI) to
`https://example.com/external-auth/primary-bitbucket-server/callback`.
This callback path includes the value of `CODER_EXTERNAL_AUTH_0_ID`.
docs/admin/index.md
+3 -3
View File
@@ -17,7 +17,7 @@ For automation and scripting workflows, see our [CLI](../reference/cli/index.md)
and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
[Tutorials](../tutorials/index.md) and [frequently asked questions (FAQs)](../tutorials/faqs.md).
## What is an image, template, dev container, or workspace
@@ -34,7 +34,7 @@ For any information not strictly contained in these sections, check out our
- [Templates](./templates/index.md) include infrastructure-level dependencies
for the workspace. For example, a template can include Kubernetes
PersistentVolumeClaims, Docker containers, or EC2 VMs.
PersistentVolumeClaims, Docker containers, or Amazon Elastic Compute Cloud (EC2) virtual machines (VMs).
- Managed by: Template administrators from within the Coder deployment.
### Startup scripts
@@ -56,7 +56,7 @@ For any information not strictly contained in these sections, check out our
- A
[Development Container](./integrations/devcontainers/index.md)
is an open-source specification for defining development environments (called
dev containers). It is generally stored in VCS alongside associated source
dev containers). It is generally stored in version control system (VCS) alongside associated source
code. It can reference an existing base image, or a custom Dockerfile that
will be built on-demand.
- Managed by: Dev Teams
docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md
+6 -6
View File
@@ -97,12 +97,12 @@ Developers can edit the `devcontainer.json` in their workspace to customize thei
## Example templates
| Template | Description |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Docker dev containers](../../../../../examples/templates/docker-devcontainer) | Docker provisions a development container. |
| [Kubernetes dev containers](../../../../../examples/templates/kubernetes-devcontainer) | Provisions a development container on the Kubernetes cluster. |
| [Google Compute Engine dev container](../../../../../examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
| [AWS EC2 dev container](../../../../../examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
| Template | Description |
|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Docker dev containers](../../../../../examples/templates/docker-devcontainer) | Docker provisions a development container. |
| [Kubernetes dev containers](../../../../../examples/templates/kubernetes-devcontainer) | Provisions a development container on the Kubernetes cluster. |
| [Google Compute Engine dev container](../../../../../examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the virtual machine (VM) inside the container to enable Docker inside the workspace. |
| [AWS Elastic Compute Cloud (EC2) dev container](../../../../../examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
Your template can prompt the user for a repo URL with [parameters](../../../templates/extending-templates/parameters.md):
docs/admin/integrations/devcontainers/envbuilder/index.md
+1 -1
View File
@@ -29,7 +29,7 @@ Envbuilder can run on Docker or Kubernetes.
It is independently packaged and versioned from the centralized Coder open-source project.
This means that Envbuilder can be used with Coder, but it is not required.
It also means that dev container builds can scale independently of the Coder control plane and even run within a CI/CD pipeline.
It also means that dev container builds can scale independently of the Coder control plane and even run within a continuous integration and continuous delivery (CI/CD) pipeline.
## Next steps
docs/admin/integrations/index.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Integrations
---
Coder is highly extensible and is not limited to the platforms outlined in these docs.
The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource.
The control plane can be provisioned on any virtual machine (VM) or container compute, and workspaces can include any Terraform resource.
See our [architecture diagram](../../install/plan/architecture.md) for more details.
You can host your deployment on almost any infrastructure.
docs/admin/integrations/multiple-kube-clusters.md
+2 -2
View File
@@ -47,7 +47,7 @@ coder:
### VM control plane
If you deployed Coder on a VM, copy the kubeconfig file to `/home/coder/.kube/config`.
If you deployed Coder on a virtual machine (VM), copy the kubeconfig file to `/home/coder/.kube/config`.
### Create a Coder template
@@ -189,7 +189,7 @@ Kubernetes control plane is running at https://example.domain:6443
export CLUSTER_ADDRESS=https://example.domain:6443
```
To fetch the CA certificate and token:
To fetch the certificate authority (CA) certificate and token:
```sh
export CLUSTER_CA_CERTIFICATE=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.ca\.crt}")
docs/admin/integrations/oauth2-provider/callback-url-schemes.md
+3 -3
View File
@@ -2,7 +2,7 @@
title: OAuth2 provider callback URL schemes
---
This page covers which redirect URI schemes and hosts Coder accepts, for both admin-created and self-registered applications.
This page covers which redirect Uniform Resource Identifier (URI) schemes and hosts Coder accepts, for both admin-created and self-registered applications.
Custom URI schemes (`myapp://`, `vscode://`, `jetbrains://`, etc.) are fully supported for native and desktop applications.
The OS routes the redirect back to the registered application without requiring a running HTTP server.
@@ -10,7 +10,7 @@ A private-use scheme must name a path or an authority, as in `com.example.app:/c
The bare form `com.example.app:callback` is rejected.
The out-of-band URN `urn:ietf:wg:oauth:2.0:oob` is accepted from either client type, for clients that display the authorization code for the user to copy rather than receiving it on a redirect.
No other URN is accepted.
No other Uniform Resource Name (URN) is accepted.
The following schemes are blocked for security reasons: `javascript:`, `data:`, `file:`, `ftp:`.
@@ -24,7 +24,7 @@ Every other host must use `https://`, so that an authorization code is never del
The management API and Dynamic Client Registration apply the same rule, so an administrator cannot store a target that a client could not register for itself.
Coder ignores the port of an `http://` redirect URI to `localhost`, `127.0.0.1`, or `[::1]`, for public and confidential clients alike.
RFC 8252 requires this for `127.0.0.1` and `[::1]` so that native apps can choose a port at runtime.
Request for Comments (RFC) 8252 requires this for `127.0.0.1` and `[::1]` so that native apps can choose a port at runtime.
Coder applies it to `localhost` too.
A `.localhost` subdomain still requires an exact port match.
Register `http://127.0.0.1/callback` and present whichever port the client is listening on.
docs/admin/integrations/oauth2-provider/index.md
+3 -3
View File
@@ -70,7 +70,7 @@ Treat the setting as a way to stop new authorizations rather than as a way to re
Your application name
- **Default callback**:
`https://yourapp.example.com/callback` (web) or `myapp://callback` (native/desktop).
Select **Add redirect URI** for additional callback URLs.
Select **Add redirect URI** to add a Uniform Resource Identifier (URI) for each additional callback URL.
- **Icon**:
Optional icon URL
- **Allowed scopes**:
@@ -137,11 +137,11 @@ curl -X POST \
The response includes `client_secret_full`, the plaintext secret.
Save it now: later reads of this application return only a truncated version.
Every client, whichever method you used to create its application, must complete PKCE (Proof Key for Code Exchange) to exchange a code for a token; refer to [Authorization code flow](./integration-patterns.md#authorization-code-flow) before you start integrating.
Every client, whichever method you used to create its application, must complete Proof Key for Code Exchange (PKCE) to exchange a code for a token; refer to [Authorization code flow](./integration-patterns.md#authorization-code-flow) before you start integrating.
## Dynamic Client Registration
Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) lets a client register itself against `/oauth2/register` instead of an admin creating the application manually.
Dynamic Client Registration ([Request for Comments (RFC) 7591](https://datatracker.ietf.org/doc/html/rfc7591)) lets a client register itself against `/oauth2/register` instead of an admin creating the application manually.
It's **disabled by default**; an owner must turn it on before any client can self-register.
Change the setting in the web UI:
docs/admin/integrations/oauth2-provider/integration-patterns.md
+6 -6
View File
@@ -2,7 +2,7 @@
title: OAuth2 provider integration patterns
---
This page covers how a client proves who it is and completes a login: the supported ways to prove identity, the standard login steps, the required PKCE (Proof Key for Code Exchange) step, and how a client finds the right web addresses to use.
This page covers how a client proves who it is and completes a login: the supported ways to prove identity, the standard login steps, the required Proof Key for Code Exchange (PKCE) step, and how a client finds the right web addresses to use.
- [OAuth2 provider](./index.md): turn on the provider and create an application
- [Scopes](./scopes.md): control what a client is allowed to access
@@ -13,7 +13,7 @@ This page covers how a client proves who it is and completes a login: the suppor
Coder supports the following OAuth2 client authentication methods at the token endpoint (`/oauth2/tokens`):
- `client_secret_basic` (recommended): HTTP Basic authentication (RFC 6749 §2.3.1).
- `client_secret_basic` (recommended): HTTP Basic authentication (Request for Comments (RFC) 6749 §2.3.1).
The username is `client_id` and the password is `client_secret`.
- `client_secret_post`: Form-based authentication where `client_id` and `client_secret` are sent in the request body.
- `none`: No client secret.
@@ -27,7 +27,7 @@ Send `client_secret` in the request body or in the `Authorization` header.
Refer to ["invalid_request" for `client_secret` in the query string](./troubleshooting.md#invalid_request-for-client_secret-in-the-query-string) for the exceptions and the log line to search for.
Public clients suit native, mobile, and CLI applications that cannot keep a secret confidential.
Note the redirect URI restrictions below before choosing one.
Note the redirect Uniform Resource Identifier (URI) restrictions below before choosing one.
Opening a public client on the **OAuth2 Applications** page shows no client secrets section, since a public client has no secret to display or generate.
@@ -126,9 +126,9 @@ Coder provides OAuth2 discovery endpoints for programmatic integration:
- **Authorization Server Metadata**:
`GET /.well-known/oauth-authorization-server`
- **REST API protected resource metadata**:
- **Representational State Transfer (REST) API protected resource metadata**:
`GET /.well-known/oauth-protected-resource`
- **MCP protected resource metadata**:
- **Model Context Protocol (MCP) protected resource metadata**:
`GET /.well-known/oauth-protected-resource/api/experimental/mcp/http`
These endpoints return server capabilities and endpoint URLs according to [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) and [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).
@@ -143,7 +143,7 @@ It is not gated on [Dynamic Client Registration](./index.md#dynamic-client-regis
## Standards compliance
This implementation follows established OAuth2 standards including [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) (OAuth2 core), [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) (PKCE), and the [OAuth 2.1 draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-16).
Coder enforces OAuth 2.1 requirements including mandatory PKCE for all authorization code grants, exact redirect URI string matching with the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252) loopback port exception, rejection of the implicit grant, and CSRF protections on consent pages.
Coder enforces OAuth 2.1 requirements including mandatory PKCE for all authorization code grants, exact redirect URI string matching with the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252) loopback port exception, rejection of the implicit grant, and cross-site request forgery (CSRF) protections on consent pages.
## Learn more
docs/admin/integrations/oauth2-provider/scopes.md
+1 -1
View File
@@ -36,7 +36,7 @@ An update that resends the stored `scope` unchanged keeps it as stored.
An allowlist set through the web UI or the management API is stored as given; a name it holds that this deployment does not offer fails at authorization, as described under ["invalid_scope" returned to your callback](./troubleshooting.md#invalid_scope-returned-to-your-callback).
Use caution when narrowing the scope allowlist of a self-registered application.
Many clients request every scope Coder advertises in `scopes_supported` rather than selecting specific scopes; MCP clients that rely on discovery commonly work this way.
Many clients request every scope Coder advertises in `scopes_supported` rather than selecting specific scopes; Model Context Protocol (MCP) clients that rely on discovery commonly work this way.
The allowlist is stored on the application and does not affect that advertised list, so the client continues requesting the full set.
Coder rejects requests that exceed the allowlist rather than trimming their scopes, so every new authorization attempt fails with `invalid_scope`.
Previously issued tokens retain their scopes.
docs/admin/integrations/oauth2-provider/security.md
+5 -5
View File
@@ -11,10 +11,10 @@ This page covers security guidance and current limitations.
- **Use HTTPS**:
Always use HTTPS in production to protect tokens in transit
- **Implement PKCE**:
PKCE is mandatory for all authorization code clients (public and confidential)
Proof Key for Code Exchange (PKCE) is mandatory for all authorization code clients (public and confidential)
- **Validate redirect URLs**:
Only register trusted redirect URIs.
Dangerous schemes (`javascript:`, `data:`, `file:`, `ftp:`) are blocked by the control plane, custom URI schemes for native apps (`myapp://`) are permitted, and public clients additionally cannot use `mailto:`, `tel:`, or `sms:`
Dangerous schemes (`javascript:`, `data:`, `file:`, `ftp:`) are blocked by the control plane, custom Uniform Resource Identifier (URI) schemes for native apps (`myapp://`) are permitted, and public clients additionally cannot use `mailto:`, `tel:`, or `sms:`
- **Rotate secrets**:
Periodically rotate client secrets using the management API
- **Rate limits**:
@@ -26,7 +26,7 @@ This page covers security guidance and current limitations.
Running the deployment with `--dangerous-disable-rate-limits` turns it off, and a user with the Owner role can bypass it on a single request with the `X-Coder-Bypass-Ratelimit` header
- **Refresh tokens are not self-sufficient**:
a confidential client must present its `client_secret` to refresh or revoke, so a leaked token alone cannot mint new access tokens or end another client's session
- **No CORS on the authorization endpoint**:
- **No cross-origin resource sharing (CORS) on the authorization endpoint**:
`/oauth2/authorize` is reached only by browser navigation and sends no CORS headers, as OAuth 2.1 requires.
The token, registration, revocation, and metadata endpoints do allow cross-origin requests so that browser-based clients can call them
@@ -35,9 +35,9 @@ This page covers security guidance and current limitations.
The current implementation has these limitations:
- No client credentials grant support
- No device authorization grant support (RFC 8628)
- No device authorization grant support (Request for Comments (RFC) 8628)
- Implicit grant (`response_type=token`) is not supported; OAuth 2.1 deprecated this flow due to token leakage risks, and a request for it redirects to the registered callback with `unsupported_response_type`
- Limited to opaque access tokens (no JWT support)
- Limited to opaque access tokens (no JSON Web Token (JWT) support)
- An application may register at most 32 redirect URIs of at most 2048 bytes each.
An application that stored a longer list before this limit existed keeps working, but it cannot be saved again until the list fits.
To fix it, send a `PUT` with a `redirect_uris` list that fits, as shown under [Create an application with the API](./index.md#create-an-application-with-the-api).
docs/admin/integrations/oauth2-provider/token-management.md
+1 -1
View File
@@ -48,7 +48,7 @@ curl -X POST \
## Revoke a token
Revoke one refresh token or access token through the [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009) endpoint that `revocation_endpoint` advertises.
Revoke one refresh token or access token through the [Request for Comments (RFC) 7009](https://datatracker.ietf.org/doc/html/rfc7009) endpoint that `revocation_endpoint` advertises.
A confidential client authenticates as it does on a refresh, with HTTP Basic as below or with `client_id` and `client_secret` form fields as in the refresh examples above.
An omitted or wrong secret answers HTTP 401 with `error=invalid_client`:
docs/admin/integrations/oauth2-provider/troubleshooting.md
+6 -6
View File
@@ -15,7 +15,7 @@ Refer to [Enable OAuth2 Provider](./index.md#enable-oauth2-provider).
## "Invalid redirect_uri"
Ensure the redirect URI in your request exactly matches one of the redirect URIs registered for your application.
Ensure the redirect Uniform Resource Identifier (URI) in your request exactly matches one of the redirect URIs registered for your application.
The one exception is the port of a loopback `http://` redirect URI (`localhost`, `127.0.0.1`, `[::1]`), which may differ from the registered one.
Refer to [Callback URL schemes](./callback-url-schemes.md).
@@ -132,7 +132,7 @@ The rule covers `client_secret` only.
Coder still reads `refresh_token`, `code`, and the revocation `token` from the query string.
Send those in the request body too, not in the query string.
A `client_secret` with no value, as in `?client_secret=`, counts as absent under RFC 6749 section 3.2 and is not refused by this rule.
A `client_secret` with no value, as in `?client_secret=`, counts as absent under Request for Comments (RFC) 6749 section 3.2 and is not refused by this rule.
`POST /oauth2/revoke` accepts such a request when the body authenticates.
`POST /oauth2/tokens` answers 400 only when the body also carries a `client_secret`, because it reads the body copy and the empty URL copy as the same parameter sent twice, and the error says so.
An empty query value alone never causes a 400: a request that authenticates with HTTP Basic and sends no secret in the body, or one from a public client, succeeds.
@@ -154,7 +154,7 @@ The check also runs after the `client_id` is resolved.
A request with a missing, malformed, or unknown `client_id` is answered by that lookup first and writes no such line, so an absent line does not mean no integration is leaking.
Rotate the secret that was in the URL.
It is still valid, and a URL is recorded by reverse proxies, load balancers, CDN access logs, shell history, and client libraries.
It is still valid, and a URL is recorded by reverse proxies, load balancers, content delivery network (CDN) access logs, shell history, and client libraries.
Coder does not log query strings, so an empty result when you search the Coder logs does not mean the secret stayed private.
Deleting a secret also revokes the tokens issued under it, so the client has to authorize again.
@@ -209,7 +209,7 @@ An integration that watched for either now has to read the error from its own ca
## "invalid_request" for `code_challenge_method`
Coder supports the `S256` challenge method only.
`plain` sends the verifier itself as the challenge, so anything that can observe the authorization request can complete the exchange, which is what PKCE exists to prevent.
`plain` sends the verifier itself as the challenge, so anything that can observe the authorization request can complete the exchange, which is what Proof Key for Code Exchange (PKCE) exists to prevent.
Omitting the parameter is allowed and means `S256`.
An unsupported method redirects to your registered callback with `error=invalid_request`, an `error_description` that names the method, and the `state` you sent.
@@ -225,7 +225,7 @@ The rejection redirects to your registered callback with `error=invalid_request`
This holds for both `GET /oauth2/authorize` and `POST /oauth2/authorize`.
A description longer than 2048 characters is cut short and marked `(truncated)`.
Parameters the endpoint does not read are ignored, as RFC 6749 Section 3.1 requires, so an OIDC `nonce` or a vendor extension does not fail the request.
Parameters the endpoint does not read are ignored, as RFC 6749 Section 3.1 requires, so an OpenID Connect (OIDC) `nonce` or a vendor extension does not fail the request.
A misspelled parameter is ignored on the same rule, so what you see is the failure caused by the parameter you meant to send being absent.
Two failures stay on Coder rather than reaching your callback, because in both cases the callback is not yet trustworthy:
@@ -265,7 +265,7 @@ Verify that the `code_verifier` used in the token request matches the one used t
## "public clients may not use the mailto/tel/sms scheme"
This error appears during client registration when a public client (`token_endpoint_auth_method: none`) registers a redirect URI using the `mailto:`, `tel:`, or `sms:` scheme.
These schemes hand off to a mail client, dialer, or SMS app instead of returning control to the application that started the flow, so a public client registered with one of them could never complete authorization.
These schemes hand off to a mail client, dialer, or Short Message Service (SMS) app instead of returning control to the application that started the flow, so a public client registered with one of them could never complete authorization.
Register a redirect URI the client can actually receive control on instead, such as a custom scheme (`myapp://callback`) or a loopback HTTP address.
## Learn more
docs/admin/integrations/vault.md
+1 -1
View File
@@ -35,7 +35,7 @@ module "vault" {
This module installs and authenticates the `vault` CLI in your Coder workspace.
Users then can use the `vault` CLI to interact with Vault; for example, to fetch a secret stored in the KV backend.
Users then can use the `vault` CLI to interact with Vault; for example, to fetch a secret stored in the key-value (KV) backend.
```sh
vault kv get -namespace=YOUR_NAMESPACE -mount=MOUNT_NAME SECRET_NAME
docs/admin/monitoring/connection-logs.md
+1 -1
View File
@@ -58,7 +58,7 @@ You can filter connection logs by the following parameters:
- `method` - How the connection was established, such as `ssh`, `reconnecting_pty`, or `workspace_app`.
For every method, refer to the [`codersdk.ConnectionLogMethod` schema](../../reference/api/schemas.md#codersdkconnectionlogmethod).
For example, `method:ssh` matches every SSH connection, whichever app made it.
- `app` - The name of the application that made an SSH or reconnecting PTY connection, such as `cursor`.
- `app` - The name of the application that made an SSH or reconnecting pseudo-terminal (PTY) connection, such as `cursor`.
Repeat the filter to match any of several apps, for example `app:vscode app:cursor`.
Some clients report only `vscode` or `jetbrains` instead of their own name, so `app:vscode` and `app:jetbrains` can also include other VS Code-based editors and JetBrains IDEs.
Coder lowercases the value and replaces hyphens with underscores before it matches.
docs/admin/monitoring/health-check.md
+6 -6
View File
@@ -56,7 +56,7 @@ This could be due to a number of reasons, including but not limited to:
- DNS lookup failure
- A misconfigured firewall
- A misconfigured reverse proxy
- Invalid or expired SSL certificates
- Invalid or expired Secure Sockets Layer (SSL) certificates
**Solution:** Investigate and resolve the root cause of the connection issue.
@@ -129,7 +129,7 @@ configured threshold to a higher value (this will not address the root cause).
## DERP
Coder workspace agents may use
[DERP (Designated Encrypted Relay for Packets)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
[Designated Encrypted Relay for Packets (DERP)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
to communicate with Coder. This requires connectivity to a number of configured
[DERP servers](../../reference/cli/server/index.md#--derp-config-path) which are used
to relay traffic between Coder and workspace agents. Coder periodically queries
@@ -198,13 +198,13 @@ deployment. For example:
#### No STUN servers available
**Problem:** This is shown if no STUN servers are available. Coder will use STUN
**Problem:** This is shown if no Session Traversal Utilities for Network Address Translation (STUN) servers are available. Coder will use STUN
to establish [direct connections](../networking/stun.md). Without at least one
working STUN server, direct connections may not be possible.
**Solution:** Ensure that the
[configured STUN severs](../../reference/cli/server/index.md#--derp-server-stun-addresses)
are reachable from Coder and that UDP traffic can be sent/received on the
are reachable from Coder and that User Datagram Protocol (UDP) traffic can be sent/received on the
configured port.
### ESTUN02
@@ -213,7 +213,7 @@ configured port.
**Problem:** This is a warning shown when multiple attempts to determine our
public IP address/port via STUN resulted in different `ip:port` combinations.
This is a sign that you are behind a "hard NAT", and may result in difficulty
This is a sign that you are behind a "hard Network Address Translation (NAT)", and may result in difficulty
establishing direct connections. However, it does not mean that direct
connections are impossible.
@@ -269,7 +269,7 @@ to write a message.
2. Validate that the network link between Coder and the workspace proxy is
stable, e.g. by using `ping`.
3. Validate that any internal network infrastructure (for example, firewalls,
proxies, VPNs) do not interfere with WebSocket connections.
proxies, virtual private networks (VPNs)) do not interfere with WebSocket connections.
## Workspace Proxy
docs/admin/monitoring/logs.md
+2 -2
View File
@@ -12,7 +12,7 @@ By default, `coderd`, the process that runs the control plane, exports
human-readable logs to standard output. You can access these logs via
`kubectl logs deployment/coder -n <coder-namespace>`
on Kubernetes or `journalctl -u coder` if you deployed Coder on a host
machine/VM.
machine/virtual machine (VM).
- To change the log format/location, you can set
[`CODER_LOGGING_HUMAN`](../../reference/cli/server/index.md#--log-human) and
@@ -27,7 +27,7 @@ machine/VM.
> `CODER_LOGGING_HUMAN`) to `/dev/null`. An empty string does not disable
> logging.
Events such as server errors, audit logs, user activities, and SSO & OpenID
Events such as server errors, audit logs, user activities, and single sign-on (SSO) & OpenID
Connect logs are all captured in the `coderd` logs.
## `provisionerd` Logs
docs/admin/monitoring/notifications/index.md
+3 -3
View File
@@ -61,7 +61,7 @@ These notifications are sent to the workspace owner:
## Delivery Methods
Notifications can be delivered through the Coder dashboard Inbox and by SMTP or webhook.
Notifications can be delivered through the Coder dashboard Inbox and by Simple Mail Transfer Protocol (SMTP) or webhook.
OOM/OOD notifications can be delivered to users in VS Code.
You can configure:
@@ -224,7 +224,7 @@ Here is an example payload for Coder's webhook notification:
The top-level object has these keys:
- `_version`: describes the version of this schema; follows semantic versioning
- `msg_id`: the UUID of the notification (matches the ID in the
- `msg_id`: the universally unique identifier (UUID) of the notification (matches the ID in the
`notification_messages` table)
- `payload`: contains the specific details of the notification; described below
- `title`: the title of the notification message (equivalent to a subject in
@@ -241,7 +241,7 @@ The `payload` object has these keys:
- `user_email`: email address of the target user
- `user_name`: name of the target user
- `user_username`: username of the target user
- `actions`: a list of CTAs (Call-To-Action); these are mainly relevant for SMTP
- `actions`: a list of calls to action (CTAs); these are mainly relevant for SMTP
delivery in which they're shown as buttons
- `labels`: dynamic map of zero or more string key-value pairs; these vary from
event to event
docs/admin/networking/high-availability.md
+1 -1
View File
@@ -57,7 +57,7 @@ because `CODER_DERP_SERVER_RELAY_URL` is ignored and no fallback address is
available. If a node has neither value set, Coder logs an error and falls back
to PostgreSQL for pubsub.
Nodes connect to each other's pubsub on TCP port 6222, which isn't configurable.
Nodes connect to each other's pubsub on Transmission Control Protocol (TCP) port 6222, which isn't configurable.
Allow port 6222 between the `CODER_CLUSTER_HOST` addresses of your `coderd` nodes in any firewall or Kubernetes NetworkPolicy that sits between them.
If you use the embedded relay, also allow the port in `CODER_DERP_SERVER_RELAY_URL`.
If port 6222 is blocked, Coder doesn't fall back to PostgreSQL, so events published on one node, such as workspace updates, don't reach clients connected to another node.
docs/admin/networking/index.md
+5 -5
View File
@@ -10,7 +10,7 @@ workspaces, but otherwise, all topologies _just work_ with Coder.
When possible, we establish direct connections between users and workspaces.
Direct connections are as fast as connecting to the workspace outside of Coder.
When NAT traversal fails, connections are relayed through the control plane. All
When Network Address Translation (NAT) traversal fails, connections are relayed through the control plane. All
user-workspace connections are end-to-end encrypted.
[Tailscale's open source](https://tailscale.com) backs our websocket/HTTPS
@@ -52,11 +52,11 @@ In order for clients to be able to establish direct connections:
communicate with each other using their locally assigned IP addresses, then a
direct connection can be established immediately. Otherwise, the client and
agent will contact
[the configured STUN servers](../../reference/cli/server/index.md#--derp-server-stun-addresses)
[the configured Session Traversal Utilities for Network Address Translation (STUN) servers](../../reference/cli/server/index.md#--derp-server-stun-addresses)
to try and determine which `ip:port` can be used to communicate with their
counterpart. See [STUN and NAT](./stun.md) for more details on how this
process works.
- All outbound UDP traffic must be allowed for both the client and the agent on
- All outbound User Datagram Protocol (UDP) traffic must be allowed for both the client and the agent on
**all ports** to each others' respective networks.
- To establish a direct connection, both agent and client use STUN. This
involves sending UDP packets outbound on `udp/3478` to the configured
@@ -121,7 +121,7 @@ but this can be disabled or changed for
### Relayed connections
By default, your control plane also runs a built-in DERP relay which can be used
By default, your control plane also runs a built-in Designated Encrypted Relay for Packets (DERP) relay which can be used
for both public and [Air-gapped deployments](../../install/prepare/airgap.md).
However, Tailscale maintains a global fleet of [DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers) intended for their product, and has allowed Coder to access and use them.
@@ -212,7 +212,7 @@ There are three main types of latency metrics for your Coder deployment:
The latency shown on the workspace dashboard measures the round-trip time between the workspace agent and its DERP relay server.
This metric is displayed in milliseconds on the workspace dashboard and specifically shows the agent-to-relay latency, not direct P2P connections.
This metric is displayed in milliseconds on the workspace dashboard and specifically shows the agent-to-relay latency, not direct peer-to-peer (P2P) connections.
To estimate the total end-to-end latency experienced by a user, add the dashboard-to-server latency to this agent-to-relay latency.
docs/admin/networking/port-forwarding.md
+8 -8
View File
@@ -8,12 +8,12 @@ a browser.
There are four ways to forward ports in Coder:
| Method | Details |
|:---------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Coder Desktop](#coder-desktop) | Automatic port forwarding via VPN tunnel. All workspace ports are available at `workspace.coder:PORT` with no manual setup. Supports peer-to-peer connections. |
| [CLI](#the-coder-port-forward-command) | Forwards specific TCP or UDP ports from the workspace to local ports. Supports peer-to-peer connections. |
| [Dashboard](#dashboard) | Proxies traffic through the Coder control plane. |
| [SSH](#ssh) | Forwards ports over an SSH connection. |
| Method | Details |
|:---------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Coder Desktop](#coder-desktop) | Automatic port forwarding via virtual private network (VPN) tunnel. All workspace ports are available at `workspace.coder:PORT` with no manual setup. Supports peer-to-peer connections. |
| [CLI](#the-coder-port-forward-command) | Forwards specific Transmission Control Protocol (TCP) or User Datagram Protocol (UDP) ports from the workspace to local ports. Supports peer-to-peer connections. |
| [Dashboard](#dashboard) | Proxies traffic through the Coder control plane. |
| [SSH](#ssh) | Forwards ports over an SSH connection. |
Coder Desktop and `coder port-forward` are generally more performant than:
@@ -145,7 +145,7 @@ not it is still accessible.
![Annotated port controls in the UI](../../images/networking/annotatedports.png)
The sharing level is limited by the maximum level enforced in the template
settings in premium deployments, and not restricted in OSS deployments.
settings in premium deployments, and not restricted in open source software (OSS) deployments.
This can also be used to change the sharing level of `coder_app`s by entering
their port number in the sharable ports UI. The `share` attribute on `coder_app`
@@ -192,7 +192,7 @@ When forwarding via the dashboard, Coder automatically sets headers that allow
requests between separately forwarded applications belonging to the same user.
When forwarding through other methods the application itself will need to set
its own CORS headers if they are being forwarded through different origins since
its own cross-origin resource sharing (CORS) headers if they are being forwarded through different origins since
Coder does not intercept these cases. See below for the required headers.
#### Authentication
docs/admin/networking/stun.md
+4 -4
View File
@@ -42,7 +42,7 @@ address.
At a high level, STUN works like this:
- **Discovery:** Both the client and agent will send UDP traffic to one or more
- **Discovery:** Both the client and agent will send User Datagram Protocol (UDP) traffic to one or more
configured STUN servers. These STUN servers are generally located on the
public internet, and respond with the public IP address and port from which
the request came.
@@ -87,7 +87,7 @@ communicate directly with each other through their respective NATs.
### 3. Direct connections with VPN and NAT hairpinning
In this example, the client workstation must use a VPN to connect to the
In this example, the client workstation must use a virtual private network (VPN) to connect to the
corporate network. All traffic from the client will enter through the VPN entry
node and exit at the VPN exit node inside the corporate network. Traffic from
the client inside the corporate network will appear to be coming from the IP
@@ -139,7 +139,7 @@ establish or will not be established at all. If one peer is behind a "hard" NAT
and the other is running a firewall (including Windows Defender Firewall), the
firewall may block direct connections.
In both cases, peers fallback to DERP connections if they cannot establish a
In both cases, peers fallback to Designated Encrypted Relay for Packets (DERP) connections if they cannot establish a
direct connection.
If your workspaces are behind a "hard" NAT, you can:
@@ -165,7 +165,7 @@ this "easy" NAT). Linux `MASQUERADE` rules work well for this.
### AWS Elastic Kubernetes Service (EKS)
The default configuration of AWS Elastic Kubernetes Service (EKS) includes the
[Amazon VPC CNI Driver](https://github.com/aws/amazon-vpc-cni-k8s), which by
[Amazon Virtual Private Cloud (VPC) Container Network Interface (CNI) Driver](https://github.com/aws/amazon-vpc-cni-k8s), which by
default randomizes the public port for different outgoing UDP connections. This
makes it act as a "hard" NAT, even if the EKS nodes are on a public subnet (and
thus do not need to use the AWS NAT Gateway to reach the Internet).
docs/admin/networking/troubleshooting.md
+6 -6
View File
@@ -42,9 +42,9 @@ flag on the control plane. When set, this will be reflected in the output of
### UDP Blocked
Some corporate firewalls block UDP traffic. Direct connections require UDP
Some corporate firewalls block User Datagram Protocol (UDP) traffic. Direct connections require UDP
traffic to be allowed between the client and agent, as well as between the
client/agent and STUN servers in most cases. `coder ping` will indicate if
client/agent and Session Traversal Utilities for Network Address Translation (STUN) servers in most cases. `coder ping` will indicate if
either the Coder agent or client had issues sending or receiving UDP packets to
STUN servers.
@@ -55,7 +55,7 @@ for Coder workspaces, clients, and STUN servers.
Hard NATs prevent public endpoints gathered from STUN servers from being used by
the peer to establish a direct connection. Typically, if only one side of the
connection is behind a hard NAT, direct connections can still be established
connection is behind a hard Network Address Translation (NAT), direct connections can still be established
easily. However, if both sides are behind hard NATs, direct connections may take
longer to establish or may not be possible at all.
@@ -66,7 +66,7 @@ Learn more about [STUN and NAT](./stun.md).
### No STUN Servers
If there are no STUN servers available within a deployment's DERP MAP, direct
If there are no STUN servers available within a deployment's Designated Encrypted Relay for Packets (DERP) map, direct
connections may not be possible. Notable exceptions are if the client and agent
are on the same network, or if either is able to use UPnP instead of STUN to
resolve the public IP of the other. `coder ping` will indicate if no STUN
@@ -83,7 +83,7 @@ firewall, or reconfigure the hard NAT.
### VPNs
If a VPN is the default route for all IP traffic, it may interfere with the
If a virtual private network (VPN) is the default route for all IP traffic, it may interfere with the
ability for clients and agents to form direct connections. This happens if the
NAT does not permit traffic to be
['hairpinned'](./stun.md#3-direct-connections-with-vpn-and-nat-hairpinning) from
@@ -95,7 +95,7 @@ the NAT configuration, or deploy an internal STUN server.
### Low MTU
If a network interface on the side of either the client or agent has an MTU
If a network interface on the side of either the client or agent has a maximum transmission unit (MTU)
smaller than 1378, any direct connections form may have degraded quality or
might hang entirely.
docs/admin/networking/wildcard-access-url.md
+1 -1
View File
@@ -94,7 +94,7 @@ You'll need to configure DNS to point wildcard subdomains to your control plane:
*.coder.example.com A <your-coder-server-ip>
```
Or alternatively, using a CNAME record:
Or alternatively, using a canonical name (CNAME) record:
```txt
*.coder.example.com CNAME coder.example.com
docs/admin/setup/appearance.md
+1 -1
View File
@@ -39,7 +39,7 @@ Example: Adhere to government network classification requirements and notify use
## OIDC Login Button Customization
[Use environment variables to customize](../users/oidc-auth/index.md#oidc-login-customization) the text and icon on the OIDC button on the Sign In page.
[Use environment variables to customize](../users/oidc-auth/index.md#oidc-login-customization) the text and icon on the OpenID Connect (OIDC) button on the Sign In page.
## Support Links
docs/admin/setup/chat-lifecycle-hooks.md
+3 -3
View File
@@ -4,7 +4,7 @@ title: Configure chat lifecycle hooks
> [!NOTE]
> Chat lifecycle hooks are an experimental feature.
> The feature requires the `agent-lifecycle-hooks` experiment, and the consumer contract (including the request schema and JWT claims) may change or be removed in any release without a compatibility guarantee.
> The feature requires the `agent-lifecycle-hooks` experiment, and the consumer contract (including the request schema and JSON Web Token (JWT) claims) may change or be removed in any release without a compatibility guarantee.
This guide is for Coder deployment administrators who need to apply an external policy service to the agent loop.
Work through it to configure the deployment, handle events in a consumer, recover from dispatch failures, and roll out enforcement.
@@ -79,7 +79,7 @@ Provider-executed tools don't produce `pre_tool_use` or `post_tool_use` events b
For `pre_tool_use`, `tool_input` carries the model's JSON bytes with key spelling and order preserved, so a policy can read them exactly as the model wrote them.
Coder's built-in tools decode that JSON with Go, which matches property names case-insensitively and keeps the last match, so `{"path":"/allowed","PATH":"/secret"}` could make a policy approve `/allowed` while the tool opens `/secret`.
Coder rejects a built-in tool call whose input repeats a key or spells a schema property with different capitalization, before dispatching `pre_tool_use`.
This check doesn't cover dynamic and MCP tools, because the client and the workspace agent execute those calls rather than `coderd`.
This check doesn't cover dynamic and Model Context Protocol (MCP) tools, because the client and the workspace agent execute those calls rather than `coderd`.
A policy that gates them must validate their input itself.
The chat `edit_files` tool reads `old_text` and `new_text`; a policy that gates edit content must inspect those keys.
@@ -101,7 +101,7 @@ A consumer must apply all of the following checks before it uses the body:
- Compute SHA-256 over the exact request body bytes and compare it with `body_sha256`.
- Check that `sub` has the form `coder:chat:<chat ID>` and that its chat ID matches `meta.chat_id`.
The Go consumer SDK in `codersdk/x/agenthooks` implements the wire types, JWT verification, body binding, audience checks, and event routing.
The Go consumer software development kit (SDK) in `codersdk/x/agenthooks` implements the wire types, JWT verification, body binding, audience checks, and event routing.
Use `agenthooks.NewHTTPHandler` to build an `http.Handler` from callbacks for the events your consumer handles.
Pass the deployment's `CODER_CHAT_HOOK_URL` as the expected audience, because a handler built without one rejects every request.
Pass `agenthooks.WithExpectedIssuer` with the deployment ID associated with the secret to enforce the `iss` check.
docs/admin/setup/data-retention.md
+5 -5
View File
@@ -157,13 +157,13 @@ ai_gateway:
Common compliance frameworks have varying retention requirements:
- **SOC 2**:
- **System and Organization Controls (SOC) 2**:
Typically requires 1&nbsp;year of audit logs.
- **HIPAA**:
- **Health Insurance Portability and Accountability Act (HIPAA)**:
Requires 6&nbsp;years for certain records.
- **PCI DSS**:
- **Payment Card Industry Data Security Standard (PCI DSS)**:
Requires 1&nbsp;year of audit logs, with 3&nbsp;months immediately available.
- **GDPR**:
- **General Data Protection Regulation (GDPR)**:
Requires data minimization but does not specify maximum retention.
### External Log Aggregation
@@ -202,6 +202,6 @@ To monitor retention activity, enable debug logging or search your logs for entr
- [Audit Logs](../security/audit-logs.md): Learn about Audit Logs and manual purge procedures.
- [Connection Logs](../monitoring/connection-logs.md): Learn about Connection Logs and monitoring.
- [AI Gateway](../../ai-coder/ai-gateway/index.md): Learn about AI Gateway for centralized LLM and MCP proxy management.
- [AI Gateway](../../ai-coder/ai-gateway/index.md): Learn about AI Gateway for centralized large language model (LLM) and Model Context Protocol (MCP) proxy management.
- [AI Gateway Setup](../../ai-coder/ai-gateway/setup.md#data-retention): Configure AI Gateway data retention.
- [AI Gateway Monitoring](../../ai-coder/ai-gateway/monitoring.md): Monitor AI Gateway usage and metrics.
docs/admin/setup/index.md
+1 -1
View File
@@ -82,7 +82,7 @@ You must have the certificate `.key` and `.crt` files in your working directory
```
You can use a single certificate for the both the access URL and wildcard access URL.
The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
The certificate Common Name (CN) must match the wildcard domain, such as `*.example.coder.com`.
1. Reference the TLS secret in your Coder Helm chart values
docs/admin/templates/creating-templates.md
+2 -2
View File
@@ -24,7 +24,7 @@ the **Templates** page, the builder opens automatically.
The builder guides you through up to five steps:
1. **Select base infrastructure**: Choose a starter template for your target
platform (e.g. Docker, AWS EC2, Kubernetes). Each base template provides a
platform (e.g. Docker, AWS Elastic Compute Cloud (EC2), Kubernetes). Each base template provides a
working foundation with the Coder agent pre-configured.
![Select a base infrastructure template in the template builder](../../images/templatebuilder_01_bases.png)
@@ -57,7 +57,7 @@ The builder guides you through up to five steps:
After you select **Create Template**, Coder composes the Terraform
configuration server-side, validates it with `terraform init` and
`terraform validate`, and creates the template. The generated template is
standard Terraform HCL that you can edit later through the dashboard or CLI.
standard Terraform HashiCorp Configuration Language (HCL) that you can edit later through the dashboard or CLI.
> [!NOTE]
> The template builder requires outbound access to `registry.coder.com` so
docs/admin/templates/extending-templates/agent-metadata.md
+2 -2
View File
@@ -18,7 +18,7 @@ for the script declaration. With heredoc strings, you can script without messy
escape codes, just as if you were working in your terminal.
Some of the examples use the [`coder stat`](../../../reference/cli/stat/index.md)
command. This is useful for determining CPU and memory usage of the VM or
command. This is useful for determining CPU and memory usage of the virtual machine (VM) or
container that the workspace is running in, which is more accurate than resource
usage about the workspace's host.
@@ -93,7 +93,7 @@ resource "coder_agent" "main" {
You can also show agent metadata for information about the workspace's host.
[top](https://manpages.ubuntu.com/manpages/jammy/en/man1/top.1.html) is
available in most Linux distributions and provides virtual memory, CPU and IO
available in most Linux distributions and provides virtual memory, CPU and input/output (IO)
statistics. Running `top` produces output that looks like:
```txt
docs/admin/templates/extending-templates/docker-in-workspaces.md
+8 -8
View File
@@ -4,12 +4,12 @@ title: Docker in workspaces
There are a few ways to run Docker within container-based Coder workspaces.
| Method | Description | Limitations |
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Sysbox container runtime](#sysbox-container-runtime) | Install the Sysbox runtime on your Kubernetes nodes or Docker host(s) for secure docker-in-docker and systemd-in-docker. Works with GKE, EKS, AKS, Docker. | Requires [compatible nodes](https://github.com/nestybox/sysbox#host-requirements). [Limitations](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/limitations.md) |
| [Envbox](#envbox) | A container image with all the packages necessary to run an inner Sysbox container. Removes the need to setup sysbox-runc on your nodes. Works with GKE, EKS, AKS. | Requires running the outer container as privileged (the inner container that acts as the workspace is locked down). Requires compatible [nodes](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility). |
| [Rootless Podman](#rootless-podman) | Run Podman inside Coder workspaces. Does not require a custom runtime or privileged containers. Works with GKE, EKS, AKS, RKE, OpenShift | Requires smarter-device-manager for FUSE mounts. [See all](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman) |
| [Privileged docker sidecar](#privileged-sidecar-container) | Run Docker as a privileged sidecar container. | Requires a privileged container. Workspaces can break out to root on the host machine. |
| Method | Description | Limitations |
|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Sysbox container runtime](#sysbox-container-runtime) | Install the Sysbox runtime on your Kubernetes nodes or Docker host(s) for secure docker-in-docker and systemd-in-docker. Works with Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Docker. | Requires [compatible nodes](https://github.com/nestybox/sysbox#host-requirements). [Limitations](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/limitations.md) |
| [Envbox](#envbox) | A container image with all the packages necessary to run an inner Sysbox container. Removes the need to setup sysbox-runc on your nodes. Works with GKE, EKS, AKS. | Requires running the outer container as privileged (the inner container that acts as the workspace is locked down). Requires compatible [nodes](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility). |
| [Rootless Podman](#rootless-podman) | Run Podman inside Coder workspaces. Does not require a custom runtime or privileged containers. Works with GKE, EKS, AKS, Rancher Kubernetes Engine (RKE), OpenShift | Requires smarter-device-manager for Filesystem in Userspace (FUSE) mounts. [See all](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman) |
| [Privileged docker sidecar](#privileged-sidecar-container) | Run Docker as a privileged sidecar container. | Requires a privileged container. Workspaces can break out to root on the host machine. |
## Sysbox container runtime
@@ -188,7 +188,7 @@ env {
## Rootless podman
[Podman](https://docs.podman.io/en/latest/) is Docker alternative that is
compatible with OCI containers specification. which can run rootless inside
compatible with Open Container Initiative (OCI) containers specification. which can run rootless inside
Kubernetes pods. No custom RuntimeClass is required.
Before using Podman, please review the following documentation:
@@ -357,7 +357,7 @@ spec:
### Rootless Podman on EKS Auto Mode
The `EC2NodeClass` above applies to self-managed Karpenter nodes. On EKS Auto Mode, the built-in `NodeClass` (`eks.amazonaws.com`) doesn't expose `userData` or kernel sysctls, so `user.max_user_namespaces` stays at `0` with no way to raise it on those nodes. Run Podman workspaces on a separate managed node group instead; the default AL2023 AMIs ship with user namespaces enabled.
The `EC2NodeClass` above applies to self-managed Karpenter nodes. On EKS Auto Mode, the built-in `NodeClass` (`eks.amazonaws.com`) doesn't expose `userData` or kernel sysctls, so `user.max_user_namespaces` stays at `0` with no way to raise it on those nodes. Run Podman workspaces on a separate managed node group instead; the default Amazon Linux 2023 (AL2023) Amazon Machine Images (AMIs) ship with user namespaces enabled.
> On a brand-new Auto Mode cluster, install the `vpc-cni` and `kube-proxy` add-ons before your managed node group can reach `Ready`.
docs/admin/templates/extending-templates/dynamic-parameters.md
+4 -4
View File
@@ -363,7 +363,7 @@ data "coder_parameter" "environment" {
### Checkboxes
A single checkbox for boolean values.
This can be used for a TOS confirmation or to expose advanced options.
This can be used for a terms of service (TOS) confirmation or to expose advanced options.
[Try checkbox parameters on the Parameters Playground](https://playground.coder.app/parameters/ycWuQJk2Py).
@@ -682,7 +682,7 @@ data "coder_parameter" "cpu_cores" {
Premium users can leverage our roles and groups to conditionally expose or change parameters based on user identity.
This is helpful for establishing governance policy directly in the workspace creation form,
rather than creating multiple templates to manage RBAC.
rather than creating multiple templates to manage role-based access control (RBAC).
User identity is referenced in Terraform by reading the
[`coder_workspace_owner`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner) data source.
@@ -857,7 +857,7 @@ If your template's parameters do not work with Dynamic Parameters, please
### Template variables not showing up
Dynamic Parameters are GA as of [v2.25.0](https://github.com/coder/coder/releases/tag/v2.25.0). Template variables are fully supported in Dynamic Parameters.
Dynamic Parameters are generally available (GA) as of [v2.25.0](https://github.com/coder/coder/releases/tag/v2.25.0). Template variables are fully supported in Dynamic Parameters.
If you are experiencing issues with template variables, try upgrading to the latest version. Otherwise, please file an issue in our Github.
@@ -866,7 +866,7 @@ If you are experiencing issues with template variables, try upgrading to the lat
Yes, registry modules are supported with Dynamic Parameters.
Unless explicitly mentioned, no registry modules require Dynamic Parameters.
Later in 2025, more registry modules will be converted to Dynamic Parameters to improve their UX.
Later in 2025, more registry modules will be converted to Dynamic Parameters to improve their user experience (UX).
In the meantime, you can safely convert existing templates and build new parameters on top of the functionality provided in the registry.
docs/admin/templates/extending-templates/icons.md
+1 -1
View File
@@ -4,7 +4,7 @@ title: Icons
Coder uses icons in several places, including ones that can be configured
throughout the app, or specified in your Terraform. They're specified by a URL,
which can be to an image hosted on a CDN of your own, or one of the icons that
which can be to an image hosted on a content delivery network (CDN) of your own, or one of the icons that
come bundled with your Coder deployment.
- **Template Icons**:
docs/admin/templates/extending-templates/index.md
+2 -2
View File
@@ -42,7 +42,7 @@ information displayed in the dashboard's workspace view.
Multiple agents may be used in a single template or even a single resource. Each
agent may have its own apps, startup script, and metadata. This can be used to
associate multiple containers or VMs with a workspace.
associate multiple containers or virtual machines (VMs) with a workspace.
## Resource persistence
@@ -139,7 +139,7 @@ resource "coder_app" "zed" {
</div>
Check out our [module registry](https://registry.coder.com/modules) for
additional Coder apps from the team and our OSS community.
additional Coder apps from the team and our open source software (OSS) community.
## Environment variables
docs/admin/templates/extending-templates/jetbrains-airgapped.md
+1 -1
View File
@@ -60,7 +60,7 @@ We now have both clients and backends installed.
## 3. Install a web server
You will need to run a web server in order to serve requests to the backend and
client files. We installed `nginx` and setup an FQDN and routed all requests to
client files. We installed `nginx` and setup a fully qualified domain name (FQDN) and routed all requests to
`/`. See below:
```console
docs/admin/templates/extending-templates/modules.md
+1 -1
View File
@@ -165,7 +165,7 @@ In GitHub, you can generate a
[fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)
with read only access to the necessary repos.
If you are running Coder on a VM, make sure that you have `git` installed and
If you are running Coder on a virtual machine (VM), make sure that you have `git` installed and
the `coder` user has access to the following files:
```sh
docs/admin/templates/extending-templates/parameters.md
+1 -1
View File
@@ -341,7 +341,7 @@ workspace presets with optional `description` and `icon` fields:
to use it.
- **icon**: A visual icon displayed alongside the preset name in the UI. Use
emoji icons with the format `/emojis/{code}.png` (e.g.,
`/emojis/1f1fa-1f1f8.png` for the US flag emoji 🇺🇸).
`/emojis/1f1fa-1f1f8.png` for the United States (US) flag emoji 🇺🇸).
For a complete list of all available fields, see the
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_preset#schema).
docs/admin/templates/extending-templates/prebuilt-workspaces.md
+3 -3
View File
@@ -18,7 +18,7 @@ Prebuilt workspaces are:
- Automatically scaled based on time-based schedules to optimize resource usage.
Prebuilt workspaces are a special type of workspace that don't follow the
[regular workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. Instead, they have their own reconciliation loop that handles prebuild-specific scheduling features such as TTL and prebuild scheduling.
[regular workspace scheduling features](../../../user-guides/workspace-scheduling.md) like autostart and autostop. Instead, they have their own reconciliation loop that handles prebuild-specific scheduling features such as time to live (TTL) and prebuild scheduling.
## Relationship to workspace presets
@@ -225,7 +225,7 @@ When a template's active version is updated:
1. Prebuilt workspaces for old versions are automatically deleted.
1. New prebuilt workspaces are created for the active template version.
1. If dependencies change (e.g., an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) update) without a template version change:
1. If dependencies change (e.g., an [Amazon Machine Image (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) update) without a template version change:
- You can delete the existing prebuilt workspaces manually.
- Coder will automatically create new prebuilt workspaces with the updated dependencies.
@@ -239,7 +239,7 @@ When external dependencies change without a template version update, you can inv
This is useful when:
- A base VM image or container image has been updated externally
- A base virtual machine (VM) image or container image has been updated externally
- Infrastructure configuration has drifted from the desired state
- A monorepo cloned during the prebuild has fallen behind its origin
- You want to ensure prebuilt workspaces use the latest dependencies without publishing a new template version
docs/admin/templates/extending-templates/process-priority.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Improve agent resiliency
---
Coder's agent can automatically lower the scheduling priority
and raise the OOM (out-of-memory) kill score of user processes
and raise the out-of-memory (OOM) kill score of user processes
so the agent itself stays alive under resource pressure.
## Prerequisites
docs/admin/templates/extending-templates/provider-authentication.md
+3 -3
View File
@@ -26,10 +26,10 @@ Generally, you can set up an environment to provide credentials to Coder in
these ways:
- A well-known location on disk. For example, `~/.aws/credentials` for AWS on
POSIX systems.
Portable Operating System Interface (POSIX) systems.
- Environment variables.
It is usually sufficient to authenticate using the CLI or SDK for the provider
It is usually sufficient to authenticate using the CLI or software development kit (SDK) for the provider
before running Coder, but check the Terraform provider's documentation for
details.
@@ -47,7 +47,7 @@ environments:
There are two ways to use a remote Docker host for authentication:
- Configure the Docker provider to use a
[remote host over SSH or TCP](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts).
[remote host over SSH or Transmission Control Protocol (TCP)](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts).
- Run an [external provisioner](../../../install/operate/provisioners/index.md) on the remote docker
host.
docs/admin/templates/extending-templates/resource-monitoring.md
+1 -1
View File
@@ -16,7 +16,7 @@ OOM alerts are reported per-agent.
## Prerequisites
Notifications are sent through SMTP.
Notifications are sent through Simple Mail Transfer Protocol (SMTP).
Configure Coder to [use an SMTP server](../../monitoring/notifications/index.md#smtp-email).
## Example
docs/admin/templates/extending-templates/web-ides.md
+1 -1
View File
@@ -55,7 +55,7 @@ resource "coder_agent" "main" {
}
```
For advanced use, we recommend installing code-server in your VM snapshot or
For advanced use, we recommend installing code-server in your virtual machine (VM) snapshot or
container image. Here's a Dockerfile which leverages some special
[code-server features](https://coder.com/docs/code-server):
docs/admin/templates/extending-templates/workspace-tags.md
+1 -1
View File
@@ -35,7 +35,7 @@ data "coder_workspace_tags" "custom_workspace_tags" {
provisioner runtime, `runtime_selector`
- `project_id` - a formatted string supported by the string-type
`coder_parameter`, `project_name`
- `cache` - an HCL condition involving boolean-type `coder_parameter`,
- `cache` - a HashiCorp Configuration Language (HCL) condition involving boolean-type `coder_parameter`,
`feature_cache_enabled`
Review the
docs/admin/templates/index.md
+1 -1
View File
@@ -37,7 +37,7 @@ users. Common modifications are:
[Image management](./managing-templates/image-management.md).
- Additional parameters (e.g. disk size, instance type, or region). Docs:
[Template parameters](./extending-templates/parameters.md).
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs:
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, Remote Desktop Protocol (RDP)). Docs:
[Adding IDEs and features](./extending-templates/index.md).
Learn more about the various ways you can
docs/admin/templates/managing-templates/change-management.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Template change management
---
We recommend source-controlling your templates as you would other any code, and
automating the creation of new versions in CI/CD pipelines.
automating the creation of new versions in continuous integration and continuous delivery (CI/CD) pipelines.
These pipelines will require tokens for your deployment. To cap token lifetime
on creation,
docs/admin/templates/managing-templates/dependencies.md
+1 -1
View File
@@ -98,7 +98,7 @@ file will be stored alongside with the other template source code.
> [!NOTE]
> Terraform best practices also recommend checking in your
> `.terraform.lock.hcl` into Git or other VCS.
> `.terraform.lock.hcl` into Git or other version control system (VCS).
The next time a workspace is built from that template, Coder will make sure to
use the same versions of those providers as specified in the lock file.
docs/admin/templates/managing-templates/external-workspaces.md
+3 -3
View File
@@ -10,7 +10,7 @@ External workspaces allow you to seamlessly connect externally managed infrastru
- **Windows**: amd64 or arm64 architecture
- **Linux**: amd64, arm64, or armv7 architecture
- **macOS**: amd64 or arm64 architecture
- **Examples**: VMs, bare-metal servers, Kubernetes nodes, or any machine meeting the above requirements.
- **Examples**: Virtual machines (VMs), bare-metal servers, Kubernetes nodes, or any machine meeting the above requirements.
- Networking access to your Coder deployment.
- A workspace template that includes a [`coder_external_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/external_agent) resource.
@@ -26,11 +26,11 @@ External workspaces offer flexibility and control in complex environments:
- **Flexibility**
Attach cloud, hybrid, or on-premises machines as developer workspaces. This enables connecting existing on-premises GPU servers for ML development or bringing manually provisioned VMs in restricted networks under Coder's workspace management.
Attach cloud, hybrid, or on-premises machines as developer workspaces. This enables connecting existing on-premises graphics processing unit (GPU) servers for machine learning (ML) development or bringing manually provisioned VMs in restricted networks under Coder's workspace management.
- **Separation of concerns**
Provision compute resources externally (using your existing IaC or manual processes) while managing workspace configuration (apps, scripts) with Terraform. This approach is ideal for running agents in CI pipelines to provision short-lived, externally managed workspaces for testing or build automation.
Provision compute resources externally (using your existing IaC or manual processes) while managing workspace configuration (apps, scripts) with Terraform. This approach is ideal for running agents in continuous integration (CI) pipelines to provision short-lived, externally managed workspaces for testing or build automation.
## Known limitations
docs/admin/templates/managing-templates/index.md
+1 -1
View File
@@ -28,7 +28,7 @@ configuring template settings without writing Terraform.
Starter templates for common cloud providers (AWS, Azure) and orchestrators
(Kubernetes, Docker) are available as base templates within the builder. You can
modify the generated template to use your own images, VPC, cloud credentials,
modify the generated template to use your own images, virtual private cloud (VPC), cloud credentials,
and so on. Coder supports all Terraform resources and properties.
If you prefer to use Coder on the
docs/admin/templates/managing-templates/schedule.md
+1 -1
View File
@@ -112,7 +112,7 @@ Admins can define the default quiet hours for all users with the
environment variable. The value should be a cron expression such as
`CRON_TZ=America/Chicago 30 2 * * *` which would set the default quiet hours to
2:30 AM in the America/Chicago timezone. The cron schedule can only have a
minute and hour component. The default schedule is UTC 00:00. It is recommended
minute and hour component. The default schedule is Coordinated Universal Time (UTC) 00:00. It is recommended
to set the default quiet hours to a time when most users are not expected to be
using Coder.
docs/admin/users/github-auth.md
+1 -1
View File
@@ -149,7 +149,7 @@ For GitHub Enterprise support, also set
> [configuration reference](../setup/configuration-reference.md) for the
> full mapping between environment variables and flags.
We recommend requiring and auditing MFA usage for all users in your GitHub organizations.
We recommend requiring and auditing multi-factor authentication (MFA) usage for all users in your GitHub organizations.
This can be enforced from the organization settings page in the **Authentication security** sidebar tab.
## Device Flow
docs/admin/users/groups-roles.md
+1 -1
View File
@@ -128,5 +128,5 @@ or shuts down the control plane. To avoid this, run
In low-trust environments, we do not recommend giving users direct access to
edit templates. Instead, use
[CI/CD pipelines to update templates](../templates/managing-templates/change-management.md)
[Continuous integration and continuous delivery (CI/CD) pipelines to update templates](../templates/managing-templates/change-management.md)
with proper security scans and code reviews in place.
docs/admin/users/headless-auth.md
+1 -1
View File
@@ -7,7 +7,7 @@ title: Headless authentication
Service accounts are headless user accounts that cannot use the web UI to log in
to Coder. This is useful for creating accounts for automated systems, such as
CI/CD pipelines or for users who only consume Coder via another client/API. Service accounts do not have passwords or associated email addresses.
Continuous integration and continuous delivery (CI/CD) pipelines or for users who only consume Coder via another client/API. Service accounts do not have passwords or associated email addresses.
You must have the User Admin role or above to create service accounts.
docs/admin/users/idp-sync.md
+9 -9
View File
@@ -399,11 +399,11 @@ settings, a user's memberships will update when they log out and log back in.
Analyzing the JSON payload:
| Field | Explanation |
|:----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| field | If this field is the empty string `""`, then org-sync is disabled. <br /> Org memberships must be manually configured through the UI or API. |
| mapping | Mapping takes a claim from the IdP, and associates it with 1 or more organizations by UUID. <br /> No validation is done, so you can put UUID's of orgs that do not exist (a noop). The UI picker will allow selecting orgs from a drop down, and convert it to a UUID for you. |
| organization_assign_default | This setting exists for maintaining backwards compatibility with single org deployments, either through their upgrade, or in perpetuity. <br /> If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims. |
| Field | Explanation |
|:----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| field | If this field is the empty string `""`, then org-sync is disabled. <br /> Org memberships must be manually configured through the UI or API. |
| mapping | Mapping takes a claim from the IdP, and associates it with 1 or more organizations by universally unique identifier (UUID). <br /> No validation is done, so you can put UUID's of orgs that do not exist (a noop). The UI picker will allow selecting orgs from a drop down, and convert it to a UUID for you. |
| organization_assign_default | This setting exists for maintaining backwards compatibility with single org deployments, either through their upgrade, or in perpetuity. <br /> If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims. |
</div>
@@ -492,7 +492,7 @@ The application '<oidc_application>' asked for scope 'groups' that doesn't exist
```
This can happen because the identity provider has a different name for the
scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`.
scope. For example, Azure Active Directory (AD) uses `GroupMember.Read.All` instead of `groups`.
You can find the correct scope name in the IdP's documentation. Some IdPs allow
configuring the name of this scope.
@@ -522,7 +522,7 @@ Steps to troubleshoot.
### Active Directory Federation Services (ADFS)
> [!NOTE]
> Tested on ADFS 4.0, Windows Server 2019
> Tested on Active Directory Federation Services (ADFS) 4.0, Windows Server 2019
1. In your Federation Server, create a new application group for Coder.
Follow the steps as described in the [Windows Server documentation]
@@ -553,7 +553,7 @@ Steps to troubleshoot.
```
Where `$CLIENT_ID` is the Client ID from step 1.
Consult the Microsoft [AD FS OpenID Connect/OAuth flows and Application Scenarios documentation](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional) for more information.
Consult the Microsoft [Active Directory Federation Services (AD FS) OpenID Connect/OAuth flows and Application Scenarios documentation](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional) for more information.
This is required for the upstream OIDC provider to return the requested
claims.
@@ -565,7 +565,7 @@ Steps to troubleshoot.
on your Federation Server to send the following claims:
- `preferred_username`: You can use e.g. "Display Name" as required.
- `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as
- `email`: You can use e.g. the Lightweight Directory Access Protocol (LDAP) attribute "E-Mail-Addresses" as
required.
- `email_verified`: Create a custom claim rule:
docs/admin/users/index.md
+2 -2
View File
@@ -3,7 +3,7 @@ title: Users
---
By default, Coder is accessible via password authentication. For production
deployments, we recommend using an SSO authentication provider with multi-factor
deployments, we recommend using a single sign-on (SSO) authentication provider with multi-factor
authentication (MFA). It is your responsibility to ensure the auth provider
enforces MFA correctly.
@@ -11,7 +11,7 @@ enforces MFA correctly.
## Configure SSO
- [OpenID Connect](./oidc-auth/index.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
- [OpenID Connect](./oidc-auth/index.md) (e.g. Okta, KeyCloak, PingFederate, Azure Active Directory (AD))
- [GitHub](./github-auth.md) (or GitHub Enterprise)
## Groups
docs/admin/users/oidc-auth/google.md
+1 -1
View File
@@ -13,7 +13,7 @@ This guide shows how to configure Coder to authenticate users with Google using
1. Open Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Web application.
3. Authorized redirect URIs: add your Coder callback URL:
3. Authorized redirect Uniform Resource Identifiers (URIs): add your Coder callback URL:
- `https://coder.example.com/api/v2/users/oidc/callback`
4. Save and note the Client ID and Client secret.
docs/admin/users/oidc-auth/index.md
+4 -4
View File
@@ -7,9 +7,9 @@ Active Directory, etc.) to Coder.
## Step 1: Set Redirect URI with your OIDC provider
Your OIDC provider will ask you for the following parameter:
Your OpenID Connect (OIDC) provider will ask you for the following parameter:
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
- **Redirect URI**: Set the redirect Uniform Resource Identifier (URI) to `https://coder.domain.com/api/v2/users/oidc/callback`
## Step 2: Configure Coder with the OpenID Connect credentials
@@ -139,7 +139,7 @@ CODER_DISABLE_PASSWORD_AUTH=true
## SCIM
> [!IMPORTANT]
> SCIM is a Premium feature
> System for Cross-domain Identity Management (SCIM) is a Premium feature
> ([learn more](https://coder.com/pricing#compare-plans)).
>
> Coder's SCIM 2.0 implementation is not a fully certified or guaranteed
@@ -165,7 +165,7 @@ CODER_SCIM_AUTH_HEADER="your-api-key"
### SCIM 2.0 handler
Coder includes an opt-in SCIM 2.0 handler that follows [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) and has been verified against an external SCIM 2.0 compliance suite.
Coder includes an opt-in SCIM 2.0 handler that follows [Request for Comments (RFC) 7644](https://datatracker.ietf.org/doc/html/rfc7644) and has been verified against an external SCIM 2.0 compliance suite.
It supports the following:
- User provisioning and deprovisioning
docs/admin/users/oidc-auth/microsoft.md
+1 -1
View File
@@ -19,7 +19,7 @@ This guide shows how to configure Coder to authenticate users with Microsoft Ent
6. Select "New Client Secret" and under description, enter an appropriate description. Then set an expiry and hit "Add" once it's created, copy the value and save it somewhere secure for the next step
7. Next, select the tab labeled "Token Configuration", then select "Add optional claim" and select the "ID" radio button, and finally check "upn" and hit "add" at the bottom
8. Then, select the button labeled "Add groups claim" and check "Security groups" and select "Save" at the bottom
9. Now, select the tab labeled "Authentication" and select "Add a platform", select "Web" and for the redirect URI enter your Coder callback URL, and then hit "Configure" at the bottom:
9. Now, select the tab labeled "Authentication" and select "Add a platform", select "Web" and for the redirect Uniform Resource Identifier (URI) enter your Coder callback URL, and then hit "Configure" at the bottom:
- `https://coder.example.com/api/v2/users/oidc/callback`
## Step 2: Configure Coder OIDC for Microsoft Entra ID
docs/admin/users/oidc-auth/refresh-tokens.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: Configure OIDC refresh tokens
---
OIDC refresh tokens allow your Coder deployment to maintain user sessions beyond the initial access token expiration.
OpenID Connect (OIDC) refresh tokens allow your Coder deployment to maintain user sessions beyond the initial access token expiration.
Without properly configured refresh tokens, users will be automatically logged out when their access token expires.
This is typically after one hour, but varies by provider, and can disrupt the user's workflow.
docs/admin/users/sessions-tokens.md
+1 -1
View File
@@ -160,7 +160,7 @@ Coder accepts deprecated scope names for backward compatibility. Refer to the [D
### Allow lists (advanced)
For additional security, you can combine scopes with allow lists to restrict tokens to specific resources. Allow lists let you limit a token to only interact with particular workspaces, templates, or other resources by their UUID:
For additional security, you can combine scopes with allow lists to restrict tokens to specific resources. Allow lists let you limit a token to only interact with particular workspaces, templates, or other resources by their universally unique identifier (UUID):
```sh
# Create a token limited to a specific workspace
docs/ai-coder/agent-firewall/index.md
+11 -11
View File
@@ -108,7 +108,7 @@ module "agent-firewall" {
- `INFO`: logs all requests at a high level
- `DEBUG`: logs all requests in detail
- `no_user_namespace` disables creation of a user namespace inside the jail.
Enable this in restricted environments that disallow user namespaces, such as Bottlerocket nodes in EKS auto-mode.
Enable this in restricted environments that disallow user namespaces, such as Bottlerocket nodes in Amazon Elastic Kubernetes Service (EKS) auto-mode.
Only applies to the `nsjail` jail type.
- `proxy_port` defines the port used by the HTTP proxy.
Default: `8080`.
@@ -146,15 +146,15 @@ Landjail may be preferred in environments where namespace capabilities are limit
## Implementation Comparison: Namespaces+iptables vs Landlock V4
| Aspect | Namespace Jail (Namespaces + veth-pair + iptables) | Landlock V4 Jail |
|-------------------------------|-----------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| **Privileges** | Requires `CAP_NET_ADMIN` | ✅ No special capabilities required |
| **Docker seccomp** | ❌ Requires seccomp profile modifications or sysbox-runc | ✅ Works without seccomp changes |
| **Kernel requirements** | Linux 3.8+ (widely available) | ❌ Linux 6.7+ (very new, limited adoption) |
| **Bypass resistance** | ✅ Strong - transparent interception prevents bypass | ❌ **Medium - can bypass by connecting to `evil.com:<HTTP_PROXY_PORT>`** |
| **Process isolation** | ✅ PID namespace (processes can't see/kill others); **implementation in-progress** | ❌ No PID namespace (agent can kill other processes) |
| **Non-TCP traffic control** | ✅ Can block/control UDP via iptables; **implementation in-progress** | ❌ No control over UDP (data can leak via UDP) |
| **Application compatibility** | ✅ Works with ANY application (transparent interception) | ❌ Tools without `HTTP_PROXY` support will be blocked |
| Aspect | Namespace Jail (Namespaces + veth-pair + iptables) | Landlock V4 Jail |
|-------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| **Privileges** | Requires `CAP_NET_ADMIN` | ✅ No special capabilities required |
| **Docker seccomp** | ❌ Requires seccomp profile modifications or sysbox-runc | ✅ Works without seccomp changes |
| **Kernel requirements** | Linux 3.8+ (widely available) | ❌ Linux 6.7+ (very new, limited adoption) |
| **Bypass resistance** | ✅ Strong - transparent interception prevents bypass | ❌ **Medium - can bypass by connecting to `evil.com:<HTTP_PROXY_PORT>`** |
| **Process isolation** | ✅ process ID (PID) namespace (processes can't see/kill others); **implementation in-progress** | ❌ No PID namespace (agent can kill other processes) |
| **Non-Transmission Control Protocol (TCP) traffic control** | ✅ Can block/control User Datagram Protocol (UDP) via iptables; **implementation in-progress** | ❌ No control over UDP (data can leak via UDP) |
| **Application compatibility** | ✅ Works with ANY application (transparent interception) | ❌ Tools without `HTTP_PROXY` support will be blocked |
## Audit Logs
@@ -180,7 +180,7 @@ Each Agent Firewall audit log entry includes:
| Field | Description |
|-----------------------|-----------------------------------------------------------------------------------------|
| `decision` | Whether the request was allowed (`allow`) or blocked (`deny`) |
| `workspace_id` | The UUID of the workspace where the request originated |
| `workspace_id` | The universally unique identifier (UUID) of the workspace where the request originated |
| `workspace_name` | The name of the workspace where the request originated |
| `owner` | The owner of the workspace where the request originated |
| `template_id` | The UUID of the template that the workspace was created from |
docs/ai-coder/agent-firewall/nsjail/docker.md
+1 -1
View File
@@ -12,7 +12,7 @@ For an overview of nsjail, see [nsjail](./index.md).
## Runtime & Permission Requirements for Running Boundary in Docker
This section describes the Linux capabilities and runtime configurations required to run Agent Firewall with nsjail inside a Docker container.
Requirements vary depending on the OCI runtime and the seccomp profile in use.
Requirements vary depending on the Open Container Initiative (OCI) runtime and the seccomp profile in use.
### 1. Default `runc` runtime with `CAP_NET_ADMIN`
docs/ai-coder/agent-firewall/nsjail/ecs.md
+2 -2
View File
@@ -5,13 +5,13 @@ title: nsjail on ECS
> [!NOTE]
> Agent Firewall is part of [AI Governance](../../ai-governance.md), which is included with a Premium license.
This page describes the runtime and permission requirements for running Agent Firewall with the **nsjail** jail type on **Amazon ECS**.
This page describes the runtime and permission requirements for running Agent Firewall with the **nsjail** jail type on **Amazon Elastic Container Service (ECS)**.
## Runtime & Permission Requirements for Running Agent Firewall in ECS
The setup for ECS is similar to [nsjail on Kubernetes](./k8s.md); that environment is better explored and tested, so the Kubernetes page is a useful reference.
On ECS, requirements depend on the node OS and how ECS runs your tasks.
The following examples use **ECS with Self Managed Node Groups** (EC2 launch type).
The following examples use **ECS with Self Managed Node Groups** (Amazon Elastic Compute Cloud (EC2) launch type).
---
docs/ai-coder/agent-firewall/nsjail/index.md
+1 -1
View File
@@ -8,7 +8,7 @@ title: nsjail jail type
nsjail is Agent Firewall's default jail type that uses Linux namespaces to provide process isolation.
It creates unprivileged network namespaces to control and monitor network access for processes running under Boundary.
**Running on Docker, Kubernetes, or ECS?**
**Running on Docker, Kubernetes, or Amazon Elastic Container Service (ECS)?**
See the relevant page for runtime and permission requirements:
- [nsjail on Docker](./docker.md)
docs/ai-coder/agent-firewall/nsjail/k8s.md
+2 -2
View File
@@ -10,7 +10,7 @@ This page describes the runtime and permission requirements for running Agent Fi
## Runtime & Permission Requirements for Running Boundary in Kubernetes
Requirements depend on the node OS and the container runtime.
The following examples use **EKS with Managed Node Groups** for two common node AMIs.
The following examples use **Amazon Elastic Kubernetes Service (EKS) with Managed Node Groups** for two common node Amazon Machine Images (AMIs).
---
@@ -122,6 +122,6 @@ Use this when you have no way to allow user namespace creation.
### Example 3: EKS + Fargate (Firecracker VMs)
nsjail is not currently supported on **EKS Fargate** (Firecracker-based VMs), which blocks the capabilities needed for nsjail.
nsjail is not currently supported on **EKS Fargate** (Firecracker-based virtual machines (VMs)), which blocks the capabilities needed for nsjail.
If you run on Fargate, we recommend using [landjail](../landjail.md) instead, provided kernel version supports it (Linux 6.7+).
docs/ai-coder/agent-relay/index.md
+1 -1
View File
@@ -25,7 +25,7 @@ Those stay with the cloud provider.
Agent Relay is not:
- A replacement for [Coder Agents](../agents/index.md), Coder's own AI workflow infrastructure that runs its native agent loop inside the Coder control plane and calls out to your configured LLM provider for inference.
- A replacement for [Coder Agents](../agents/index.md), Coder's own AI workflow infrastructure that runs its native agent loop inside the Coder control plane and calls out to your configured large language model (LLM) provider for inference.
- A proxy or observability layer for a provider's AI inference.
Coder has no access to model selection or token usage for sessions that run through Agent Relay.
- A self-hosted deployment of a cloud provider's control plane.
docs/ai-coder/agents/architecture.md
+5 -5
View File
@@ -11,7 +11,7 @@ If your developers can already connect to their workspaces, the agent can too.
Three components are involved in every agent interaction:
1. **The control plane** runs the agent loop.
It receives prompts, streams them to the LLM provider, interprets tool calls, and dispatches them to workspaces.
It receives prompts, streams them to the large language model (LLM) provider, interprets tool calls, and dispatches them to workspaces.
1. **The LLM provider** (Anthropic, OpenAI, Google, Azure, AWS Bedrock, or any OpenAI-compatible endpoint) performs model inference.
It never communicates with the workspace directly.
1. **The workspace** is standard compute infrastructure.
@@ -27,7 +27,7 @@ When a developer opens a web terminal in the Coder dashboard, connects via VS Co
1. The client connects to the control plane.
1. The control plane routes the connection through its internal Tailnet node.
1. The connection reaches the workspace daemon over a DERP relay or direct peer-to-peer link.
1. The connection reaches the workspace daemon over a Designated Encrypted Relay for Packets (DERP) relay or direct peer-to-peer link.
1. The workspace daemon handles the request (spawning a shell, forwarding a port, or serving a file).
When the agent executes a tool call (reading a file, running a command, writing code), it follows the same tunnel:
@@ -95,7 +95,7 @@ There is no need to wait for a response before providing additional context or r
Tools are how the agent takes action.
Each tool call from the LLM translates to a concrete operation, either inside a workspace or within the control plane itself.
The agent is restricted to the built-in tool set defined in this section, plus any additional tools from workspace skills and MCP servers.
The agent is restricted to the built-in tool set defined in this section, plus any additional tools from workspace skills and Model Context Protocol (MCP) servers.
Skills provide structured instructions the agent loads on demand (see [Extending Agents](./extending-agents.md)).
MCP tools come from admin-configured external servers (see [MCP Servers](./platform-controls/mcp-servers.md)) and from workspace `.mcp.json` files.
The agent has no direct access to the Coder API beyond what these tools expose and cannot execute arbitrary operations against the control plane.
@@ -127,8 +127,8 @@ They traverse the same Tailnet tunnel used by web terminals and IDE connections.
#### Windows workspace shell requirement
Coder Agents run workspace commands through a POSIX-compatible shell (`sh`).
Windows workspaces must provide `sh` on `PATH`, for example from [Git for Windows](https://gitforwindows.org/) (Git Bash), MSYS2, or WSL.
Coder Agents run workspace commands through a Portable Operating System Interface (POSIX)-compatible shell (`sh`).
Windows workspaces must provide `sh` on `PATH`, for example from [Git for Windows](https://gitforwindows.org/) (Git Bash), MSYS2, or Windows Subsystem for Linux (WSL).
PowerShell alone cannot run the `execute` tool.
After installing a shell, restart the workspace to pick up the updated `PATH`.
docs/ai-coder/agents/extending-agents.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: Extending agents
---
Workspace templates can extend the agent with custom skills and MCP tools.
Workspace templates can extend the agent with custom skills and Model Context Protocol (MCP) tools.
These mechanisms let platform teams provide repository-specific instructions, domain expertise, and external tool integrations without modifying the agent itself.
## How the workspace shares context with chats
docs/ai-coder/agents/getting-started.md
+3 -3
View File
@@ -9,7 +9,7 @@ This guide walks platform teams and administrators through setting up Coder Agen
Before you begin, confirm the following:
- **Coder deployment** running the latest release.
- **LLM provider credentials**:
- **Large language model (LLM) provider credentials**:
an API key for at least one [supported provider](./models.md) (Anthropic, OpenAI, Google, Azure OpenAI, AWS Bedrock, OpenAI Compatible, OpenRouter, or Vercel AI Gateway).
- **Network access** from the control plane to your LLM provider.
Workspaces do not need LLM access.
@@ -34,7 +34,7 @@ Before you begin, confirm the following:
> Coder enables the edit controls for the organization that you select.
> Coder shows the deployment settings only to deployment administrators.
> Users with model access can view the relevant Models and Coder Agents pages.
> Users with MCP server access can open the MCP servers page.
> Users with Model Context Protocol (MCP) server access can open the MCP servers page.
To configure Coder Agents:
@@ -224,7 +224,7 @@ The agent is a force multiplier, not a replacement for developer judgment.
The [Chats API](../../reference/api/chats.md) enables programmatic access to Coder Agents.
This is useful for building automations such as:
- Triggering Coder Agents from CI/CD pipelines when builds fail.
- Triggering Coder Agents from continuous integration and continuous delivery (CI/CD) pipelines when builds fail.
- Creating Coder Agents from GitHub webhooks on new issues or PRs.
- Building internal tools or dashboards on top of the API.
- Scripting batch operations across repositories.
docs/ai-coder/agents/index.md
+8 -8
View File
@@ -8,7 +8,7 @@ Developers describe the work they want done, and Coder Agents handles selecting
Coder Agents includes its own self-hosted AI coding agent that runs the agent loop directly within the Coder control plane.
No specialized software, API keys, or network access is required inside your workspace.
The only requirement is network access between the control plane and external LLM providers.
The only requirement is network access between the control plane and external large language model (LLM) providers.
<video autoplay controls muted playsinline loop>
<source src="https://raw.githubusercontent.com/coder/coder/refs/heads/main/docs/images/guides/ai-agents/coder-agents-ui.mp4" type="video/mp4">
@@ -66,7 +66,7 @@ It makes outbound requests to LLM providers and connects to workspaces only when
Not every chat requires a workspace.
The agent uses the conversation and available tools when they're sufficient for your request.
If missing tools, skills, MCP integrations, or context block progress, the agent creates a suitable workspace and uses its capabilities to continue.
If missing tools, skills, Model Context Protocol (MCP) integrations, or context block progress, the agent creates a suitable workspace and uses its capabilities to continue.
Workspaces also support reading code, running commands, and editing files.
Requests to fix a bug or build an app authorize the necessary workspace setup; you don't need to ask for a workspace separately.
Questions and self-contained code examples don't need a workspace when the conversation and available tools are sufficient.
@@ -95,12 +95,12 @@ Creating a workspace doesn't change the current mode's tool restrictions: worksp
Workspace skills, MCP tools, and context can finish loading after the workspace reports ready.
The agent can continue with available file and shell tools, but provisioning doesn't guarantee immediate access to a missing MCP tool.
| No workspace needed | Workspace provisioned |
|------------------------------------------------------|----------------------------------------------------------|
| "What are the tradeoffs between REST and gRPC?" | "Find and fix the nil pointer crash in the auth service" |
| "Help me draft an RFC for adding a caching layer" | "Run the test suite and fix any failures" |
| "What's the best way to handle retry logic in Go?" | "Refactor the handler to use the new SDK types" |
| "Compare connection pooling strategies for Postgres" | "Read the config file and add the new feature flag" |
| No workspace needed | Workspace provisioned |
|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| "What are the tradeoffs between Representational State Transfer (REST) and gRPC?" | "Find and fix the nil pointer crash in the auth service" |
| "Help me draft a Request for Comments (RFC) for adding a caching layer" | "Run the test suite and fix any failures" |
| "What's the best way to handle retry logic in Go?" | "Refactor the handler to use the new software development kit (SDK) types" |
| "Compare connection pooling strategies for Postgres" | "Read the config file and add the new feature flag" |
### Sub-agents
docs/ai-coder/agents/licensing-usage.md
+2 -2
View File
@@ -56,7 +56,7 @@ Coder sends deployment administrators an in-app soft warning as the deployment a
## Agent Time usage reporting
Coder reports Agent Time usage to Tallyman, a Coder-managed server used for billing and reporting.
Coder sends the total Coder Agents runtime consumed per UTC hour, in milliseconds, with your deployment ID.
Coder sends the total Coder Agents runtime consumed per Coordinated Universal Time (UTC) hour, in milliseconds, with your deployment ID.
Coder doesn't send user-identifiable information or additional chat data to Tallyman.
Coder also shares the reported usage with [Metronome](https://metronome.com), a Stripe product and Coder partner for usage-based billing and reporting.
@@ -71,7 +71,7 @@ A successful request produces a debug log similar to the following example when
[debu] published usage events to tallyman accepted=1 rejected=0
```
Coder sends the license JWT and deployment ID as request headers.
Coder sends the license JSON Web Token (JWT) and deployment ID as request headers.
The request body contains one `hb_agent_runtime_v1` event for each UTC hour.
The `runtime_ms` value is the total Agent Time recorded during that hour.
Idle hours have a value of `0`.
docs/ai-coder/agents/models.md
+12 -12
View File
@@ -2,7 +2,7 @@
title: Models
---
Administrators configure LLM providers from **Admin settings** > **AI** and Coder Agents models from **Admin settings** > **AI** > **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.
@@ -18,16 +18,16 @@ Each LLM provider has a type, credentials, and an endpoint/base URL for the upst
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 |
| 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 software development kit (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.
@@ -147,7 +147,7 @@ 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 UUID, so 2 providers of the same type can have different availability.
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.
docs/ai-coder/agents/platform-controls/agent-isolation.md
+4 -4
View File
@@ -31,7 +31,7 @@ You need:
- A Linux cluster with NetworkPolicy enforcement turned on for standalone Pods.
- A default storage class that provides a volume writable by user and group ID `1000`.
- A fixed IPv4 address and TCP port for Coder, including agent downloads and relay connections.
- A fixed IPv4 address and Transmission Control Protocol (TCP) port for Coder, including agent downloads and relay connections.
- A Coder provisioner with permission to create Pods, a PVC, a ConfigMap, and a NetworkPolicy in that namespace.
Check these permissions using the provisioner's Kubernetes credentials:
@@ -50,8 +50,8 @@ The provisioner also needs permission to read, update, and delete these resource
> Do not run untrusted code until the network tests pass.
> Kubernetes can accept a NetworkPolicy without enforcing it, leaving the agent's network access unrestricted.
For GKE, check [network policy enforcement](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy).
For Amazon VPC CNI, use Deployment-managed Pods instead of this example's standalone Pods.
For Google Kubernetes Engine (GKE), check [network policy enforcement](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy).
For Amazon Virtual Private Cloud (VPC) Container Network Interface (CNI), use Deployment-managed Pods instead of this example's standalone Pods.
[AWS documents unreliable enforcement for standalone Pods](https://docs.aws.amazon.com/eks/latest/userguide/cni-network-policy.html).
Save this Terraform as `main.tf` in an empty template directory.
@@ -403,7 +403,7 @@ Your network plugin can also allow traffic to the node or its local DNS service.
Review these exceptions in the [Kubernetes NetworkPolicy documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/).
The agent can read any credentials you give it, edit shared files, and send data to Coder.
Keep workspace MCP configuration outside the shared project.
Keep workspace Model Context Protocol (MCP) configuration outside the shared project.
This policy does not restrict organization MCP servers.
Restrict their tools and credentials separately.
docs/ai-coder/agents/platform-controls/chat-auto-archive.md
+1 -1
View File
@@ -8,7 +8,7 @@ Archived conversations are still visible (and can be unarchived) until they age
## How it works
The Coder Agents chat worker scans the chat database once an hour for root conversations where the most recent non-deleted message predates the configured auto-archive window, and flips them from "active" to "archived".
Eligibility is evaluated at UTC day boundaries: all conversations with last activity falling on the same UTC date are archived together on the first tick after midnight UTC following the expiration of their archive window.
Eligibility is evaluated at Coordinated Universal Time (UTC) day boundaries: all conversations with last activity falling on the same UTC date are archived together on the first tick after midnight UTC following the expiration of their archive window.
Cascaded child chats are archived alongside their parent so the conversation stays coherent.
Activity is defined as the most recent non-deleted message in the conversation family, counting messages from every role.
docs/ai-coder/agents/platform-controls/chat-debug-logging.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: Chat debug logging
---
Records a detailed trace of each chat turn for troubleshooting: the normalized request sent to the LLM provider, the full response, token usage, retry attempts, and errors.
Records a detailed trace of each chat turn for troubleshooting: the normalized request sent to the large language model (LLM) provider, the full response, token usage, retry attempts, and errors.
Off by default.
Three layers control whether it runs for a given chat:
docs/ai-coder/agents/platform-controls/git-providers.md
+1 -1
View File
@@ -27,7 +27,7 @@ Without `API_BASE_URL`, Coder defaults to `https://api.github.com`.
Clone and push still work (they use `AUTH_URL` and `TOKEN_URL` directly), but the diff viewer silently fails because Coder builds its URL-matching patterns from the API base URL.
> [!NOTE]
> If you have both a `github.com` and a GHE external auth config, only the GHE config needs `API_BASE_URL`.
> If you have both a `github.com` and a GitHub Enterprise (GHE) external auth config, only the GHE config needs `API_BASE_URL`.
## GitLab configuration
docs/ai-coder/agents/platform-controls/index.md
+2 -2
View File
@@ -12,7 +12,7 @@ This means:
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 MCP servers of their organization.
Users with organization configuration access own the models and the Model Context Protocol (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.
@@ -32,7 +32,7 @@ The control plane is the single source of truth for how agents behave.
### Providers and models
Administrators configure which LLM providers and models are available from the Coder dashboard.
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.
docs/ai-coder/agents/platform-controls/mcp-servers.md
+23 -23
View File
@@ -2,7 +2,7 @@
title: MCP servers
---
Organization admins can register external MCP servers that provide additional tools for agent chat sessions.
Organization admins can register external Model Context Protocol (MCP) servers that provide additional tools for agent chat sessions.
Each organization has its own set of MCP servers, and chats only offer servers from the chat's organization.
Configured servers are injected into or offered to users during chat depending on the availability policy.
@@ -45,11 +45,11 @@ The add and update views always show the target organization, as a read-only fie
#### Availability policies
| Policy | Behavior |
|---------------|-----------------------------------------------------------------------------------|
| `force_on` | Injected into every chat whose owner has ACL access to the server. No opting out. |
| `default_on` | Pre-selected in new chats. Users can opt out. |
| `default_off` | Available in the server list but users must opt in. |
| Policy | Behavior |
|---------------|---------------------------------------------------------------------------------------------------------|
| `force_on` | Injected into every chat whose owner has access control list (ACL) access to the server. No opting out. |
| `default_on` | Pre-selected in new chats. Users can opt out. |
| `default_off` | Available in the server list but users must opt in. |
## Authentication
@@ -79,12 +79,12 @@ The administrator configures the OAuth2 provider, and each user independently co
Optional fields:
| Field | Description |
|-------------------------|-------------------------------------------|
| `oauth2_client_secret` | OAuth2 client secret. |
| `oauth2_scopes` | Space-separated list of scopes. |
| `oauth2_revocation_url` | Token revocation endpoint URL (RFC 7009). |
| `oauth2_resource` | Resource indicator URI (RFC 8707). |
| Field | Description |
|-------------------------|------------------------------------------------------------------|
| `oauth2_client_secret` | OAuth2 client secret. |
| `oauth2_scopes` | Space-separated list of scopes. |
| `oauth2_revocation_url` | Token revocation endpoint URL (Request for Comments (RFC) 7009). |
| `oauth2_resource` | Resource indicator Uniform Resource Identifier (URI) (RFC 8707). |
The revocation endpoint must use HTTPS.
Loopback URLs may use HTTP for local development and tests.
@@ -130,7 +130,7 @@ At least one header is required when this mode is selected.
### User OIDC Identity
Forwards the calling user's OIDC access token (stored in `user_links.oauth_access_token`) to the MCP server as an `Authorization: Bearer <token>` header.
Forwards the calling user's OpenID Connect (OIDC) access token (stored in `user_links.oauth_access_token`) to the MCP server as an `Authorization: Bearer <token>` header.
The token is refreshed transparently before each request if it has expired or is close to expiring.
No admin-configurable fields.
@@ -163,7 +163,7 @@ When the server config has a signing secret, Coder also signs the request body a
| `X-Coder-Signature-Timestamp` | Unix timestamp in seconds used to limit replay. |
| `X-Coder-Signature` | Request signature in the form `v1=<lowercase hexadecimal HMAC-SHA256>`. |
Coder sends the same identity headers to LLM providers, so a first-party MCP server can correlate a tool call with the originating chat.
Coder sends the same identity headers to large language model (LLM) providers, so a first-party MCP server can correlate a tool call with the originating chat.
### Configure request signing
@@ -306,15 +306,15 @@ A subagent chat in plan mode gets none of them.
### Fields
| Field | Description |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `slug` | 1 to 32 ASCII letters, numbers, `_`, or `-`, starting with a letter or number. Unique within the chat. Prefixes every tool name. |
| `url` | Streamable HTTP MCP endpoint. Refer to [URL and header requirements](#url-and-header-requirements). |
| `headers` | Up to 16 HTTP headers sent on every request. This is the only credential mechanism. |
| `tool_allow_list` | Same semantics as [Tool governance](#tool-governance). Up to 64 names. Cannot be combined with `tool_deny_list`. |
| `tool_deny_list` | Same semantics as [Tool governance](#tool-governance). Up to 64 names. Cannot be combined with `tool_allow_list`. |
| `allow_in_subagents` | Offer the server's tools to subagent chats spawned from this chat. Defaults to `false`. |
| `forward_coder_headers` | Send the [Coder identity headers](#coder-identity-headers). Defaults to `false`. |
| Field | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `slug` | 1 to 32 American Standard Code for Information Interchange (ASCII) letters, numbers, `_`, or `-`, starting with a letter or number. Unique within the chat. Prefixes every tool name. |
| `url` | Streamable HTTP MCP endpoint. Refer to [URL and header requirements](#url-and-header-requirements). |
| `headers` | Up to 16 HTTP headers sent on every request. This is the only credential mechanism. |
| `tool_allow_list` | Same semantics as [Tool governance](#tool-governance). Up to 64 names. Cannot be combined with `tool_deny_list`. |
| `tool_deny_list` | Same semantics as [Tool governance](#tool-governance). Up to 64 names. Cannot be combined with `tool_allow_list`. |
| `allow_in_subagents` | Offer the server's tools to subagent chats spawned from this chat. Defaults to `false`. |
| `forward_coder_headers` | Send the [Coder identity headers](#coder-identity-headers). Defaults to `false`. |
### Limits
docs/ai-coder/agents/platform-controls/organizations.md
+19 -19
View File
@@ -13,25 +13,25 @@ Running more than 1 organization requires a [Premium license](../../../admin/use
## What each scope owns
| Setting | Scope | Where to configure |
|---------------------------------|------------------------|----------------------------------------------------------------------------|
| AI providers and credentials | Deployment | **Admin settings** > **AI** > **Providers** |
| Chat models | Organization | **Admin settings** > **AI** > **Models** |
| Default model | Organization | **Admin settings** > **AI** > **Coder Agents** > **Organization settings** |
| Admin model overrides | Organization | **Admin settings** > **AI** > **Coder Agents** > **Organization settings** |
| Personal model overrides | User, per organization | **Agents** > **Settings** > **Agents** |
| Personal override toggle | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| MCP servers | Organization | **Admin settings** > **AI** > **Coder Agents** > **MCP servers** |
| Organization skills | Organization | **Admin settings** > **AI** > **Coder Agents** > **Skills** |
| Personal skills | User | **Agents** > **Settings** > **Skills** |
| System prompt | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Organization instructions | Organization | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Plan mode instructions | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Agent access to a template | Template | **Admin settings** > **AI** > **Coder Agents** > **Templates** |
| Advisor runtime limits | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| Virtual desktop provider | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| Autostop fallback and lifecycle | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Lifecycle** |
| Data retention | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Lifecycle** |
| Setting | Scope | Where to configure |
|--------------------------------------|------------------------|----------------------------------------------------------------------------|
| AI providers and credentials | Deployment | **Admin settings** > **AI** > **Providers** |
| Chat models | Organization | **Admin settings** > **AI** > **Models** |
| Default model | Organization | **Admin settings** > **AI** > **Coder Agents** > **Organization settings** |
| Admin model overrides | Organization | **Admin settings** > **AI** > **Coder Agents** > **Organization settings** |
| Personal model overrides | User, per organization | **Agents** > **Settings** > **Agents** |
| Personal override toggle | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| Model Context Protocol (MCP) servers | Organization | **Admin settings** > **AI** > **Coder Agents** > **MCP servers** |
| Organization skills | Organization | **Admin settings** > **AI** > **Coder Agents** > **Skills** |
| Personal skills | User | **Agents** > **Settings** > **Skills** |
| System prompt | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Organization instructions | Organization | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Plan mode instructions | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Instructions** |
| Agent access to a template | Template | **Admin settings** > **AI** > **Coder Agents** > **Templates** |
| Advisor runtime limits | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| Virtual desktop provider | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Deployment settings** |
| Autostop fallback and lifecycle | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Lifecycle** |
| Data retention | Deployment | **Admin settings** > **AI** > **Coder Agents** > **Lifecycle** |
The **Deployment settings** section holds the Advisor card and the Virtual desktop card.
Both cards appear on the **Coder Agents** page.
docs/ai-coder/agents/platform-controls/spend-management.md
+3 -3
View File
@@ -16,7 +16,7 @@ Coder Agents spend is controlled by AI Gateway budgets, which cap all AI Gateway
Per-user overrides take priority over group budgets.
The deployment flags `--ai-budget-policy` and `--ai-budget-period` currently support only `highest` and `month`.
`highest` selects the group with the largest spend limit, and `month` resets spend at the start of each UTC calendar month.
`highest` selects the group with the largest spend limit, and `month` resets spend at the start of each Coordinated Universal Time (UTC) calendar month.
A user who belongs to no budgeted group falls back to the Everyone group, which has no budget unless one is set for it.
There is no deployment-wide budget amount, and a configured spend limit cannot exceed $1,000,000 per member per period.
@@ -28,7 +28,7 @@ There is no deployment-wide budget amount, and a configured spend limit cannot e
> Existing native limit values are not migrated to AI Gateway budgets and are no longer enforced.
> Configured per-model prices and historical native cost totals are also not migrated to AI Gateway.
> Before upgrading, record any per-model prices you need from **Admin settings** > **AI** > **Models**.
> The old cost endpoints default `start_date` to 30&nbsp;days before the request and `end_date` to the request time, so choose explicit RFC 3339 UTC values that cover all history you need.
> The old cost endpoints default `start_date` to 30&nbsp;days before the request and `end_date` to the request time, so choose explicit Request for Comments (RFC) 3339 UTC values that cover all history you need.
> Fetch `/api/v2/chats/cost/users?start_date=<start>&end_date=<end>&limit=100&offset=0` and save the response.
> After each page, stop when `offset + users.length >= count`; otherwise, increase `offset` by 100 and fetch the next page.
> For every `users[].user_id` across those pages, save `/api/v2/chats/cost/{user_id}/summary?start_date=<start>&end_date=<end>` with the same dates.
@@ -43,7 +43,7 @@ The API reference documents how to [get](../../../reference/api/enterprise.md#ge
- The AI Gateway checks the user's current spend before forwarding each request.
When spend meets or exceeds the budget, the request is rejected and the chat shows a terminal error explaining that the budget was exceeded.
- Brief overage is possible when concurrent requests are in flight, because cost is recorded after the LLM responds.
- Brief overage is possible when concurrent requests are in flight, because cost is recorded after the large language model (LLM) responds.
### User-facing status
docs/ai-coder/agents/platform-controls/template-optimization.md
+9 -9
View File
@@ -3,7 +3,7 @@ title: Template optimization
---
Not every chat with Coder Agents requires a workspace.
The agent provisions one when missing tools, skills, MCP integrations, or context block progress, or when it needs to work with files or run commands.
The agent provisions one when missing tools, skills, Model Context Protocol (MCP) integrations, or context block progress, or when it needs to work with files or run commands.
When a workspace is needed, the agent reads the available templates, selects the appropriate one based on its name and description, and provisions a workspace automatically.
Administrators can [restrict which templates the agent can use](#restrict-available-templates).
@@ -48,12 +48,12 @@ A good template description tells the agent:
### Examples
| Description | Why it works |
|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| Python backend services for the payments repo. Includes Poetry, Python 3.12, and PostgreSQL | Specific language, repo, and toolchain |
| React frontend development for the customer portal. Node 20, pnpm, Storybook pre-installed | Clear stack, named project, key tools listed |
| General-purpose Go development environment with Go 1.23, Docker, and common CLI tools | Broad but descriptive — the agent can match it to Go-related tasks |
| Java microservices for the order-processing pipeline. Maven, JDK 21, Kafka client libraries | Names the service domain and build tool |
| Description | Why it works |
|--------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| Python backend services for the payments repo. Includes Poetry, Python 3.12, and PostgreSQL | Specific language, repo, and toolchain |
| React frontend development for the customer portal. Node 20, pnpm, Storybook pre-installed | Clear stack, named project, key tools listed |
| General-purpose Go development environment with Go 1.23, Docker, and common CLI tools | Broad but descriptive, so the agent can match it to Go-related tasks |
| Java microservices for the order-processing pipeline. Maven, Java Development Kit (JDK) 21, Kafka client libraries | Names the service domain and build tool |
| Description | Why it fails |
|--------------------|-------------------------------------------------------------------------|
@@ -114,7 +114,7 @@ Agent templates differ from developer templates in several ways:
- **Reduced permissions.**
Agent workspaces can use scoped credentials with fewer permissions than a developer's interactive session.
See [Creating templates](../../../admin/templates/creating-templates.md) for step-by-step instructions on creating templates via the UI, CLI, or CI/CD.
See [Creating templates](../../../admin/templates/creating-templates.md) for step-by-step instructions on creating templates via the UI, CLI, or continuous integration and continuous delivery (CI/CD).
## Configure network boundaries
@@ -122,7 +122,7 @@ The workspace is the network boundary for the agent.
If you want to control what the agent can access, control what the workspace can access.
This is a deliberate architectural advantage of running the agent loop in the control plane.
Because all AI functionality (LLM inference, tool dispatch, chat state) lives in the control plane, agent workspaces do not need outbound access to any LLM provider.
Because all AI functionality (large language model (LLM) inference, tool dispatch, chat state) lives in the control plane, agent workspaces do not need outbound access to any LLM provider.
The workspace only needs to reach:
- **The Coder control plane** — required for the workspace daemon to function.
docs/ai-coder/agents/tasks-to-chats-migration.md
+14 -14
View File
@@ -25,16 +25,16 @@ Tasks and Chats are separate resources with separate APIs, so plan to update you
Before mapping individual endpoints, understand the structural changes:
| Aspect | Tasks API | Chats API |
|------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------|
| Agent execution | Agent runs **inside the workspace** (via AgentAPI) | Agent loop runs **in the control plane** |
| LLM credentials | Injected into workspace environment | Stored in control plane only; never enters the workspace |
| Workspace provisioning | You specify a `template_version_id` at creation | The agent auto-selects a template and provisions on demand |
| Template requirements | Requires `coder_ai_task` resource, `coder_task` data source, and an agent module | Any template with a clear description works |
| Chat state | Stored in the workspace (AgentAPI state file) | Persisted in the Coder database |
| Conversation model | Single prompt with optional follow-up input | Multi-turn chat with message history, queuing, and editing |
| Real-time updates | HTTP polling (`GET .../logs`) | WebSocket streaming (`GET .../stream`) |
| Sub-agents | Not supported | Built-in sub-agent delegation |
| Aspect | Tasks API | Chats API |
|----------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------|
| Agent execution | Agent runs **inside the workspace** (via AgentAPI) | Agent loop runs **in the control plane** |
| Large language model (LLM) credentials | Injected into workspace environment | Stored in control plane only; never enters the workspace |
| Workspace provisioning | You specify a `template_version_id` at creation | The agent auto-selects a template and provisions on demand |
| Template requirements | Requires `coder_ai_task` resource, `coder_task` data source, and an agent module | Any template with a clear description works |
| Chat state | Stored in the workspace (AgentAPI state file) | Persisted in the Coder database |
| Conversation model | Single prompt with optional follow-up input | Multi-turn chat with message history, queuing, and editing |
| Real-time updates | HTTP polling (`GET .../logs`) | WebSocket streaming (`GET .../stream`) |
| Sub-agents | Not supported | Built-in sub-agent delegation |
## Endpoint mapping
@@ -115,7 +115,7 @@ Key differences:
- `template_version_id` and `template_version_preset_id` are removed.
The agent selects a template automatically based on the prompt and available template descriptions.
To pin to a specific workspace, pass `workspace_id` instead.
- Optionally pass `model_config_id` to override the default model, or `mcp_server_ids` to attach MCP servers.
- Optionally pass `model_config_id` to override the default model, or `mcp_server_ids` to attach Model Context Protocol (MCP) servers.
- Optionally pass `title` to set the chat's title.
A title you set is kept; automatic title generation runs only when `title` is omitted.
@@ -305,7 +305,7 @@ jobs:
+ comment-on-issue: true
```
Key differences from the Tasks GHA:
Key differences from the Tasks GitHub Action (GHA):
- No `coder-template-name` or `coder-task-name-prefix`.
The agent auto-provisions a workspace; pass `workspace-id` if you want to pin to an existing workspace instead.
@@ -625,7 +625,7 @@ The Chats API returns a `Chat` object with conversation-centric fields:
| Tasks API field | Chats API equivalent | Notes |
|--------------------|-----------------------------------------------|------------------------------------------------------------------|
| `id` | `id` | Both are UUIDs |
| `id` | `id` | Both are universally unique identifiers (UUIDs) |
| `initial_prompt` | First message in `GET /chats/{chat}/messages` | Prompt is a message, not a top-level field |
| `display_name` | `title` | Auto-generated or set via `PATCH` |
| `status` | `status` | Different enum values (see status table above) |
@@ -638,7 +638,7 @@ The Chats API returns a `Chat` object with conversation-centric fields:
## CLI changes
The Tasks CLI (`coder task`) was removed, and Coder does not ship an interactive Coder Agents TUI.
The Tasks CLI (`coder task`) was removed, and Coder does not ship an interactive Coder Agents terminal user interface (TUI).
Use the web UI for interactive chat and direct API calls for automation.
The table below maps the removed commands to their Chats API equivalents.
docs/ai-coder/agents/tools.md
+3 -3
View File
@@ -21,7 +21,7 @@ Tool calls and their results are visible in the chat timeline, so you can always
Two properties hold for every built-in tool:
- **Your permissions apply.**
Tools run with the chat owner's RBAC identity.
Tools run with the chat owner's role-based access control (RBAC) identity.
The agent cannot list templates or create workspaces that you could not access yourself.
- **Results carry instructions.**
Where a decision matters, the tool result includes a `next_step` field containing a fixed instruction for the agent, such as asking you to choose between similar templates.
@@ -31,7 +31,7 @@ Two properties hold for every built-in tool:
A chat can start without a workspace.
When the conversation and available tools are sufficient, the agent answers without provisioning one.
If missing tools, skills, MCP integrations, or context block progress, or the task needs workspace file access or execution, the agent provisions a workspace.
If missing tools, skills, Model Context Protocol (MCP) integrations, or context block progress, or the task needs workspace file access or execution, the agent provisions a workspace.
You don't need to request a workspace separately for setup needed to complete your task.
The agent uses three tools to provision a workspace:
@@ -170,7 +170,7 @@ For templates that work with defaults, the agent skips straight to `create_works
| Argument | Type | Description |
|---------------|--------|------------------------------------------------------------------------------------|
| `template_id` | string | Required. The template UUID from `list_templates` |
| `template_id` | string | Required. The template universally unique identifier (UUID) from `list_templates` |
| `name` | string | Optional workspace name. One is generated if omitted |
| `parameters` | object | Optional template parameter values from `read_template` |
| `preset_id` | string | Optional preset UUID. Applies preset parameters and may claim a prebuilt workspace |
docs/ai-coder/ai-gateway/ai-gateway-proxy/index.md
+2 -2
View File
@@ -17,8 +17,8 @@ For a list of clients supported through AI Gateway Proxy, see [Client Configurat
AI Gateway Proxy operates in two modes depending on the destination:
* MITM (Man-in-the-Middle) mode for the hostnames of enabled AI providers:
* Intercepts and decrypts HTTPS traffic using a configured CA certificate
* Man-in-the-Middle (MITM) mode for the hostnames of enabled AI providers:
* Intercepts and decrypts HTTPS traffic using a configured certificate authority (CA) certificate
* Forwards requests to AI Gateway for authentication, auditing, and routing
* Covers the hostname from each enabled provider's base URL
docs/ai-coder/ai-gateway/ai-gateway-proxy/setup.md
+4 -4
View File
@@ -10,7 +10,7 @@ Once enabled, `coderd` runs the AI Gateway Proxy in-process and intercepts traff
1. AI Gateway must be enabled and configured (requires a Premium license, which includes [AI Governance](../../ai-governance.md)).
See [AI Gateway Setup](../setup.md) for further information.
1. AI Gateway Proxy must be [enabled](#proxy-configuration) using the `coder server` flag.
1. A [CA certificate](#ca-certificate) must be configured for MITM interception.
1. A [certificate authority (CA) certificate](#ca-certificate) must be configured for man-in-the-middle (MITM) interception.
1. [Clients](#client-configuration) must be configured to use the proxy and trust the CA certificate.
## Proxy Configuration
@@ -96,11 +96,11 @@ As a best practice, apply one or more of the following to protect credentials du
### Restrict proxy access
Requests to non-allowlisted domains are tunneled through the proxy, but connections to private and reserved IP ranges are blocked by default.
The IP validation and TCP connect happen atomically, preventing DNS rebinding attacks where the resolved address could change between the check and the connection.
The IP validation and Transmission Control Protocol (TCP) connect happen atomically, preventing DNS rebinding attacks where the resolved address could change between the check and the connection.
To prevent unauthorized use, restrict network access to the proxy so that only authorized clients can connect.
In case the AI Gateway [proxy target](#proxy-target) hostname (the Coder access URL by default) resolves to a private address, it is automatically exempt from this restriction so the proxy can always reach the configured AI Gateway.
If you need to allow access to additional internal networks via the proxy, use the Allowlist CIDRs option ([`CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS`](../../../reference/cli/server/index.md#--ai-gateway-proxy-allowed-private-cidrs)):
If you need to allow access to additional internal networks, given as Classless Inter-Domain Routing (CIDR) ranges, via the proxy, use the Allowlist CIDRs option ([`CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS`](../../../reference/cli/server/index.md#--ai-gateway-proxy-allowed-private-cidrs)):
```sh
CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS=10.0.0.0/8,172.16.0.0/12
@@ -339,7 +339,7 @@ curl -o coder-ai-gateway-proxy-ca.pem \
Replace `<coder-url>` with your Coder deployment URL.
When [TLS is enabled](#proxy-tls-configuration) on the proxy, AI tools must trust both the [MITM CA certificate](#ca-certificate) and the [TLS certificate](#proxy-tls-configuration).
Combine both certificates into a single PEM file:
Combine both certificates into a single Privacy-Enhanced Mail (PEM) file:
```sh
cat coder-ai-gateway-proxy-ca.pem listener.crt > combined-ca.pem
docs/ai-coder/ai-gateway/audit.md
+1 -1
View File
@@ -65,7 +65,7 @@ While a query is active, the timeline shows only matching events and a count bel
Matches render in bold in prompts, tool names, and network call destinations, and a matching prompt expands to show the match.
A "No events match your search in the loaded events." message appears when nothing in the loaded events matches.
Within a thread, each step shows token usage, tool call details (including arguments and MCP server URLs), duration, and any errors or warnings.
Within a thread, each step shows token usage, tool call details (including arguments and Model Context Protocol (MCP) server URLs), duration, and any errors or warnings.
The **Session summary** card beside the timeline reports the session's [Agent Firewall](../agent-firewall/index.md) activity:
docs/ai-coder/ai-gateway/auth.md
+3 -3
View File
@@ -47,7 +47,7 @@ Or create a new long-lived token with a name and lifetime:
coder tokens create --lifetime 30d -n my-ai-token
```
Use short lifetimes for automation and CI to limit the blast radius if a token leaks.
Use short lifetimes for automation and continuous integration (CI) to limit the blast radius if a token leaks.
### Retrieve your session token
@@ -67,7 +67,7 @@ The Coder token is supplied in the proxy URL:
export HTTPS_PROXY="https://coder:$(coder login token)@<proxy-host>:8888"
```
The client machine also needs to trust the proxy's CA certificate.
The client machine also needs to trust the proxy's certificate authority (CA) certificate.
For full setup, refer to [AI Gateway Proxy setup](./ai-gateway-proxy/setup.md).
## Authenticate standalone gateway replicas
@@ -146,7 +146,7 @@ For provider setup and credential failover, refer to [Provider configuration](./
## Bring Your Own Key (BYOK)
In addition to centralized key management, AI Gateway supports Bring Your Own Key (BYOK) mode.
Users can provide their own LLM API keys or provider subscriptions, such as Claude Pro or Max and ChatGPT Plus or Pro, while AI Gateway continues to provide observability and governance.
Users can provide their own large language model (LLM) API keys or provider subscriptions, such as Claude Pro or Max and ChatGPT Plus or Pro, while AI Gateway continues to provide observability and governance.
![BYOK authentication flow](../../images/aibridge/clients/byok_auth_flow.png)
docs/ai-coder/ai-gateway/clients/cline.md
+1 -1
View File
@@ -63,7 +63,7 @@ To configure Cline to use AI Gateway, follow these steps: ![Cline Settings](../.
1. **Custom Headers**:
Add `X-Coder-AI-Governance-Token` with your **[Coder API token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)**.
![Cline BYOK OpenAI Settings](../../../images/aibridge/clients/cline-byok-openai.png)
![Cline Bring Your Own Key (BYOK) OpenAI Settings](../../../images/aibridge/clients/cline-byok-openai.png)
</div>
docs/ai-coder/ai-gateway/clients/copilot.md
+3 -3
View File
@@ -43,16 +43,16 @@ Copilot CLI is built on Node.js and uses the `NODE_EXTRA_CA_CERTS` environment v
export NODE_EXTRA_CA_CERTS="/path/to/coder-ai-gateway-proxy-ca.pem"
```
Refer to [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
Refer to [Client Configuration certificate authority (CA) certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
When [TLS is enabled](../ai-gateway-proxy/setup.md#proxy-tls-configuration) on the proxy, combine the MITM CA certificate and the TLS certificate into a single file:
When [TLS is enabled](../ai-gateway-proxy/setup.md#proxy-tls-configuration) on the proxy, combine the man-in-the-middle (MITM) CA certificate and the TLS certificate into a single file:
```sh
cat coder-ai-gateway-proxy-ca.pem listener.crt > combined-ca.pem
export NODE_EXTRA_CA_CERTS="/path/to/combined-ca.pem"
```
Copilot CLI may start MCP server processes that use runtimes other than Node.js (e.g. Go).
Copilot CLI may start Model Context Protocol (MCP) server processes that use runtimes other than Node.js (e.g. Go).
These processes inherit environment variables like `HTTPS_PROXY` but may not respect `NODE_EXTRA_CA_CERTS`.
Adding the TLS certificate to the [system trust store](../ai-gateway-proxy/setup.md#system-trust-store) ensures all processes trust it.
docs/ai-coder/ai-gateway/clients/factory.md
+1 -1
View File
@@ -75,4 +75,4 @@ Factort's Droid agent can be configured to use AI Gateway by setting up custom m
```
**References:**
[Factory BYOK OpenAI & Anthropic](https://docs.factory.ai/cli/byok/openai-anthropic)
[Factory Bring Your Own Key (BYOK) OpenAI & Anthropic](https://docs.factory.ai/cli/byok/openai-anthropic)
docs/ai-coder/ai-gateway/clients/index.md
+21 -21
View File
@@ -42,26 +42,26 @@ For information about authenticating with AI Gateway, visit [AI Gateway Authenti
The table below shows tested AI clients and their compatibility with AI Gateway.
| Client | OpenAI | Anthropic | BYOK | Notes |
|-----------------------------------|--------|-----------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Xum](./xum.md) | ✅ | ✅ | - | |
| [Claude Code](./claude-code.md) | - | ✅ | ✅ | |
| [Codex CLI](./codex.md) | ✅ | - | ✅ | |
| [OpenCode](./opencode.md) | ✅ | ✅ | ✅ | |
| [Factory](./factory.md) | ✅ | ✅ | ✅ | |
| [Cline](./cline.md) | ✅ | ✅ | ✅ | |
| [Kilo Code](./kilo-code.md) | ✅ | ✅ | ❌ | |
| [VS Code](./vscode.md) | ✅ | ✅ | ❌ | VS Code 1.122+ via Custom Endpoint provider. GitHub sign-in not required. Inline suggestions still require GitHub Copilot. |
| [JetBrains IDEs](./jetbrains.md) | ✅ | ❌ | ❌ | Works in Chat mode via [third-party model configuration](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html#provide-your-own-api-key). |
| [Junie](./junie.md) | ✅ | ✅ | ✅ | Junie CLI via custom model profiles. |
| [Zed](./zed.md) | ✅ | ✅ | ❌ | |
| [GitHub Copilot](./copilot.md) | ⚙️ | - | - | Requires [AI Gateway Proxy](../ai-gateway-proxy/index.md). Uses per-user GitHub tokens. |
| Devin Desktop (formerly Windsurf) | ❌ | ❌ | ❌ | No option to override base URL. |
| Cursor | ❌ | ❌ | ❌ | Override for OpenAI broken ([upstream issue](https://forum.cursor.com/t/requests-are-sent-to-incorrect-endpoint-when-using-base-url-override/144894)). |
| Sourcegraph Amp | ❌ | ❌ | ❌ | No option to override base URL. |
| Kiro | ❌ | ❌ | ❌ | No option to override base URL. |
| Gemini CLI | ❌ | ❌ | ❌ | No Gemini API support. Upvote [this issue](https://github.com/coder/coder/issues/24804). |
| Antigravity | ❌ | ❌ | ❌ | No option to override base URL. |
| Client | OpenAI | Anthropic | Bring Your Own Key (BYOK) | Notes |
|-----------------------------------|--------|-----------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Xum](./xum.md) | ✅ | ✅ | - | |
| [Claude Code](./claude-code.md) | - | ✅ | ✅ | |
| [Codex CLI](./codex.md) | ✅ | - | ✅ | |
| [OpenCode](./opencode.md) | ✅ | ✅ | ✅ | |
| [Factory](./factory.md) | ✅ | ✅ | ✅ | |
| [Cline](./cline.md) | ✅ | ✅ | ✅ | |
| [Kilo Code](./kilo-code.md) | ✅ | ✅ | ❌ | |
| [VS Code](./vscode.md) | ✅ | ✅ | ❌ | VS Code 1.122+ via Custom Endpoint provider. GitHub sign-in not required. Inline suggestions still require GitHub Copilot. |
| [JetBrains IDEs](./jetbrains.md) | ✅ | ❌ | ❌ | Works in Chat mode via [third-party model configuration](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html#provide-your-own-api-key). |
| [Junie](./junie.md) | ✅ | ✅ | ✅ | Junie CLI via custom model profiles. |
| [Zed](./zed.md) | ✅ | ✅ | ❌ | |
| [GitHub Copilot](./copilot.md) | ⚙️ | - | - | Requires [AI Gateway Proxy](../ai-gateway-proxy/index.md). Uses per-user GitHub tokens. |
| Devin Desktop (formerly Windsurf) | ❌ | ❌ | ❌ | No option to override base URL. |
| Cursor | ❌ | ❌ | ❌ | Override for OpenAI broken ([upstream issue](https://forum.cursor.com/t/requests-are-sent-to-incorrect-endpoint-when-using-base-url-override/144894)). |
| Sourcegraph Amp | ❌ | ❌ | ❌ | No option to override base URL. |
| Kiro | ❌ | ❌ | ❌ | No option to override base URL. |
| Gemini CLI | ❌ | ❌ | ❌ | No Gemini API support. Upvote [this issue](https://github.com/coder/coder/issues/24804). |
| Antigravity | ❌ | ❌ | ❌ | No option to override base URL. |
|
*Legend: ✅ supported, ⚙️ requires AI Gateway Proxy, ❌ not supported, - not applicable.*
@@ -101,7 +101,7 @@ You can also configure AI tools running outside of a Coder workspace, such as lo
Use the same settings as the in-workspace case, configure the [base URL](#base-urls) and authenticate with a Coder API token.
For base URL setup, the client machine must have network access to the gateway endpoint on your Coder deployment.
Clients using [AI Gateway Proxy](../ai-gateway-proxy/index.md) must be able to reach the proxy endpoint and trust its CA certificate.
Clients using [AI Gateway Proxy](../ai-gateway-proxy/index.md) must be able to reach the proxy endpoint and trust its certificate authority (CA) certificate.
Users can generate a long-lived API token from the Coder UI or CLI.
Follow the instructions at [Sessions and API tokens](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself) to create one.
docs/ai-coder/ai-gateway/clients/jetbrains.md
+1 -1
View File
@@ -52,7 +52,7 @@ You can now use the AI Assistant chat with the configured provider.
## BYOK (Personal API Key)
> [!NOTE]
> At the time of writing, JetBrains AI Assistant does not support sending custom headers, so BYOK mode is not available.
> At the time of writing, JetBrains AI Assistant does not support sending custom headers, so Bring Your Own Key (BYOK) mode is not available.
**References:**
[Use custom models with JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html#provide-your-own-api-key)
docs/ai-coder/ai-gateway/clients/junie.md
+3 -3
View File
@@ -74,11 +74,11 @@ Run Junie with the profile:
junie --model custom:ai-gateway
```
Custom profiles also appear in the model selection list of the interactive TUI and in the `/model` slash command.
Custom profiles also appear in the model selection list of the interactive terminal user interface (TUI) and in the `/model` slash command.
## BYOK (Personal API Key)
Junie supports custom headers, so BYOK works by sending your personal provider key as the API key and the Coder API token as the governance token:
Junie supports custom headers, so Bring Your Own Key (BYOK) works by sending your personal provider key as the API key and the Coder API token as the governance token:
```json
{
@@ -119,4 +119,4 @@ resource "coder_env" "coder_api_token" {
Reference the deployment URL in the profile with `${data.coder_workspace.me.access_url}/api/v2/ai-gateway/openai/v1/responses` if you generate the file from the template instead of committing it.
**References:**
[Junie custom LLMs](https://junie.jetbrains.com/docs/custom-llm-models.html#using-custom-models)
[Junie custom large language models (LLMs)](https://junie.jetbrains.com/docs/custom-llm-models.html#using-custom-models)
docs/ai-coder/ai-gateway/clients/opencode.md
+1 -1
View File
@@ -79,7 +79,7 @@ You can use OpenCode with custom model IDs through a [Bedrock Mantle provider](.
AI Gateway signs requests with AWS credentials centrally, so you only need a [Coder API token](../auth.md#authenticate-ai-clients) in OpenCode.
Use a custom provider in OpenCode that matches your model's API, rather than its native Amazon Bedrock integration.
The following example uses Astra with the Responses API.
For other models, choose the SDK package that matches the API:
For other models, choose the software development kit (SDK) package that matches the API:
| Model API | OpenCode `npm` package |
|--------------------|-----------------------------|
docs/ai-coder/ai-gateway/clients/xum.md
+1 -1
View File
@@ -39,7 +39,7 @@ _Replace `coder.example.com` with your Coder deployment URL._
## Environment variables
Xum reads provider configuration from its settings UI and also from environment variables.
Environment variables are useful in CI or when running Xum inside a Coder workspace.
Environment variables are useful in continuous integration (CI) or when running Xum inside a Coder workspace.
> [!NOTE]
> Xum treats environment variables as a fallback when a provider is not configured in settings.
docs/ai-coder/ai-gateway/clients/zed.md
+1 -1
View File
@@ -72,7 +72,7 @@ You can set this in two ways:
## BYOK (Personal API Key)
> [!NOTE]
> At the time of writing, Zed Agent does not support sending custom headers, so BYOK mode is not available.
> At the time of writing, Zed Agent does not support sending custom headers, so Bring Your Own Key (BYOK) mode is not available.
**References:**
[Configuring Zed - Language Models](https://zed.dev/docs/reference/all-settings#language-models)
docs/ai-coder/ai-gateway/cost-controls.md
+10 -10
View File
@@ -22,14 +22,14 @@ AI Governance Cost Control requires:
These terms appear throughout this page and in the Coder dashboard:
| Term | What it means | Where it is set |
|-----------------------|---------------------------------------------------------------------------------------|----------------------------------------|
| **Budget period** | The window spend accumulates in before it resets. Defaults to the UTC calendar month. | Deployment settings |
| **Budget policy** | The rule that selects a user's effective group. Defaults to the highest budget. | Deployment settings |
| **Group budget** | A spend limit granted to each member of a group. | **Groups** > {group} > **Settings** |
| **User override** | A spend limit for one user that supersedes their group budget. | **Groups** > {group} > **Members** tab |
| **Effective group** | The group that supplies a user's budget and has their spend associated with it. | Resolved automatically |
| **Approximate spend** | A user's approximate spend in the current budget period. | Calculated from usage |
| Term | What it means | Where it is set |
|-----------------------|--------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| **Budget period** | The window spend accumulates in before it resets. Defaults to the Coordinated Universal Time (UTC) calendar month. | Deployment settings |
| **Budget policy** | The rule that selects a user's effective group. Defaults to the highest budget. | Deployment settings |
| **Group budget** | A spend limit granted to each member of a group. | **Groups** > {group} > **Settings** |
| **User override** | A spend limit for one user that supersedes their group budget. | **Groups** > {group} > **Members** tab |
| **Effective group** | The group that supplies a user's budget and has their spend associated with it. | Resolved automatically |
| **Approximate spend** | A user's approximate spend in the current budget period. | Calculated from usage |
## Deployment settings
@@ -64,7 +64,7 @@ Refer to [Groups and roles](../../admin/users/groups-roles.md) for the deploymen
The [Organization roles](../../admin/users/groups-roles.md#organization-roles) section covers the organization roles.
A group budget applies to each member individually rather than to the group as a whole.
For example, if a group has ten members and a budget of $200 USD, each member can spend $200 USD and the group has a total spend limit of $2,000 USD.
For example, if a group has ten members and a budget of $200 United States dollars (USD), each member can spend $200 USD and the group has a total spend limit of $2,000 USD.
1. Go to **Groups** and select a group.
1. Select **Settings**.
@@ -317,7 +317,7 @@ curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
```
- Without parameters, the export covers the current budget period.
- To select a range, pass `period_start` and `period_end` together as RFC 3339 timestamps.
- To select a range, pass `period_start` and `period_end` together as Request for Comments (RFC) 3339 timestamps.
A range can span at most 31&nbsp;days.
- Spend is attributed through each request's effective budget group, which falls back to the organization's `Everyone` group when no budget applies, so only usage recorded without any effective group is excluded.
- Each CSV row breaks spend down by user, group, model, and provider, with the underlying token counts.

Some files were not shown because too many files have changed in this diff Show More