diff --git a/docs/.style/README.md b/docs/.style/README.md index 404217650b..47b13bc30a 100644 --- a/docs/.style/README.md +++ b/docs/.style/README.md @@ -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 diff --git a/docs/.style/content-guidelines.md b/docs/.style/content-guidelines.md index d30a5ae53c..ea66ee8133 100644 --- a/docs/.style/content-guidelines.md +++ b/docs/.style/content-guidelines.md @@ -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 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 diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index 589d8c8f19..7fc80ee041 100644 --- a/docs/.style/styles/Coder/README.md +++ b/docs/.style/styles/Coder/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 03397d35db..7ceca03f51 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 3be141f514..70ec6d2236 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -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`. diff --git a/docs/admin/index.md b/docs/admin/index.md index be27accb15..8fedd7db11 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -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 diff --git a/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md index 773a93cbba..6029a80f15 100644 --- a/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md +++ b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md @@ -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): diff --git a/docs/admin/integrations/devcontainers/envbuilder/index.md b/docs/admin/integrations/devcontainers/envbuilder/index.md index 422f3d0c84..04300a7ea3 100644 --- a/docs/admin/integrations/devcontainers/envbuilder/index.md +++ b/docs/admin/integrations/devcontainers/envbuilder/index.md @@ -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 diff --git a/docs/admin/integrations/index.md b/docs/admin/integrations/index.md index 55c2ba6fbc..90526935f4 100644 --- a/docs/admin/integrations/index.md +++ b/docs/admin/integrations/index.md @@ -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. diff --git a/docs/admin/integrations/multiple-kube-clusters.md b/docs/admin/integrations/multiple-kube-clusters.md index 4d3640e58c..0fb40df9ad 100644 --- a/docs/admin/integrations/multiple-kube-clusters.md +++ b/docs/admin/integrations/multiple-kube-clusters.md @@ -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}") diff --git a/docs/admin/integrations/oauth2-provider/callback-url-schemes.md b/docs/admin/integrations/oauth2-provider/callback-url-schemes.md index 48586feff1..31974482b0 100644 --- a/docs/admin/integrations/oauth2-provider/callback-url-schemes.md +++ b/docs/admin/integrations/oauth2-provider/callback-url-schemes.md @@ -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. diff --git a/docs/admin/integrations/oauth2-provider/index.md b/docs/admin/integrations/oauth2-provider/index.md index 35d87307bd..ff354b4fc8 100644 --- a/docs/admin/integrations/oauth2-provider/index.md +++ b/docs/admin/integrations/oauth2-provider/index.md @@ -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: diff --git a/docs/admin/integrations/oauth2-provider/integration-patterns.md b/docs/admin/integrations/oauth2-provider/integration-patterns.md index 1b5c1c2383..c16bb02a06 100644 --- a/docs/admin/integrations/oauth2-provider/integration-patterns.md +++ b/docs/admin/integrations/oauth2-provider/integration-patterns.md @@ -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 diff --git a/docs/admin/integrations/oauth2-provider/scopes.md b/docs/admin/integrations/oauth2-provider/scopes.md index 4a0de54534..11eefd1959 100644 --- a/docs/admin/integrations/oauth2-provider/scopes.md +++ b/docs/admin/integrations/oauth2-provider/scopes.md @@ -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. diff --git a/docs/admin/integrations/oauth2-provider/security.md b/docs/admin/integrations/oauth2-provider/security.md index e24f4e74f4..43d4827522 100644 --- a/docs/admin/integrations/oauth2-provider/security.md +++ b/docs/admin/integrations/oauth2-provider/security.md @@ -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). diff --git a/docs/admin/integrations/oauth2-provider/token-management.md b/docs/admin/integrations/oauth2-provider/token-management.md index f53a499ecf..06ed8a37a4 100644 --- a/docs/admin/integrations/oauth2-provider/token-management.md +++ b/docs/admin/integrations/oauth2-provider/token-management.md @@ -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`: diff --git a/docs/admin/integrations/oauth2-provider/troubleshooting.md b/docs/admin/integrations/oauth2-provider/troubleshooting.md index ac0a35aacc..93760e44c9 100644 --- a/docs/admin/integrations/oauth2-provider/troubleshooting.md +++ b/docs/admin/integrations/oauth2-provider/troubleshooting.md @@ -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 diff --git a/docs/admin/integrations/vault.md b/docs/admin/integrations/vault.md index 065ce1a9b7..41c6855f6a 100644 --- a/docs/admin/integrations/vault.md +++ b/docs/admin/integrations/vault.md @@ -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 diff --git a/docs/admin/monitoring/connection-logs.md b/docs/admin/monitoring/connection-logs.md index b48c39f836..d1241381ae 100644 --- a/docs/admin/monitoring/connection-logs.md +++ b/docs/admin/monitoring/connection-logs.md @@ -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. diff --git a/docs/admin/monitoring/health-check.md b/docs/admin/monitoring/health-check.md index 816d80ae19..290dc1c6af 100644 --- a/docs/admin/monitoring/health-check.md +++ b/docs/admin/monitoring/health-check.md @@ -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 diff --git a/docs/admin/monitoring/logs.md b/docs/admin/monitoring/logs.md index e4800d0429..b584419bea 100644 --- a/docs/admin/monitoring/logs.md +++ b/docs/admin/monitoring/logs.md @@ -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 ` 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 diff --git a/docs/admin/monitoring/notifications/index.md b/docs/admin/monitoring/notifications/index.md index 5cf745525f..ee007db50a 100644 --- a/docs/admin/monitoring/notifications/index.md +++ b/docs/admin/monitoring/notifications/index.md @@ -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 diff --git a/docs/admin/networking/high-availability.md b/docs/admin/networking/high-availability.md index 439a72858f..028ebcea0d 100644 --- a/docs/admin/networking/high-availability.md +++ b/docs/admin/networking/high-availability.md @@ -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. diff --git a/docs/admin/networking/index.md b/docs/admin/networking/index.md index a85d12035f..75e5fbdd55 100644 --- a/docs/admin/networking/index.md +++ b/docs/admin/networking/index.md @@ -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. diff --git a/docs/admin/networking/port-forwarding.md b/docs/admin/networking/port-forwarding.md index 893fb9b9c8..c8c07e37a2 100644 --- a/docs/admin/networking/port-forwarding.md +++ b/docs/admin/networking/port-forwarding.md @@ -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 diff --git a/docs/admin/networking/stun.md b/docs/admin/networking/stun.md index fbd20c26ff..00f57b454b 100644 --- a/docs/admin/networking/stun.md +++ b/docs/admin/networking/stun.md @@ -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). diff --git a/docs/admin/networking/troubleshooting.md b/docs/admin/networking/troubleshooting.md index b884aaf8d0..15f6d76baf 100644 --- a/docs/admin/networking/troubleshooting.md +++ b/docs/admin/networking/troubleshooting.md @@ -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. diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 3fc50b4a15..5d39504567 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -94,7 +94,7 @@ You'll need to configure DNS to point wildcard subdomains to your control plane: *.coder.example.com A ``` -Or alternatively, using a CNAME record: +Or alternatively, using a canonical name (CNAME) record: ```txt *.coder.example.com CNAME coder.example.com diff --git a/docs/admin/setup/appearance.md b/docs/admin/setup/appearance.md index 2a74eed006..4dc8b431ad 100644 --- a/docs/admin/setup/appearance.md +++ b/docs/admin/setup/appearance.md @@ -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 diff --git a/docs/admin/setup/chat-lifecycle-hooks.md b/docs/admin/setup/chat-lifecycle-hooks.md index e8a86ef9a5..b8f9c853e4 100644 --- a/docs/admin/setup/chat-lifecycle-hooks.md +++ b/docs/admin/setup/chat-lifecycle-hooks.md @@ -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:` 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. diff --git a/docs/admin/setup/data-retention.md b/docs/admin/setup/data-retention.md index db476af615..cb331f6c94 100644 --- a/docs/admin/setup/data-retention.md +++ b/docs/admin/setup/data-retention.md @@ -157,13 +157,13 @@ ai_gateway: Common compliance frameworks have varying retention requirements: -- **SOC 2**: +- **System and Organization Controls (SOC) 2**: Typically requires 1 year of audit logs. -- **HIPAA**: +- **Health Insurance Portability and Accountability Act (HIPAA)**: Requires 6 years for certain records. -- **PCI DSS**: +- **Payment Card Industry Data Security Standard (PCI DSS)**: Requires 1 year of audit logs, with 3 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. diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 67f439f5c0..11e7c60fee 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -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 diff --git a/docs/admin/templates/creating-templates.md b/docs/admin/templates/creating-templates.md index dae6ebfcba..d169deb933 100644 --- a/docs/admin/templates/creating-templates.md +++ b/docs/admin/templates/creating-templates.md @@ -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 diff --git a/docs/admin/templates/extending-templates/agent-metadata.md b/docs/admin/templates/extending-templates/agent-metadata.md index 8c5ec70e95..0348709b89 100644 --- a/docs/admin/templates/extending-templates/agent-metadata.md +++ b/docs/admin/templates/extending-templates/agent-metadata.md @@ -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 diff --git a/docs/admin/templates/extending-templates/docker-in-workspaces.md b/docs/admin/templates/extending-templates/docker-in-workspaces.md index d66116e790..bcd0538976 100644 --- a/docs/admin/templates/extending-templates/docker-in-workspaces.md +++ b/docs/admin/templates/extending-templates/docker-in-workspaces.md @@ -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`. diff --git a/docs/admin/templates/extending-templates/dynamic-parameters.md b/docs/admin/templates/extending-templates/dynamic-parameters.md index 0e93425f7f..7b8c7f3bf1 100644 --- a/docs/admin/templates/extending-templates/dynamic-parameters.md +++ b/docs/admin/templates/extending-templates/dynamic-parameters.md @@ -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. diff --git a/docs/admin/templates/extending-templates/icons.md b/docs/admin/templates/extending-templates/icons.md index 5bf89185cb..76daa82f80 100644 --- a/docs/admin/templates/extending-templates/icons.md +++ b/docs/admin/templates/extending-templates/icons.md @@ -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**: diff --git a/docs/admin/templates/extending-templates/index.md b/docs/admin/templates/extending-templates/index.md index 3f988f3f6b..dda252a69d 100644 --- a/docs/admin/templates/extending-templates/index.md +++ b/docs/admin/templates/extending-templates/index.md @@ -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" { 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 diff --git a/docs/admin/templates/extending-templates/jetbrains-airgapped.md b/docs/admin/templates/extending-templates/jetbrains-airgapped.md index bd40be000a..d494acdb74 100644 --- a/docs/admin/templates/extending-templates/jetbrains-airgapped.md +++ b/docs/admin/templates/extending-templates/jetbrains-airgapped.md @@ -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 diff --git a/docs/admin/templates/extending-templates/modules.md b/docs/admin/templates/extending-templates/modules.md index b780053372..fd35879a16 100644 --- a/docs/admin/templates/extending-templates/modules.md +++ b/docs/admin/templates/extending-templates/modules.md @@ -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 diff --git a/docs/admin/templates/extending-templates/parameters.md b/docs/admin/templates/extending-templates/parameters.md index 4bed588dee..d89c375de4 100644 --- a/docs/admin/templates/extending-templates/parameters.md +++ b/docs/admin/templates/extending-templates/parameters.md @@ -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). diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 15a1534225..db753a7458 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -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 diff --git a/docs/admin/templates/extending-templates/process-priority.md b/docs/admin/templates/extending-templates/process-priority.md index 42e20b2093..5bdf463a01 100644 --- a/docs/admin/templates/extending-templates/process-priority.md +++ b/docs/admin/templates/extending-templates/process-priority.md @@ -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 diff --git a/docs/admin/templates/extending-templates/provider-authentication.md b/docs/admin/templates/extending-templates/provider-authentication.md index e4a290337e..85e11eba68 100644 --- a/docs/admin/templates/extending-templates/provider-authentication.md +++ b/docs/admin/templates/extending-templates/provider-authentication.md @@ -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. diff --git a/docs/admin/templates/extending-templates/resource-monitoring.md b/docs/admin/templates/extending-templates/resource-monitoring.md index 2be943192a..9b83330a18 100644 --- a/docs/admin/templates/extending-templates/resource-monitoring.md +++ b/docs/admin/templates/extending-templates/resource-monitoring.md @@ -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 diff --git a/docs/admin/templates/extending-templates/web-ides.md b/docs/admin/templates/extending-templates/web-ides.md index ac21c6f056..23142167d3 100644 --- a/docs/admin/templates/extending-templates/web-ides.md +++ b/docs/admin/templates/extending-templates/web-ides.md @@ -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): diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md index 2f2eca1109..8271e227aa 100644 --- a/docs/admin/templates/extending-templates/workspace-tags.md +++ b/docs/admin/templates/extending-templates/workspace-tags.md @@ -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 diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index be526aed8e..faf810b0ff 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -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 diff --git a/docs/admin/templates/managing-templates/change-management.md b/docs/admin/templates/managing-templates/change-management.md index 3ba719e51b..04c1b92897 100644 --- a/docs/admin/templates/managing-templates/change-management.md +++ b/docs/admin/templates/managing-templates/change-management.md @@ -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, diff --git a/docs/admin/templates/managing-templates/dependencies.md b/docs/admin/templates/managing-templates/dependencies.md index 14f5cc6d6c..27789fd5a8 100644 --- a/docs/admin/templates/managing-templates/dependencies.md +++ b/docs/admin/templates/managing-templates/dependencies.md @@ -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. diff --git a/docs/admin/templates/managing-templates/external-workspaces.md b/docs/admin/templates/managing-templates/external-workspaces.md index c9886aaff6..11baf1acb4 100644 --- a/docs/admin/templates/managing-templates/external-workspaces.md +++ b/docs/admin/templates/managing-templates/external-workspaces.md @@ -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 diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md index f105fa7988..ee9a15198e 100644 --- a/docs/admin/templates/managing-templates/index.md +++ b/docs/admin/templates/managing-templates/index.md @@ -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 diff --git a/docs/admin/templates/managing-templates/schedule.md b/docs/admin/templates/managing-templates/schedule.md index 4455840b73..3ce37b029b 100644 --- a/docs/admin/templates/managing-templates/schedule.md +++ b/docs/admin/templates/managing-templates/schedule.md @@ -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. diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md index 5d86b4df0d..59667e8fa7 100644 --- a/docs/admin/users/github-auth.md +++ b/docs/admin/users/github-auth.md @@ -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 diff --git a/docs/admin/users/groups-roles.md b/docs/admin/users/groups-roles.md index 34a3b1134a..52ba22e516 100644 --- a/docs/admin/users/groups-roles.md +++ b/docs/admin/users/groups-roles.md @@ -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. diff --git a/docs/admin/users/headless-auth.md b/docs/admin/users/headless-auth.md index a99b2dbc07..6f2febd37c 100644 --- a/docs/admin/users/headless-auth.md +++ b/docs/admin/users/headless-auth.md @@ -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. diff --git a/docs/admin/users/idp-sync.md b/docs/admin/users/idp-sync.md index a26d844bd5..8217b771dd 100644 --- a/docs/admin/users/idp-sync.md +++ b/docs/admin/users/idp-sync.md @@ -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.
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.
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.
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.
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).
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.
If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims. | @@ -492,7 +492,7 @@ The 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: diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md index 0c5bc0dcb6..8c3c526913 100644 --- a/docs/admin/users/index.md +++ b/docs/admin/users/index.md @@ -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 diff --git a/docs/admin/users/oidc-auth/google.md b/docs/admin/users/oidc-auth/google.md index 68235a8c9c..0a2c9b9381 100644 --- a/docs/admin/users/oidc-auth/google.md +++ b/docs/admin/users/oidc-auth/google.md @@ -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. diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index f30f4cb584..b63d705dad 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -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 diff --git a/docs/admin/users/oidc-auth/microsoft.md b/docs/admin/users/oidc-auth/microsoft.md index 2c83ee3359..906f1c2bd7 100644 --- a/docs/admin/users/oidc-auth/microsoft.md +++ b/docs/admin/users/oidc-auth/microsoft.md @@ -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 diff --git a/docs/admin/users/oidc-auth/refresh-tokens.md b/docs/admin/users/oidc-auth/refresh-tokens.md index 8cf5d73336..db57046e87 100644 --- a/docs/admin/users/oidc-auth/refresh-tokens.md +++ b/docs/admin/users/oidc-auth/refresh-tokens.md @@ -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. diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index 655ec72bc1..cf5606d6c2 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -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 diff --git a/docs/ai-coder/agent-firewall/index.md b/docs/ai-coder/agent-firewall/index.md index 400baead8f..45408e08f8 100644 --- a/docs/ai-coder/agent-firewall/index.md +++ b/docs/ai-coder/agent-firewall/index.md @@ -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:`** | -| **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:`** | +| **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 | diff --git a/docs/ai-coder/agent-firewall/nsjail/docker.md b/docs/ai-coder/agent-firewall/nsjail/docker.md index 23237127f7..7e30ef1c8b 100644 --- a/docs/ai-coder/agent-firewall/nsjail/docker.md +++ b/docs/ai-coder/agent-firewall/nsjail/docker.md @@ -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` diff --git a/docs/ai-coder/agent-firewall/nsjail/ecs.md b/docs/ai-coder/agent-firewall/nsjail/ecs.md index 6bcc3b9600..0ec7c30739 100644 --- a/docs/ai-coder/agent-firewall/nsjail/ecs.md +++ b/docs/ai-coder/agent-firewall/nsjail/ecs.md @@ -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). --- diff --git a/docs/ai-coder/agent-firewall/nsjail/index.md b/docs/ai-coder/agent-firewall/nsjail/index.md index 79a3b29a3c..55a435ecaf 100644 --- a/docs/ai-coder/agent-firewall/nsjail/index.md +++ b/docs/ai-coder/agent-firewall/nsjail/index.md @@ -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) diff --git a/docs/ai-coder/agent-firewall/nsjail/k8s.md b/docs/ai-coder/agent-firewall/nsjail/k8s.md index 7c3561dca7..4e1c67e080 100644 --- a/docs/ai-coder/agent-firewall/nsjail/k8s.md +++ b/docs/ai-coder/agent-firewall/nsjail/k8s.md @@ -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+). diff --git a/docs/ai-coder/agent-relay/index.md b/docs/ai-coder/agent-relay/index.md index cd93182a0d..9fd30cc4dd 100644 --- a/docs/ai-coder/agent-relay/index.md +++ b/docs/ai-coder/agent-relay/index.md @@ -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. diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index 3dfa30cad0..2f9fee17c7 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -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`. diff --git a/docs/ai-coder/agents/extending-agents.md b/docs/ai-coder/agents/extending-agents.md index 3893121278..a3ee9c0ee1 100644 --- a/docs/ai-coder/agents/extending-agents.md +++ b/docs/ai-coder/agents/extending-agents.md @@ -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 diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index 76ae36c252..b7f3724fa5 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -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. diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index 1b5c4ef110..66e1e4eeb8 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -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.