Version: 1.0.x

Reservation Schedules

Reservation schedules let you reserve a higher (or lower) minimum replica count for your agent during specific time windows, without leaving extra capacity warm 24/7.

A schedule has three layers:

Layer	What it is	Example
Default	The `deploy.replicas.min` value from `videosdk.yaml`.	`min: 0`
Recurring	Weekly rules that override the default on specific weekdays.	Mon-Fri, 09:00-18:00 → `min: 3`
Override	One-off rules for specific dates or date ranges.	Black Friday week, all day → `min: 10`

Resolution order: override > recurring > default. Inside the same layer, the highest min wins.

Schedules live declaratively in videosdk.yaml under deploy.replicas.schedule. The CLI pushes them to the cloud automatically when you run videosdk agent deploy, videosdk agent up, or videosdk agent version update.

Configure in videosdk.yaml

deploy:
  id: dep_xxxxxx
  replicas:
    min: 0           # Default layer
    max: 5           # required; schedules cannot exceed this
    schedule:
      timezone: Asia/Kolkata   # IANA timezone (required)
      recurring:
        - name: biz-hours
          days: [MON, TUE, WED, THU, FRI]
          start: '09:00'
          end: '18:00'
          min: 3
        - name: night-shift
          days: [MON, TUE, WED]
          start: '22:00'
          end: '02:00'         # wraps past midnight (allowed)
          min: 1
      overrides:
        - name: diwali
          date: '2026-11-08'    # single date, full day
          min: 0
        - name: blackfri
          dateRange:
            start: '2026-11-27'
            end: '2026-11-29'
          start: '09:00'        # optional partial-day window
          end: '18:00'
          min: 10

Field reference

