CONCEPTS

Encryption

Tether encrypts your dotfiles on your machine before they reach Git. Locally they stay plaintext, so your shell reads them as usual. For the threat model, see Security.

How encryption works

1. On the first tether init, Tether makes a random 256-bit key
2. It encrypts the key with your passphrase, using age
3. It stores the encrypted key in the sync repo as encryption.key.age
4. It encrypts each dotfile with AES-256-GCM before it commits it
5. On another machine, you enter the passphrase to decrypt the key

Package manifests and machine records stay readable in Git. Team secrets use age public-key encryption. See Teams and collab.

Encryption is on by default. To turn it off, set security.encrypt_dotfiles = false. Do not turn it off if your dotfiles hold secrets.

Unlock and lock

Each machine caches the decrypted key. If the daemon cannot decrypt, unlock the key with your passphrase:

tether unlock

To clear the cached key:

tether lock

Secret detection

Tether scans team dotfiles for common secret patterns in these places:

• tether sync and the daemon scan before they push the team repo. A finding blocks the push
• tether team add scans the team repo. A finding asks you whether to continue

A sync with only team features on does not scan. tether team files promote does not scan. Tether does not scan personal dotfiles. They reach Git encrypted, unless you set security.encrypt_dotfiles = false. Tether looks for patterns such as:

• AWS credentials (AKIA...)
• GitHub tokens (ghp_..., gho_...)
• Generic patterns (API_KEY=, password=)

A line that holds an ignore pattern is not a finding. Add one for a false positive:

tether ignore secrets add 'EXAMPLE_KEY='

Turn the team scan off with security.scan_secrets = false.