Jun 20, 2025 · Jun 19, 2025 · Jun 19, 2025 · Jun 20, 2025 · Jun 20, 2025 · Jun 20, 2025
diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
 - Created and maintained automatically by Coder to match your specified preset configurations.
 - Claimed transparently when developers create workspaces.
 - Monitored and replaced automatically to maintain your desired pool size.
 - Automatically scaled based on time-based schedules to optimize resource usage.

 ## Relationship to workspace presets

 Expired prebuilt workspaces are removed during the reconciliation loop to avoid stale environments and resource waste.
 New prebuilt workspaces are only created to maintain the desired count if needed.

 ### Scheduling and time-based scaling

 Prebuilt workspaces support time-based scheduling to scale the number of instances based on usage patterns.
 This allows you to reduce resource costs during off-hours while maintaining availability during peak usage times.

 Configure scheduling by adding a `scheduling` block within your `prebuilds` configuration:

 ```hcl
 data "coder_workspace_preset" "goland" {
   name = "GoLand: Large"
   parameters {
     jetbrains_ide = "GO"
     cpus          = 8
     memory        = 16
   }

   prebuilds {
     instances = 0                  # default to 0 instances

     scheduling {
       timezone = "UTC"             # only a single timezone may be used for simplicity

       # scale to 3 instances during the work week
       schedule {
         cron = "* 8-18 * * 1-5"    # from 8AM-6:59PM, Mon-Fri, UTC
         instances = 3              # scale to 3 instances
       }

       # scale to 1 instance on Saturdays for urgent support queries
       schedule {
         cron = "* 8-14 * * 6"      # from 8AM-2:59PM, Sat, UTC
         instances = 1              # scale to 1 instance
       }
     }
   }
 }
 ```

 **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).

 **How scheduling works:**

 1. Coder evaluates all active schedules at regular intervals.
 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.

 **Cron expression format:**

 Cron expressions follow the format: `* HOUR DOM MONTH DAY-OF-WEEK`

 - `*` (minute): Must always be `*` to ensure the schedule covers entire hours rather than specific minute intervals
 - `HOUR`: 0-23, range (e.g., 8-18 for 8AM-6:59PM), or `*`
 - `DOM` (day-of-month): 1-31, range, or `*`
 - `MONTH`: 1-12, range, or `*`
 - `DAY-OF-WEEK`: 0-6 (Sunday=0, Saturday=6), range (e.g., 1-5 for Monday to Friday), or `*`

 **Important notes about cron expressions:**

 - **Minutes must always be `*`**: To ensure the schedule covers entire hours
 - **Time ranges are continuous**: A range like `8-18` means from 8AM to 6:59PM (inclusive of both start and end hours)
 - **Weekday ranges**: `1-5` means Monday through Friday (Monday=1, Friday=5)
 - **No overlapping schedules**: The validation system prevents overlapping schedules.

 **Example schedules:**

 ```hcl
 # Business hours only (8AM-6:59PM, Mon-Fri)
 schedule {
  cron = "* 8-18 * * 1-5"
  instances = 5
 }

 # 24/7 coverage with reduced capacity overnight and on weekends
 schedule {
  cron = "* 8-18 * * 1-5"  # Business hours (8AM-6:59PM, Mon-Fri)
  instances = 10
 }
 schedule {
  cron = "* 19-23,0-7 * * 1,5"  # Evenings and nights (7PM-11:59PM, 12AM-7:59AM, Mon-Fri)
  instances = 2
 }
 schedule {
  cron = "* * * * 6,0"  # Weekends
  instances = 2
 }

 # Weekend support (10AM-4:59PM, Sat-Sun)
 schedule {
  cron = "* 10-16 * * 6,0"
  instances = 1
 }
 ```

 ### Template updates and the prebuilt workspace lifecycle

 Prebuilt workspaces are not updated after they are provisioned.

  [View issue](https://github.com/coder/internal/issues/364)

 - **Autoscaling**

  Prebuilt workspaces remain running until claimed. There's no automated mechanism to reduce instances during off-hours.

  [View issue](https://github.com/coder/internal/issues/312)

 ### Monitoring and observability

 #### Available metrics