docs: add documentation for prebuild scheduling feature

coder · evgeniy-scherbina · Jun 20, 2025 · Jun 19, 2025 · Jun 19, 2025 · Jun 20, 2025
commit d26f6638b7868e12a63663879baa9e92d51a2fd2
diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
@@ -12,6 +12,7 @@ Prebuilt workspaces are:
 - 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
 
@@ -111,6 +112,105 @@ prebuilt workspace can remain before it is considered expired and eligible for c
 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.
-2. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
+2. The schedule matching the current time is considered active. Overlapping schedules are prevented by validation rules.
-2. The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
+2. The schedule matching the current time is considered active. Overlapping schedules are prevented by validation rules.
+3. If no schedules match the current time, the base `instances` count is used.
-3. If no schedules match the current time, the base `instances` count is used.
+3. If no schedule matches the current time, the system defaults to the base `instances` count.
-3. If no schedules match the current time, the base `instances` count is used.
+3. If no schedule matches the current time, the system defaults to the base `instances` count.
+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 `*`
- `HOUR`: 0-23, range (e.g., 8-18 for 8AM-6:59PM), or `*`
+- `HOUR`: 8-18, range (e.g., 8-18 for 8AM-6:59PM), or `*`
- `HOUR`: 0-23, range (e.g., 8-18 for 8AM-6:59PM), or `*`
+- `HOUR`: 8-18, 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.
@@ -195,12 +295,6 @@ The prebuilt workspaces feature has these current limitations:
 
   [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