Publish a change to your Follower Machines

Follower Machines never read files from the Source Machine's disk. They receive only what you publish as a signed Profile Revision, so editing ~/.claude/CLAUDE.md on the Source Machine changes nothing on a Follower Machine until you publish again. Changed content, an added resource, and a removal all follow the same steps.

Before you start

• The Source Machine is set up with canonfig source init. Publishing without it fails with "the profile revision could not be signed (operation="load source credentials"); run 'canonfig source init' first".
• You have a Machine Profile file. The examples use ~/canonfig.profile.jsonc from Sync your first two machines. The profile file reference lists every field.
• Follower Machines fetch from the Source Machine, so it must be serving when they sync. See Run Canonfig unattended.

Publish a change

1. Edit the source file, for example ~/.claude/CLAUDE.md, or the profile file itself. Config values sit in the profile under spec.keys.

2. Check the profile on the Source Machine:

   canonfig source digest --profile-file ~/canonfig.profile.jsonc

   source.digest completed
   profile: workstation
   content digests (2):
     file       claude-instructions          2acae736aaa9c6a866fcad37170b4069f9f3e90c3cfec7437ce5d74799fec7b0
     skill      claude-review-skill          5c21ab53ead1c187aa0ef404c98191621b46ccc37ef1ccc23e49ef1b42ed2528

   source digest reads every source file exactly as publishing does and prints each resource's content digest. It does not sign or publish anything. Add --resource claude-instructions to check one resource.

3. Publish:

   canonfig source publish --profile-file ~/canonfig.profile.jsonc --reviewer "$USER"

   source.publish completed
   profile: workstation, sequence 2
   revision: workstation:25f4e71bd8dc2ccc11604f4da39a0c7e45e1a0f6809b75a53d378efb73ba43cc
   published at: 2026-11-02T19:47:11.383Z
   resources (2):
     file       claude-instructions          → ~/.claude/CLAUDE.md
     skill      claude-review-skill          → ~/.claude/skills/code-review

   --reviewer is required and records who approved the Profile Revision.

If the content is identical to the latest Profile Revision, source publish returns that Profile Revision with the same sequence number, and nothing reaches Follower Machines. Any other content becomes the next sequence number.

Each Follower Machine applies the Profile Revision at its next scheduled run. To apply it immediately, continue with the next section.

Apply the change on a Follower Machine immediately

On the Follower Machine:

canonfig sync --plan
canonfig sync --apply

The plan lists every action, such as write-file or write-config with the keys it sets, and anything it will remove. sync --plan changes nothing. After sync --apply reports Converged, canonfig status shows the applied Profile Revision.

If a resource needs a person on the Follower Machine, for example a login, a skill edited on that machine, or a config file that does not parse, the plan and the result name the resource and the reason. The apply stops at that resource: resources before it stay applied and later ones wait. Fix it, then run canonfig sync --apply again. See Recover from a failed or blocked sync.

Add, change, or remove a resource

To add a resource, add an entry to resources with a unique id, then check and publish as above. To remove one, delete its entry and publish.

To keep a config key on one Follower Machine only, claim it there as a Local Overlay:

canonfig overlay set claude-settings --target ~/.claude/settings.json --key permissions.allow

Files and skills cannot be claimed this way.

To remove skill resources whose source directory you deleted on the Source Machine, see Remove deleted skills from the profile.

Add a tool

Add a tool resource with one Installation Recipe per platform and an exact version:

{
  "id": "typescript",
  "kind": "tool",
  "target": "tsc",
  "spec": {
    "kind": "tool",
    "toolId": "typescript",
    "recipes": [
      { "platform": "linux", "method": "npm", "package": "typescript", "version": "5.6.3" },
      { "platform": "macos", "method": "npm", "package": "typescript", "version": "5.6.3" }
    ]
  },
  "verify": { "method": "executable-present", "executable": "tsc" }
}

Use the package name and the version you tested on the Source Machine. Every automatic installer recipe (npm, pnpm, bun, brew, apt, winget, uv, cargo) needs an exact version. Publishing refuses a recipe without one.

When the tool is missing on a Follower Machine, sync --apply installs it with the recipe for that Follower Machine's platform, then runs the verification. This example has no Windows recipe, so a Windows Follower Machine reports Human Action Required for typescript. How Canonfig installs and verifies tools covers recipe fields and how verification finds executables.

To find which tools your configuration files reference, scan them:

canonfig source scan --file ~/.codex/config.toml --file ~/.claude.json

The scan proposes tool resources only, never file, config, or skill resources. Each tool is accepted or needs-review, and the output gives the reason for each needs-review entry. Use the result to write tool resources yourself.

source publish --proposal <file> can also add a scanned file's accepted tools to the profile at publish time. It stops with Human Action Required (exit 3) when anything in that file needs review, so writing the resource yourself is the path that always works.

Roll back to earlier content

No command moves Follower Machines back to an earlier sequence number. Publish the earlier content again instead: it becomes the next sequence number, and Follower Machines move forward to it.

This needs the earlier content. Keep the profile and copies of the managed files in a Git repository, for example ~/canonfig-profile, with sources such as claude/CLAUDE.md relative to ~/canonfig-profile/profile.jsonc:

mkdir -p ~/canonfig-profile/claude
cp ~/.claude/CLAUDE.md ~/canonfig-profile/claude/CLAUDE.md
git -C ~/canonfig-profile add -A
git -C ~/canonfig-profile commit -m "Update CLAUDE.md"

To roll back the last change:

git -C ~/canonfig-profile checkout HEAD~1 -- .
canonfig source digest --profile-file ~/canonfig-profile/profile.jsonc
canonfig source publish --profile-file ~/canonfig-profile/profile.jsonc --reviewer "$USER"

This layout also lets you review a change before you publish it. Copy files into the repository; do not symlink them. A symlink to ~/.claude/CLAUDE.md resolves outside ~/canonfig-profile, and publishing refuses it.

With the profile in your home directory instead, as in the tutorial, each source points at the live file. You skip the copy step, but you publish whatever is on the Source Machine's disk at that moment, including unfinished edits.

If something fails

Unless a row says otherwise, each refusal exits 2 before anything is signed, and source digest reports the same problems.