Sync on a schedule

A Synchronization Schedule makes a Follower Machine apply the latest Profile Revision at a fixed time, daily or on chosen weekdays, with nobody at the keyboard. Canonfig installs a job in the operating system's own scheduler: a systemd user timer on Linux, a launchd agent on macOS, and a Task Scheduler task on Windows. Each run does the same as canonfig sync --apply --no-input.

A Follower Machine has no schedule until you set one on it. Publishing a profile or running sync never installs one.

Before you start

• The Follower Machine is enrolled and has applied its profile at least once. On a machine that is not enrolled, schedule set fails with "canonfig schedule set needs an enrolled follower; enroll, then apply the selected profile first".
• Run schedule set from the Canonfig installation you use every day. The job records that installation's location and the Node.js it runs on.
• The job runs only while you are logged in, except on Linux with lingering turned on. See Keep the job running while you are logged out.

Schedule a daily or weekly sync

On the Follower Machine, sync every day at 09:00 in the machine's time zone:

canonfig schedule set daily@09:00

Or sync on chosen weekdays:

canonfig schedule set weekly:Mon,Thu@12:30

Weekdays are Mon, Tue, Wed, Thu, Fri, Sat, and Sun. The time is 24-hour HH:mm. Cron expressions are not accepted.

schedule set prints the time zone it used, the next run time in UTC (nextRun), and any warnings. If that time has passed today, the first run is the next occurrence; schedule set does not start a run. Running the same command again changes nothing.

To change the schedule, run schedule set with another calendar. It replaces the old one.

Use the profile's suggested schedule

A Machine Profile can suggest a schedule with scheduleDefault (see the profile file reference). Sync never installs it. When the Follower Machine has no schedule, sync --plan, sync --apply, and schedule status tell you about it:

schedule available: the profile suggests daily@04:30 in this machine's time zone; run canonfig schedule set --default to install it

To accept it:

canonfig schedule set --default

The Follower Machine then follows the profile: when a later Profile Revision changes the suggested schedule, the next apply updates the job. If a Profile Revision drops the suggestion, the next apply removes the job and says so; run canonfig schedule set daily@09:00 (or another calendar) to keep one.

Pin the schedule to a time zone (Linux only)

On Linux, you can run at a time in a named IANA time zone instead of the machine's own:

canonfig schedule set weekly:Mon@12:30 --timezone Europe/Paris

Canonfig corrects the capitalization of zone names, so europe/paris becomes Europe/Paris. Numeric offsets such as +05:30 are refused.

On macOS and Windows, the native scheduler always uses the machine's time zone, so --timezone is refused there. Run the command again without it.

Keep the job running while you are logged out

canonfig status and canonfig doctor warn you about this. On Linux without lingering:

the systemd user manager stops when you log out (Linger=no), so the job only runs while you are logged in; run loginctl enable-linger alex to run it while logged out

On Windows, always:

the Task Scheduler task uses an interactive logon, so it only runs while you are logged on to Windows; a run due while you are logged off or the machine is off is skipped, not caught up

When a Windows run was due and did not start, they add a warning that names it, starting "the scheduled run at <time> did not start". Run canonfig sync --apply to catch up by hand.

On Windows, the task starts on battery power and keeps running when you unplug the machine. It does not stop the machine from sleeping or shutting down.

If the Follower Machine reaches the Source Machine through a managed SSH tunnel, a scheduled run restarts the tunnel once, if it is down, before it fetches. See Run Canonfig unattended.

Check that the schedule works

canonfig schedule status

schedule status reports what the operating system will run, including changes you made to the job yourself. It shows the time zone, the next run, the last run, and one of these states:

canonfig doctor fails its scheduler probe in every state where the job will not run as chosen. Both doctor and status report the last unattended run, for example:

the last unattended run failed at 2026-11-02T09:00:04.512Z: <reason>; the last completed one was at 2026-11-01T09:00:03.977Z

so you can see a failed scheduled run without reading scheduler logs.

Turn the schedule back on, or off for good

If you disable, stop, or delete the job yourself, Canonfig leaves it that way. status and doctor report "automation disabled outside Canonfig" and the cause. Sync does not put the job back.

To turn it back on:

canonfig schedule set daily@09:00

To turn scheduled sync off on this Follower Machine:

canonfig schedule remove

schedule remove deletes the job and records your choice, so later applies do not reinstall it, even when the profile suggests a schedule. Removing a schedule that is already gone changes nothing.

Time zones, daylight saving, and missed runs

• Time zone. Without --timezone, the job runs at that clock time in the machine's time zone.

• Missed runs on Linux. A run missed while the machine was off, or while you were logged out without lingering, starts once when the timer starts again, not once per missed day.

• Missed runs on macOS. launchd runs a job missed while the Mac slept once when it wakes. A run missed while the Mac was off or you were logged out is not caught up.

• Missed runs on Windows. They are skipped, not caught up.

• Time zone change on Linux. systemd recalculates the next run. If, in the other zone, a run time has passed since the last run, the job runs once immediately.

• Time zone change on macOS. launchd may keep using the old zone until you restart. schedule status reports timezone-changed, and schedule set refuses to install until you restart the Mac and sign in again. This does not apply to daylight-saving changes within one time zone.

• Start time. On Linux, a run can start up to one minute after the scheduled time.

• Times that do not exist. On the day clocks move forward, some local times do not exist, for example 02:30 in Europe/Madrid on 2027-03-28. schedule set checks the next 12 months of your scheduled days and warns, for example:

  02:30 does not exist in Europe/Madrid on 2027-03-28 (daylight-saving change); systemd skips the run on those days and runs again on the next scheduled day. Choose a time outside the change window to run on every scheduled day.

  On macOS and Windows, the warning says the run on those days may be skipped or start after the clock change. Choose 04:00 or later to run on every scheduled day.

• Times that occur twice. On the day clocks move back, Canonfig gives no warning and makes no promise about how often the job runs.

Run a specific Canonfig installation

By default the job runs the Canonfig you ran schedule set with. To run another installation, pass its absolute path:

canonfig schedule set daily@09:00 --executable /usr/local/bin/canonfig

Canonfig first checks that the command starts with the limited PATH the scheduler uses. If it does not, schedule set stops with Human Action Required (exit 3), names the command and the PATH, and suggests running again without --executable.

If something fails