Aug 22, 2025 · Jul 9, 2025 · Jul 9, 2025 · Jul 30, 2025 · Jul 30, 2025 · Aug 22, 2025
diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
 # Prebuilt workspaces

 > [!WARNING]
 > Prebuilds Compatibility Limitations:
 > Prebuilt workspaces currently do not work reliably with [DevContainers feature](../managing-templates/devcontainers/index.md).
 > If your project relies on DevContainer configuration, we recommend disabling prebuilds or carefully testing behavior before enabling them.
 >
 > We’re actively working to improve compatibility, but for now, please avoid using prebuilds with this feature to ensure stability and expected behavior.
 Prebuilt workspaces (prebuilds) reduce workspace creation time with an automatically-maintained pool of
 ready-to-use workspaces for specific parameter presets.

 Prebuilt workspaces allow template administrators to improve the developer experience by reducing workspace
 creation time with an automatically maintained pool of ready-to-use workspaces for specific parameter presets.

 The template administrator configures a template to provision prebuilt workspaces in the background, and then when a developer creates
 a new workspace that matches the preset, Coder assigns them an existing prebuilt instance.
 Prebuilt workspaces significantly reduce wait times, especially for templates with complex provisioning or lengthy startup procedures.
 The template administrator defines the prebuilt workspace's parameters and number of instances to keep provisioned.
 The desired number of workspaces are then provisioned transparently.
 When a developer creates a new workspace that matches the definition, Coder assigns them an existing prebuilt workspace.
 This significantly reduces wait times, especially for templates with complex provisioning or lengthy startup procedures.

 Prebuilt workspaces are:

 - Monitored and replaced automatically to maintain your desired pool size.
 - 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.

 ## Relationship to workspace presets

 Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets):
     prebuilds {
       instances = 3   # Number of prebuilt workspaces to maintain
       expiration_policy {
          ttl = 86400  # Time (in seconds) after which unclaimed prebuilds are expired (1 day)
          ttl = 86400  # Time (in seconds) after which unclaimed prebuilds are expired (86400 =1 day)
      }
     }
   }

 **Scheduling configuration:**

 -**`timezone`**:The timezone for all cron expressions (required). Only a single timezone is supported per scheduling configuration.
 -**`schedule`**: One or more schedule blocks defining when to scale to specific instance counts.
  -**`cron`**:Cron expression interpreted as continuous time ranges (required).
  -**`instances`**:Number of prebuilt workspaces to maintain during this schedule (required).
 - `timezone`: (Required)The timezone for all cron expressions. Only a single timezone is supported per scheduling configuration.
 - `schedule`: One or more schedule blocks defining when to scale to specific instance counts.
  - `cron`: (Required)Cron expression interpreted as continuous time ranges.
  - `instances`: (Required)Number of prebuilt workspaces to maintain during this schedule.

 **How scheduling works:**

 1. The reconciliation loop evaluates all active schedules every reconciliation interval (`CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`).
 2. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
 3. If no schedules match the current time, the base `instances` count is used.
 4. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count.
 1. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
 1. If no schedules match the current time, the base `instances` count is used.
 1. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count.

 **Cron expression format:**

 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:
   - Youmay delete the existing prebuilt workspaces manually.
   - Youcan delete the existing prebuilt workspaces manually.
   - Coder will automatically create new prebuilt workspaces with the updated dependencies.

 The system always maintains the desired number of prebuilt workspaces for the active template version.
 has [`ForceNew`](https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/ec2/ec2_instance.go#L75-L81) set,
 since the AMI cannot be changed in-place._

 #### Updating claimed prebuilt workspace templates

 Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent
 does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840)
 and will be addressed before the next release (v2.23). In the interim, a simple workaround is to restart the workspace
 when it is in this problematic state.

 ### Monitoring and observability

 #### Available metrics
