CONCEPTS

How sync works

Tether connects your machines through one Git repository. Each machine pushes its changes there and pulls the changes of the other machines.

One sync, step by step

1. The daemon starts a sync every 5 minutes. tether sync starts one at once
2. Tether pulls the sync repo and merges the synced config.toml into the local one. See Config merge
3. Tether syncs the dotfiles. It encrypts local changes and applies changes from other machines. A file that changed on both sides is a conflict
4. Tether syncs project configs
5. Tether verifies the signed records of the other machines against its trust list. See Machine trust
6. Tether checks each synced package that this machine does not have. It installs it, or holds it in the Inbox
7. Tether signs this machine's record again when its content changed, or when the signed copy is 60 minutes old. The record lists the packages and versions of this machine
8. Tether commits and pushes

What syncs

• Dotfiles, such as .zshrc and .gitconfig, and folders that you add. Tether stores them encrypted in Git, unless you set security.encrypt_dotfiles = false. Locally they stay plaintext, so your shell reads them
• Package lists for Homebrew, npm, pnpm, bun, gem and uv. They stay readable in Git. See Packages and versions
• Project configs, such as .env files, matched by the Git remote of the project
• Machine records: one signed file per machine, with its packages, versions, profile and OS
• config.toml, encrypted, so all machines share one configuration

Some files never sync: ~/.tether/local.toml, the trust list, the Inbox and the signing key. See Data layout.

The daemon

The daemon runs a sync every 5 minutes. It does not ask questions. It holds new packages and machine keys in the Inbox and sends one notification for each new batch. It records conflicts for tether resolve.

• Without a terminal, the git commands that reach the remote stop after 5 minutes. The next sync tries again
• An idle machine signs its record again once an hour, so other machines see that it runs
• On macOS, launchd runs the daemon. On Linux, a systemd user service runs it. See Linux and systemd

Control the daemon with tether daemon. See Commands.