Platform differences
Look up how Canonfig differs on Linux, macOS, and Windows in paths, tools, credentials, schedules, and unattended runs.
Linux, macOS, and Windows can each run a Source Machine or a Follower Machine. A Machine Profile describes the same outcome on each platform, but paths, package managers, credential stores, and schedulers differ.
What Canonfig uses on each platform
| Capability | Linux | macOS | Windows |
|---|---|---|---|
| Follower Machine schedule | systemd user timer | launchd user agent | Task Scheduler task |
| Source Machine service | systemd user unit canonfig-source.service | LaunchAgent dev.canonfig.source | Task Scheduler task Canonfig\canonfig-source, started at logon |
| Credential store | Secret Service (for example GNOME Keyring) | login Keychain | Credential Manager |
| Typical installers | apt, npm, uv, cargo, source | Homebrew, npm, uv, cargo, source | winget, npm, uv, cargo, source |
| Path syntax | POSIX | POSIX | Windows |
Paths and targets
A target path cannot contain .., a null byte, or a glob. Where a target
differs between platforms, map it per platform in the Machine Profile; do not
publish the Source Machine's absolute path as if it fit every Follower Machine.
Agent harness allowlists belong to each Follower Machine. Use Windows paths on Windows and POSIX paths on Linux and macOS.
Canonfig writes each file to a temporary sibling named .cf-<12 hex>.tmp,
then renames it over the target, so a target is never left half written.
canonfig recover removes leftover temporary files.
Windows path length and symbolic links
Unless Windows long paths are enabled, Windows limits paths to 260 characters
(MAX_PATH). canonfig sync --plan and canonfig sync --apply measure each
target, including the temporary name, and refuse a target that is too long
before they change anything:
<path>needs N characters including Canonfig's staging names, but this machine accepts file paths of at most 260 characters because Windows long paths are not enabled (MAX_PATH is 260). Nothing was changed.
To fix it, shorten the target, or enable long paths from an administrator PowerShell and open another session:
Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1If an apply fails after it created parent directories, rollback and
canonfig recover remove the directories that run created, and only while
they are empty. Directories that existed before the run stay.
Creating a symbolic link on Windows needs Developer Mode or the "Create symbolic links" user right. Without either, the action fails with:
Windows refused to create a symbolic link (EPERM). Creating symbolic links requires Developer Mode (Settings > System > For developers) or the SeCreateSymbolicLinkPrivilege user right ("Create symbolic links"); enable one for this account, sign in again, then retry
Installation Recipes
Each platform has its own Installation Recipe. A tool can install with apt on Linux, Homebrew on macOS, and winget on Windows. An npm, uv, cargo, or source recipe covers several platforms only when it was verified on each of them.
To verify a bare command such as ruff, Canonfig looks first in the
directories where that recipe's installer puts executables, then on PATH.
On Windows these include %APPDATA%\npm and
%LOCALAPPDATA%\Microsoft\WinGet\Links. See
How Canonfig installs and verifies tools.
Windows package managers
Canonfig starts installers without a shell, and Windows .cmd shims such as
npm.cmd and pnpm.cmd cannot run that way. When PATH resolves npm to
npm.cmd, canonfig sync --plan shows a warning and canonfig sync --apply
stops with Human Action Required:
No installer binding is set for npm, and PATH resolves it to the Windows command shim C:\Program Files\nodejs\npm.cmd, which cannot run without a shell. Bind npm to Node and its own entrypoint instead, then retry:
Run the binding command it prints, which looks like this, then check it:
canonfig installer set npm --executable "C:\Program Files\nodejs\node.exe" --arg "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js"
canonfig installer check npmBoth paths must be absolute and exist. They depend on where Node.js is
installed; nvm-windows and Volta use other directories. For pnpm, use
pnpm.cjs as the --arg. canonfig installer list shows the same command
under suggestions, and canonfig installer check confirms that the binding
starts. See Installer bindings.
Schedules
You declare a schedule once, in local time, and Canonfig installs the matching native job:
canonfig schedule set daily@09:00 --timezone Europe/Paris
canonfig schedule status--timezone works on Linux only. Missed runs and daylight-saving changes
follow each platform's scheduler; see Sync on a schedule.
Unattended runs
Every scheduled run executes:
canonfig sync --apply --no-input --scheduledA scheduled run never waits for a prompt. A missing credential store, login, elevation, or other step only a person can take ends as Human Action Required.
The Source Machine's service and scheduled runs work under these conditions:
| Platform | While logged in | While logged out |
|---|---|---|
| Linux | yes | only with lingering on (loginctl enable-linger <user>) and a reachable, unlocked Secret Service, or the local-file credential policy |
| macOS | in the logged-in desktop session, with the login Keychain unlocked | no |
| Windows | from logon, while you stay logged on | no |
Reaching the Source Machine
On every platform, the Source Machine listens on a loopback address only. Canonfig does not support a public listener. A Follower Machine on another host connects through the managed SSH tunnel, which pins the SSH host key, the Source Machine's TLS certificate, and its signing key, and refuses options that skip host-key checks or add forwards.
canonfig tunnel start --invitation ./canonfig-invite --ssh-host source.lan --ssh-user maria --ssh-host-key-file ./source-host-key.pub
canonfig tunnel startThe first command sets up and records the tunnel. Later starts need no invitation, and a scheduled run restarts a tunnel that went down once before it fetches. See the CLI reference.