DRAFT: I'd like feedback on this approach for 1k before I give the others the same treatment and add a 10k document.
- Bumps database requirements to 8 vCPU, 30 GB memory. In our testing database was nearly always the bottleneck. (This could come back down again with improvements to how we use it.)
- Removes specific machine type recommendations.
- This only applies to VM-based deployments and many of our customers use Kubernetes.
- The major clouds upgrade their machine teirs, so our recommendations go out of date
- In its place we just give CPU and memory requirements
- Removes API requests per second
- It's not a metric that many operators will know until they are already operating
- Our API requests vary wildly in cost depending on what they are
- Replaces them with Users | Running Workspaces | Concurrent Builds - which represents our scale testing scenarios, and are easier for operators to reason about.
- Removes specific advice about workspace sizing, instead gives the minimum specs for the agent
- Gives Kubernetes resource request/limits in notes
- Adds advice about not needing high performance disks for Coderd, but that provisioners will benefit.
**Breaking Change:** Existing oauth apps might now use PKCE. If an
unknown IdP type was being used, and it does not support PKCE, it will
break.
To fix, set the PKCE methods on the external auth to `none`
```
export CODER_EXTERNAL_AUTH_1_PKCE_METHODS=none
```
The user guide jumped straight into integration details without explaining
what dev containers are. Now it opens with a brief orientation linking to
the spec, then explains this guide covers the Docker-based approach.
Converted several NOTE callouts to prose where they were just cross-references
or stacked unnecessarily. The Envbuilder index note was reframed to lead with
its strengths rather than "we recommend the other thing."
Also updates platform support to Linux only per current status.
Refs #21157
Dev container admin docs were scattered across two locations: the Docker-based
integration under extending-templates/ and Envbuilder under managing-templates/.
There was no landing page explaining that two approaches exist or helping admins
choose between them.
This moves everything under admin/integrations/devcontainers/ with a decision
guide at the top. Dev containers are an integration with the dev container
specification, so integrations/ is a natural fit alongside JFrog, Vault, etc.
Stub pages remain at the original locations for discoverability.
New structure:
admin/integrations/devcontainers/
├── index.md # Landing page + decision guide
├── integration.md # Docker-based dev containers
└── envbuilder/
├── index.md
├── add-envbuilder.md
├── envbuilder-security-caching.md
└── envbuilder-releases-known-issues.md
Refs #21080
docs: rewrite dev containers documentation for GA
Corrects inaccuracies in SSH examples (deprecated `--container` flag),
port forwarding (native sub-agent forwarding is primary), and
prerequisites (dev containers are on by default). Fixes template
descriptions: docker-devcontainer uses native Dev Containers while
AWS/Kubernetes templates use Envbuilder.
Renames admin docs folder from `devcontainers/` to `envbuilder/` to
reflect actual content. Adds customization guide documenting agent
naming, display apps, custom apps, and variable interpolation. Documents
multi-repo workspace support and adds note about Terraform module
limitations with sub-agents. Fixes module registry URLs.
Refs #18907
Removes references to adding database replicas from the scaling docs, as Coder only allows a single connection URL. These passages where added in error.
Previously AI Bridge retention was only documented in the auto-generated
CLI reference, making it difficult for administrators to discover and
understand how to configure data retention for compliance requirements.
This adds retention configuration to the AI Bridge setup guide with
examples, documents the REST API and CLI export options in the monitoring
guide, and cross-references AI Bridge from the central data retention
page for discoverability.
Closes#21038
Replace hardcoded 7-day retention for workspace agent logs with
configurable retention from deployment settings. Defaults to 7d to
preserve existing behavior.
Depends on #21038
Updates #20743
Document configurable retention policies for Audit Logs, Connection Logs,
and API keys. Add new data-retention.md page and update existing docs to
reference it.
Depends on #21021
Updates #20743
## Problem
Tasks currently only expose a machine-friendly name field (e.g.
`task-python-debug-a1b2`), but this value is primarily an identifier
rather than a clean, descriptive label. We need a separate
display-friendly name for use in the UI.
This PR introduces a new `display_name` field and updates the task-name
generation flow. The Claude system prompt was updated to return valid
JSON with both `name` and `display_name`. The name generation logic
follows a fallback chain (Anthropic > prompt sanitization > random
fallback). To make task names more closely resemble their display names,
the legacy `task-` prefix has been removed. For context, PR
https://github.com/coder/coder/pull/20834 introduced a small Task icon
to the workspace list to help identify workspaces associated to tasks.
## Changes
- Database migration: Added `display_name` column to tasks table
- Updated system prompt to generate both task name and display name as
valid JSON
- Task name generation now follows a fallback chain: Anthropic > prompt
sanitization > random fallback
- Removed `task-` prefix from task names to allow more descriptive names
- Note: PR https://github.com/coder/coder/pull/20834 adds a Task icon to
workspaces in the workspace list to distinguish task-created workspaces
**Note:** UI changes will be addressed in a follow-up PR
Related to: https://github.com/coder/coder/issues/20801
Updates the dev containers documentation to accurately reflect that the
feature is generally available and document all configuration options.
Closes https://github.com/coder/internal/issues/1138
---
🤖 PR was written by Claude Sonnet 4.5 Thinking using [Coder
Mux](https://github.com/coder/cmux) and reviewed by a human 👩
## Description
Adds a brief section to the API & Session Tokens documentation
explaining API key scopes.
## Changes
- Added "API Key Scopes" section to
`docs/admin/users/sessions-tokens.md`
- Includes overview of scope functionality and security benefits
- Documents scope format (`resource:action`) and wildcard usage
- Provides CLI examples for creating scoped tokens
- Lists common scope examples with descriptions
## Motivation
Users need documentation on how to create and use scoped API tokens for
improved security by limiting token permissions to only necessary
operations.
## Testing
- Reviewed documentation formatting
- Verified markdown structure
- Confirmed examples are accurate
For experimental and dogfood purposes, this adds the ability to opt in a single template.
Leaving the rest of the templates as is.
For GA, this setting might be removed or changed.
Propose Microsoft Entra ID OIDC Directions for Admin Documentation based
on my personal experience / setup.
Propose information on changing access URL in Tutorials -> FAQs
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: DevCats <chris@dualriver.com>
Co-authored-by: DevelopmentCats <christofer@coder.com>
## Add Dynamic Parameters test procedure to 10k users validated architecture
This PR adds a new test procedure for Dynamic Parameters to the 10k users validated architecture documentation. No changes to the recommended hardware specs as this test case succeeded with no issues.
Adds a new document for our ongoing efforts achieving 10k user scale. The content is caveated as work in progress, but represents what we have tested so far.
closes: https://github.com/coder/internal/issues/1025
## Description
Add missing provisionerd metrics to Prometheus documentation:
* `coderd_provisionerd_num_daemons`: The number of provisioner daemons.
* `coderd_provisionerd_workspace_build_timings_seconds`: The time taken
for a workspace to build.
Related to internal thread:
https://codercom.slack.com/archives/C07GRNNRW03/p1760642020583019
## Description
Follow-up from: https://github.com/coder/coder/pull/20305 to include a
note about `coder_workspace_tags` being cumulative and a new step to
validate the status of the prebuild provisioners.
Fix steps formatting.
## Description
Update the Prebuilds troubleshooting page to include a new section,
“Preventing prebuild queue contention (recommended)”, outlining a
best-practice configuration to prevent prebuild jobs from overwhelming
the provisioner queue.
This setup introduces a dedicated prebuild provisioner pool and has been
successfully tested internally in dogfood:
https://github.com/coder/dogfood/pull/201
Closes: https://github.com/coder/coder/issues/20241
This PR adds troubleshooting steps to guide Coder operators when they
suspect that prebuilds might have overwhelmed their deployments.
Closes https://github.com/coder/coder/issues/19490
---------
Co-authored-by: Susana Ferreira <susana@coder.com>
Audit Log entries can be deleted safely (with appropriate caveats), but
we don't specifically call this out in the docs.
---------
Signed-off-by: Danny Kopping <danny@coder.com>
Solves #15575
Adds OAuth access token revocation when unlinking external auth
provider. Due to revocation not being consistently implemented by
providers this is only best effort attempt. Unsuccessful revocation
won't influence link removal.
Dynamic parameters are now GA as of v2.25.0, so this PR updates the
troubleshooting section to remove outdated beta references and clarify
current support.
**Changes:**
- Updated "Template variables not showing up" section to remove beta
references
- Clarified that template variables are fully supported in GA version
- Simplified troubleshooting guidance
Fixes the outdated documentation mentioned in the Slack thread.
---------
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: bpmct <22407953+bpmct@users.noreply.github.com>
Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com>
## Description
Adds support for sending an ad‑hoc custom notification to the
authenticated user via API and CLI. This is useful for surfacing the
result of scripts or long‑running tasks. Notifications are delivered
through the configured method and the dashboard Inbox, respecting
existing preferences and delivery settings.
## Changes
* New notification template: “Custom Notification” with a label for a
custom title and a custom message.
* New API endpoint: `POST /api/v2/notifications/custom` to send a custom
notification to the requesting user.
* New API endpoint: `GET /notifications/templates/custom` to get custom
notification template.
* New CLI subcommand: `coder notifications custom <title> <message>` to
send a custom notification to the requesting user.
* Documentation updates: Add a “Custom notifications” section under
Administration > Monitoring > Notifications, including instructions on
sending custom notifications and examples of when to use them.
Closes: https://github.com/coder/coder/issues/19611
I noticed that our docs mention the possibility of using the
Tailscale-managed DERP server fleet.
https://github.com/coder/coder/pull/15901 changed the phrasing from
> However, Tailscale has graciously allowed us to use
to
> However, our Wireguard integration through Tailscale has graciously
allowed us to use
This change alters the original meaning of the sentence. AFAIK, the
original meant that we contacted Tailscale directly and asked if it
would be ok for our customers to use the Tailscale-managed DERP server
fleet, and Tailscale graciously agreed. The new phrasing conveys
something different. This PR reverts the phrasing to the original.
---------
Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com>
Steven Masley