How Canonfig works

One Source Machine owns the desired configuration. Every other machine is a Follower Machine: it receives that configuration and never sends changes back.

Who owns what

A Follower Machine never publishes. To change something on every machine, change the profile file on the Source Machine and run canonfig source publish. To change something on one machine only, claim it on that machine as a Local Overlay, or keep it out of the profile.

What syncs and when

1. You write a profile file and publish it on the Source Machine. Publishing validates the profile, reads every source file it names, and signs a Profile Revision with the next sequence number. A Profile Revision never changes after you publish it.
2. A Follower Machine fetches the latest Profile Revision of its selected profile only when you run canonfig sync, or when its native schedule runs canonfig sync --apply --no-input --scheduled. Canonfig does not push changes and does not poll in the background.
3. canonfig sync --plan (the default) downloads the Profile Revision and compares it with the machine. It changes nothing. canonfig sync --apply applies the plan and verifies every resource.

To roll a profile back, publish the earlier content again; it becomes the next Profile Revision.

Follower Machines download only files they do not already hold. Before a run starts, Canonfig checks free disk space on each target's filesystem and on its cache, and refuses the run when either is too small.

The Source Machine serves Profile Revisions on a loopback address only. A Follower Machine on another host reaches it through canonfig tunnel, an SSH tunnel Canonfig manages. See Security and credentials.

What stays local

• Credentials. A credential resource carries a reference, not a value. Each Follower Machine must already hold the credential; otherwise the resource needs Human Action Required. Shared secrets are a separate, opt-in channel; see Opt-in shared secrets.
• Local Overlay keys. Keys you claim with canonfig overlay set stay as you wrote them, and are never sent to the Source Machine.
• Local text in append-local files. Canonfig replaces only the Source Machine's marked section of the file.
• Files the profile does not declare. Canonfig changes only the targets and keys a profile declares. A directory resource with the default mirror-owned policy removes only entries Canonfig wrote earlier.
• Applied files after you leave. canonfig follower unenroll leaves every applied file in place.

What happens when a Follower Machine changed a managed file

Canonfig keeps an Applied Resource Record of what it last applied to each resource. On the next run it compares the machine with that record:

• A config resource rewrites only the keys the profile declares. Other keys, comments, and layout in the file stay.
• A skill resource (policy replace-if-unmodified) that you edited on the Follower Machine is Follower Drift. Canonfig keeps your edit, reports the resource as drift-conflict in the plan, and stops the run with exit 4. Move the change to the Source Machine and publish it, or discard it on the Follower Machine, then run canonfig sync --apply again.
• A file resource with the default replace policy is overwritten with the profile's content. Use append-local when a Follower Machine needs its own text in the same file.

Apply Policies lists every policy.

How Canonfig decides what to do

For every resource, Canonfig first looks for one safe action it can take from the profile alone, such as writing a file or running a pinned installer. If none exists, the outcome depends on the Follower Machine's agent policy:

Human Action Required means a step only a person can complete, such as signing in to a tool or unlocking a credential store. Canonfig stops at that resource and prints what to do.

An agent's own report is never proof. After any change, Canonfig runs the resource's declared verification, and only that verification counts. See Let a Configuration Agent resolve work.

The transaction boundary

Canonfig records a Synchronization Run's plan and each action as it runs, so one run behaves as one transaction for file, directory, and config changes:

• A failed action rolls back the whole run. Canonfig restores every file, directory, and config it changed in that run, including resources unrelated to the failure. The run fails with exit 7 and names the cause: "resource <id> could not be applied to <target>: <cause>". Fix the cause and run canonfig sync --apply again.
• Tool installs are not rolled back. Canonfig cannot reverse a package manager, a login, or an agent's commands. The next run's verification finds an installed tool and leaves it in place.
• Human Action Required and Follower Drift stop the run without rolling back. Resources that applied and verified stay applied. The blocked resource is left as it is, and every later action is skipped. canonfig sync --plan lists the blocked resource in advance. Fix the cause, then run canonfig sync --apply again to apply the rest.

A run that stops part-way (a crash, a killed process, a reboot, or a full disk) stays open. canonfig recover finishes it or rolls it back. When a file was edited after the run wrote it, recovery stops and keeps both your file and the saved copy instead of choosing for you. See Recover from a failed or blocked sync.

Where Canonfig keeps its files

The user cache directory is ~/.cache (or $XDG_CACHE_HOME) on Linux, ~/Library/Caches on macOS, and %LOCALAPPDATA% on Windows.

Canonfig never deletes or resets its state database by itself. If the database is unreadable, commands fail with exit 3; check the directory's permissions, or restore a known good copy of state.sqlite.