Field	Required	Description
`replicas.min`	Yes	The Default layer in resolution, used when no recurring rule or override matches.
`replicas.max`	Yes	Hard ceiling. Every `min` in recurring/override rules must be `<= max`.
`schedule.timezone`	Yes	IANA timezone name (e.g. `Asia/Kolkata`, `Europe/Berlin`, `America/New_York`). Find yours in the IANA tz database list.
`recurring[].name`	No	Used by `remove-rule`. Recommended for every rule.
`recurring[].days`	Yes	List of `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, `SUN`.
`recurring[].start` / `end`	Yes	`HH:mm` 24h. `end < start` wraps midnight.
`recurring[].min`	Yes	Integer in `[0, replicas.max]`.
`overrides[].name`	No	Used by `remove-override`. Recommended for every override.
`overrides[].date`	One of	Single date `YYYY-MM-DD`.
`overrides[].dateRange`	One of	`{ start: YYYY-MM-DD, end: YYYY-MM-DD }`. Mutually exclusive with `date`.
`overrides[].start` / `end`	No	Optional partial-day window. Pass both or neither.
`overrides[].min`	Yes	Integer in `[0, replicas.max]`.

tip

Always quote HH:MM values (e.g. '09:00') so YAML doesn't read them as numbers, and use an IANA timezone name such as Asia/Kolkata or America/New_York (not abbreviations like CET). Windows are resolved in that timezone, with daylight saving handled for you.

Add Recurring Rule

Append a weekly recurring rule to videosdk.yaml.

Usage

videosdk agent schedule add-rule [OPTIONS]

Options

Option	Required	Description
`--name`	No	Rule name. Required if you want to `remove-rule` later by name.
`--days`	Yes	Comma-separated weekdays, e.g. `MON,TUE,WED,THU,FRI`.
`--start`	Yes	Start time `HH:mm` (24h).
`--end`	Yes	End time `HH:mm` (24h). If `end < start`, the window wraps midnight.
`--min`	Yes	Effective `minReplica` while the window is active.
`--timezone`	No	IANA timezone. Required only when the schedule has no timezone set yet.

Example Output

$ videosdk agent schedule add-rule \
    --name biz-hours --days MON,TUE,WED,THU,FRI \
    --start 09:00 --end 18:00 --min 3 --timezone Asia/Kolkata

◆ Adding Recurring Rule

✓ Added recurring rule (biz-hours).
ℹ Run `videosdk agent version update` to push the change.

Examples

# Business hours, weekdays
videosdk agent schedule add-rule \
  --name biz-hours --days MON,TUE,WED,THU,FRI \
  --start 09:00 --end 18:00 --min 3 --timezone Asia/Kolkata

# Late-night window that wraps past midnight
videosdk agent schedule add-rule \
  --name night-shift --days MON,TUE,WED \
  --start 22:00 --end 02:00 --min 1

# Weekend-only burst
videosdk agent schedule add-rule \
  --name weekend-peak --days SAT,SUN \
  --start 12:00 --end 23:00 --min 5

Notes

--timezone is only required the first time you add a rule. Subsequent rules reuse the existing schedule.timezone.
Use --name if you ever want to remove the rule by name. Without it, the rule cannot be targeted by remove-rule.
Rules with the same days/window are allowed; the resolver uses the highest min among matching rules.

Remove Recurring Rule

Remove a recurring rule from videosdk.yaml by name.

Usage

videosdk agent schedule remove-rule --name <rule-name>

Options

Option	Required	Description
`--name`	Yes	Name of the recurring rule to remove.

Example Output

$ videosdk agent schedule remove-rule --name biz-hours

◆ Removing Recurring Rule

✓ Removed recurring rule 'biz-hours'.
ℹ Run `videosdk agent version update` to push the change.

Examples

# Remove a single rule
videosdk agent schedule remove-rule --name biz-hours

# Remove a wrapping window rule
videosdk agent schedule remove-rule --name night-shift

Add Override

Append a one-off override to videosdk.yaml. Use a single date for one day, or a date range for multiple consecutive days. An optional partial-day window narrows the effect within those dates.

Usage

videosdk agent schedule add-override [OPTIONS]

Options

Option	Required	Description
`--name`	No	Override name. Required if you want to `remove-override` by name.
`--date`	One of	Single date `YYYY-MM-DD`.
`--date-range`	One of	Date range `YYYY-MM-DD..YYYY-MM-DD`. Mutually exclusive with `--date`.
`--start`	No	Partial-day start `HH:mm` (24h). Must be paired with `--end`.
`--end`	No	Partial-day end `HH:mm` (24h). Must be paired with `--start`.
`--min`	Yes	Effective `minReplica` while the override is active.
`--timezone`	No	IANA timezone. Required only when the schedule has no timezone yet.

Example Output

$ videosdk agent schedule add-override \
    --name diwali --date 2026-11-08 --min 0

◆ Adding Override

✓ Added override (diwali).
ℹ Run `videosdk agent version update` to push the change.

Examples

# Single date, full day, scale down to zero
videosdk agent schedule add-override \
  --name diwali --date 2026-11-08 --min 0

# Date range, scale up for an entire week
videosdk agent schedule add-override \
  --name blackfri --date-range 2026-11-27..2026-11-29 --min 10

# Date range with a partial-day window
videosdk agent schedule add-override \
  --name holiday-shopping --date-range 2026-12-23..2026-12-31 \
  --start 09:00 --end 18:00 --min 8

# Single date with a partial-day window
videosdk agent schedule add-override \
  --name product-launch --date 2026-06-15 \
  --start 18:00 --end 22:00 --min 15

Notes

An override with dateRange plus start/end applies the same partial-day window on every day in the range.
Overrides take precedence over recurring rules. This is useful for temporarily disabling a recurring rule on a specific day without removing it.

Remove Override

Remove an override from videosdk.yaml by name.

Usage

videosdk agent schedule remove-override --name <override-name>

Options

Option	Required	Description
`--name`	Yes	Name of the override to remove.

Example Output

$ videosdk agent schedule remove-override --name diwali

◆ Removing Override

✓ Removed override 'diwali'.
ℹ Run `videosdk agent version update` to push the change.

Examples

# Remove a single override
videosdk agent schedule remove-override --name diwali

# Remove a date-range override
videosdk agent schedule remove-override --name blackfri

Validate

Validate the schedule in videosdk.yaml without calling the API. The same validation runs automatically before up, deploy, and version update push the schedule to the cloud.

Usage

videosdk agent schedule validate

It checks the times, min ranges, timezone, and override dates, and warns about windows that wrap past midnight or overrides already in the past.

Example Output (valid, with a warning)

$ videosdk agent schedule validate

◆ Validating Schedule

! schedule.recurring[1] wraps past midnight (22:00 → 02:00); ensure this is intentional
✓ Schedule is valid.

Example Output (invalid)

$ videosdk agent schedule validate

◆ Validating Schedule

✗ schedule.recurring[0].min must be an integer in [0, 5]

Examples

# Validate after hand-editing videosdk.yaml
videosdk agent schedule validate

# Use validate as a pre-commit check
videosdk agent schedule validate && git commit -am "schedule: update biz-hours"

Show

Render a version's schedule as a table.

Usage

videosdk agent schedule show [OPTIONS]

Options

Option	Short	Description
`--version-id`	`-v`	Version ID. Defaults to `deploy.version` in `videosdk.yaml`.
`--from-yaml`		Render the schedule from `videosdk.yaml` instead of the API.

Use --from-yaml to preview unsaved local edits; without it, the command shows what's actually deployed.

Example Output

$ videosdk agent schedule show --from-yaml

◆ Schedule

  Timezone: Asia/Kolkata

                     Recurring rules
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━┓
┃ Name        ┃ Days                ┃ Window      ┃ min ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━┩
│ biz-hours   │ MON,TUE,WED,THU,FRI │ 09:00-18:00 │   3 │
│ night-shift │ MON,TUE,WED         │ 22:00-02:00 │   1 │
└─────────────┴─────────────────────┴─────────────┴─────┘

                        Overrides
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━┓
┃ Name     ┃ Date                    ┃ Window      ┃ min ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━┩
│ diwali   │ 2026-11-08              │ all day     │   0 │
│ blackfri │ 2026-11-27 → 2026-11-29 │ 09:00-18:00 │  10 │
└──────────┴─────────────────────────┴─────────────┴─────┘

Examples

# Render what's deployed on the API
videosdk agent schedule show

# Render what's in your working tree (no API call)
videosdk agent schedule show --from-yaml

# Show schedule on a specific version
videosdk agent schedule show -v ver_xxxxxx

Current

Show the effective minReplica right now and which layer is active.

Usage

videosdk agent schedule current [OPTIONS]

Options

Option	Short	Description
`--version-id`	`-v`	Version ID. Defaults to `deploy.version` in `videosdk.yaml`.

Example Output

$ videosdk agent schedule current

◆ Effective Schedule (now)

  Effective minReplica: 3
  Default (fallback):   0
  Timezone:             Asia/Kolkata
  Active layer:         recurring
  Rule name:            biz-hours
  Window:               09:00-18:00 on MON,TUE,WED,THU,FRI

Examples

# Effective min for the version in videosdk.yaml
videosdk agent schedule current

# Effective min for a specific version
videosdk agent schedule current -v ver_xxxxxx

Preview

Project a transition timeline for the next N days using the schedule in videosdk.yaml, plus a comparison of projected min-hours/week versus an always-on baseline.

Usage

videosdk agent schedule preview [OPTIONS]

Options

Option	Description	Default
`--days`	Number of days to project (integer in `[1, 30]`).	`7`

Example Output

$ videosdk agent schedule preview --days 7

◆ Schedule Preview (7 days)

  Timezone: Asia/Kolkata
  Default minReplica: 0

                 Transitions
┏━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━┳━━━━━━━━━━━━━┓
┃ Day            ┃ Time  ┃ min ┃ Source      ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━╇━━━━━━━━━━━━━┩
│ Mon 2026-06-01 │ 09:00 │   3 │ biz-hours   │
│                │ 18:00 │   0 │ default     │
│ Mon 2026-06-01 │ 22:00 │   1 │ night-shift │
│ Tue 2026-06-02 │ 02:00 │   0 │ default     │
│                │ 09:00 │   3 │ biz-hours   │
└────────────────┴───────┴─────┴─────────────┘

  Projected min-hours/week: 138  vs always-on 168  (+18% vs always-on)

Source: default rows mean no rule was active at that moment. The effective min fell back to replicas.min.

Examples

# Default 7-day projection
videosdk agent schedule preview

# Two-week projection (useful when overrides land >7 days out)
videosdk agent schedule preview --days 14

# Single-day preview (debugging a specific recurring rule)
videosdk agent schedule preview --days 1

Clear

Remove the schedule on a version on the server. The version reverts to its default minReplica until a new schedule is pushed.

By default, after the server-side clear succeeds, the CLI prompts you to also remove deploy.replicas.schedule from videosdk.yaml. Without this step, the next videosdk agent up, deploy, or version update would re-push the same schedule from the yaml.

Usage

videosdk agent schedule clear [OPTIONS]

Options

Option	Short	Description
`--version-id`	`-v`	Version ID. Defaults to `deploy.version` in `videosdk.yaml`.
`--yes`	`-y`	Also remove the schedule from `videosdk.yaml` without prompting.
`--keep-yaml`		Keep the schedule in `videosdk.yaml` (skip the removal prompt).

--yes and --keep-yaml are mutually exclusive.

Example Output (interactive)

$ videosdk agent schedule clear -v ver123

◆ Clearing Schedule

  Version ID: ver123

✓ Schedule cleared on the server.
! videosdk.yaml still contains a schedule. Next `up` / `deploy` / `version update` will re-push it.
Also remove deploy.replicas.schedule from videosdk.yaml? [Y/n]: y
✓ Schedule removed from videosdk.yaml.

Examples

# Interactive: prompt to remove from yaml after the server clear
videosdk agent schedule clear -v ver123

# Clear on server AND remove from yaml in one shot (no prompt)
videosdk agent schedule clear -v ver123 --yes

# Clear on server only, leave yaml untouched (no prompt)
videosdk agent schedule clear -v ver123 --keep-yaml

tip

If you only want to remove a single rule or override (not the whole schedule), use videosdk agent schedule remove-rule --name ... or videosdk agent schedule remove-override --name ... instead.

Pushing the schedule to the cloud

You don't run a separate "apply" command. Any of these will pick up deploy.replicas.schedule from videosdk.yaml, validate it, and send it to the cloud:

Command	What it does
`videosdk agent up`	Build + push + create a new version with the schedule attached.
`videosdk agent deploy`	Create a new version with the schedule attached.
`videosdk agent version update`	Update the existing version (from `deploy.version`) with the schedule.

If the schedule fails validation, the command exits before making any API call.

Schedules are per-version, per-region

A schedule is attached to a version, and each version is region-specific (deploy.region). If you maintain multiple versions across regions, deploy and version update apply the schedule only to the targeted version. To keep regional versions in sync, update each version independently.

Resolution model

Given a moment in time, the effective minReplica is resolved as:

Overrides: every override whose date (or date range) matches today is considered. If any of them are time-bounded, only those whose window contains "now" apply. Among the applicable overrides, the highest min wins.
Recurring: if no override applied, every recurring rule whose days includes today and whose window contains "now" is considered. Highest min wins.
Default: if no rule applied, fall back to replicas.min.

Quick Reference

Command	Description
`videosdk agent schedule add-rule`	Append a recurring weekly rule to `videosdk.yaml`.
`videosdk agent schedule remove-rule`	Remove a recurring rule by name.
`videosdk agent schedule add-override`	Append a date or date-range override.
`videosdk agent schedule remove-override`	Remove an override by name.
`videosdk agent schedule validate`	Validate the schedule in `videosdk.yaml`.
`videosdk agent schedule show`	Render the schedule from the API (or `--from-yaml`).
`videosdk agent schedule current`	Show the effective `minReplica` right now.
`videosdk agent schedule preview`	Project the transition timeline + cost estimate.
`videosdk agent schedule clear`	Remove the schedule from a version on the server.

Workflow Example

A typical end-to-end workflow for setting up, validating, deploying, and tearing down a reservation schedule:

# 1. Add a recurring rule and an override
videosdk agent schedule add-rule \
  --name biz-hours --days MON,TUE,WED,THU,FRI \
  --start 09:00 --end 18:00 --min 3 --timezone Asia/Kolkata

videosdk agent schedule add-override \
  --name diwali --date 2026-11-08 --min 0

# 2. Sanity-check locally
videosdk agent schedule validate
videosdk agent schedule show --from-yaml
videosdk agent schedule preview --days 7

# 3. Push to the cloud (any of these works)
videosdk agent up --skip-build --skip-push
# or
videosdk agent version update
# or
videosdk agent deploy

# 4. Confirm the live state
videosdk agent schedule show
videosdk agent schedule current

# 5. Tear it all down
videosdk agent schedule clear -v $(videosdk agent version describe | awk '/Version ID/ {print $3}')

Next Steps

Push your schedule with Deploy or Up & Down.
Wire credentials with Environment Secrets and Image Pull Secrets.
Track running agents via Sessions.

Got a Question? Ask us on discord

Configure in videosdk.yaml​

Field reference​

Add Recurring Rule​

Usage​

Options​

Example Output​

Examples​

Notes​

Remove Recurring Rule​

Usage​

Options​

Example Output​

Examples​

Add Override​

Usage​

Options​

Example Output​

Examples​

Notes​

Remove Override​

Usage​

Options​

Example Output​

Examples​

Validate​

Usage​

Example Output (valid, with a warning)​

Example Output (invalid)​

Examples​

Show​

Usage​

Options​

Example Output​

Examples​

Current​

Usage​

Options​

Example Output​

Examples​

Preview​

Usage​

Options​

Example Output​

Examples​

Clear​

Usage​

Options​

Example Output (interactive)​

Examples​

Pushing the schedule to the cloud​

Resolution model​

Quick Reference​

Workflow Example​

Next Steps​

Configure in videosdk.yaml

Field reference

Add Recurring Rule

Usage

Options

Example Output

Examples

Notes

Remove Recurring Rule

Usage

Options

Example Output

Examples

Add Override

Usage

Options

Example Output

Examples

Notes

Remove Override

Usage

Options

Example Output

Examples

Validate

Usage

Example Output (valid, with a warning)

Example Output (invalid)

Examples

Show

Usage

Options

Example Output

Examples

Current

Usage

Options

Example Output

Examples

Preview

Usage

Options

Example Output

Examples

Clear

Usage

Options

Example Output (interactive)

Examples

Pushing the schedule to the cloud

Resolution model

Quick Reference

Workflow Example

Next Steps