# Scheduling

> Start and stop the instance on time windows, with modes you can change from a tag at runtime.

A scheduler Lambda starts and stops instances on the windows you define. It
reconciles every 15 minutes and at each window boundary.

## Windows

```hcl
module "workspace" {
  source  = "douklar/agent-workspace/aws"
  version = "~> 2.0"

  instance_schedule_windows = [
    {
      name       = "evenings"
      timezone   = "Europe/Berlin"
      days       = ["MON", "TUE", "WED", "THU", "FRI"]
      start_time = "18:30"
      stop_time  = "23:00"
    },
    {
      name       = "weekends"
      timezone   = "Europe/Berlin"
      days       = ["SAT", "SUN"]
      start_time = "11:00"
      stop_time  = "22:00"
    }
  ]
}
```

Rules for windows:

- An instance is on if **any** window of its cohort matches; otherwise it is stopped.
- Each window has its own IANA timezone.
- `start_time` must be earlier than `stop_time`. To run across midnight,
  split into two windows, for example `22:00`–`23:59` and `00:00`–`06:00`.
- `00:00` to `23:59` runs all day.

## Modes: the `scheduler` tag

Each instance's `scheduler` tag decides what the scheduler does. Change it at
runtime; Terraform will not revert it. Set the starting value with
`scheduler_mode`.

| Tag value | Behaviour |
|---|---|
| `free-time` (default) | Follows the windows |
| `on-demand` | Kept running: started if stopped; the scheduler does not stop it |
| `disabled` | Ignored by the scheduler |

```bash
aws ec2 create-tags --resources i-0123456789abcdef0 --tags Key=scheduler,Value=on-demand
```

If the scheduler cannot evaluate a schedule, for example because of an unknown
timezone, it leaves the instance running instead of stopping it.

## Cohorts and other instances

Windows can carry a `mode` name, which makes a cohort; an instance whose tag
names that cohort follows those windows. Any EC2 instance in the Region with a
`scheduler` tag can join, and the Lambda's IAM permissions are scoped to
instances that carry the tag.

Source: https://douklar.app/docs/agent-workspace/scheduling (Agent Workspace docs, last checked 2026-10-17)