Original file line number	Diff line number	Diff line change
		@@ -1,18 +1,12 @@
		# Prebuilt workspaces

		> [!WARNING]
		> Prebuilds Compatibility Limitations:
		> Prebuilt workspaces currently do not work reliably with [DevContainers feature](../managing-templates/devcontainers/index.md).
		> If your project relies on DevContainer configuration, we recommend disabling prebuilds or carefully testing behavior before enabling them.
		>
		> We’re actively working to improve compatibility, but for now, please avoid using prebuilds with this feature to ensure stability and expected behavior.
		Prebuilt workspaces (prebuilds) reduce workspace creation time with an automatically-maintained pool of
		ready-to-use workspaces for specific parameter presets.

		Prebuilt workspaces allow template administrators to improve the developer experience by reducing workspace
		creation time with an automatically maintained pool of ready-to-use workspaces for specific parameter presets.

		The template administrator configures a template to provision prebuilt workspaces in the background, and then when a developer creates
		a new workspace that matches the preset, Coder assigns them an existing prebuilt instance.
		Prebuilt workspaces significantly reduce wait times, especially for templates with complex provisioning or lengthy startup procedures.
		The template administrator defines the prebuilt workspace's parameters and number of instances to keep provisioned.
SasSwart marked this conversation as resolved. Show resolvedHide resolved
		The desired number of workspaces are then provisioned transparently.
		When a developer creates a new workspace that matches the definition, Coder assigns them an existing prebuilt workspace.
		This significantly reduces wait times, especially for templates with complex provisioning or lengthy startup procedures.

		Prebuilt workspaces are:

Expand All		@@ -21,6 +15,9 @@ Prebuilt workspaces are:
		- Monitored and replaced automatically to maintain your desired pool size.
		- 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.

		## Relationship to workspace presets

		Prebuilt workspaces are tightly integrated with [workspace presets](./parameters.md#workspace-presets):
Expand DownExpand Up		@@ -53,7 +50,7 @@ instances your Coder deployment should maintain, and optionally configure a `exp
		prebuilds {
		instances = 3 # Number of prebuilt workspaces to maintain
		expiration_policy {
		ttl = 86400 # Time (in seconds) after which unclaimed prebuilds are expired (1 day)
		ttl = 86400 # Time (in seconds) after which unclaimed prebuilds are expired (86400 =1 day)
		}
		}
		}
Expand DownExpand Up		@@ -159,17 +156,17 @@ data "coder_workspace_preset" "goland" {

		Scheduling configuration:

		-`timezone`:The timezone for all cron expressions (required). Only a single timezone is supported per scheduling configuration.
		-`schedule`: One or more schedule blocks defining when to scale to specific instance counts.
		-`cron`:Cron expression interpreted as continuous time ranges (required).
		-`instances`:Number of prebuilt workspaces to maintain during this schedule (required).
		- `timezone`: (Required)The timezone for all cron expressions. Only a single timezone is supported per scheduling configuration.
		- `schedule`: One or more schedule blocks defining when to scale to specific instance counts.
		- `cron`: (Required)Cron expression interpreted as continuous time ranges.
		- `instances`: (Required)Number of prebuilt workspaces to maintain during this schedule.

		How scheduling works:

		1. The reconciliation loop evaluates all active schedules every reconciliation interval (`CODER_WORKSPACE_PREBUILDS_RECONCILIATION_INTERVAL`).
		2. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
		3. If no schedules match the current time, the base `instances` count is used.
		4. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count.
		1. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
EdwardAngert marked this conversation as resolved. Show resolvedHide resolved
		1. If no schedules match the current time, the base `instances` count is used.
		1. The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count.

		Cron expression format:

Expand DownExpand Up		@@ -227,7 +224,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:
		- Youmay delete the existing prebuilt workspaces manually.
		- Youcan delete the existing prebuilt workspaces manually.
		- Coder will automatically create new prebuilt workspaces with the updated dependencies.

		The system always maintains the desired number of prebuilt workspaces for the active template version.
Expand DownExpand Up		@@ -285,13 +282,6 @@ For example, the [`ami`](https://registry.terraform.io/providers/hashicorp/aws/l
		has [`ForceNew`](https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/ec2/ec2_instance.go#L75-L81) set,
		since the AMI cannot be changed in-place._

		#### Updating claimed prebuilt workspace templates

		Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent
		does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840)
		and will be addressed before the next release (v2.23). In the interim, a simple workaround is to restart the workspace
		when it is in this problematic state.

		### Monitoring and observability

		#### Available metrics
Expand Down