Syncing Secrets

Some config files contain sensitive data — SSH keys, API tokens, credentials — that you definitely don’t want sitting in plaintext in a Git repository. Dotweave handles this with secret mode, which encrypts files using age before storing them in the sync directory.

---

What Is age?

age is a simple, modern file encryption tool. Dotweave uses it under the hood so you don’t need to install anything separately — it’s built right in.

Here’s how it works in dotweave:

• Recipients are public keys (age1...) used to encrypt files. You can have multiple recipients so different machines can decrypt the same files.
• Identity is your private key (AGE-SECRET-KEY-...), stored at ~/.config/dotweave/age-identity.txt. This is what decrypts your files during pull.

The key idea: anyone with a recipient (public key) can encrypt data for you, but only the holder of the identity (private key) can decrypt it.

---

Setting Up Your Key

When you run dotweave init, dotweave generates an age key pair for you automatically:

dotweave init

Your private key is saved to ~/.config/dotweave/age-identity.txt, and the corresponding public key is registered as a recipient in your sync config.

Caution

Back up your private key! It starts with AGE-SECRET-KEY-. Without it, you cannot decrypt your secret files. Store it in a password manager or somewhere safe outside of dotweave.

---

Using an Existing Key

Already have an age key from another machine? You can provide it during init:

# Pass the key directly
dotweave init --key AGE-SECRET-KEY-1ABCDEF...

# Or let dotweave prompt you to paste it
dotweave init --promptKey

This way all your machines share the same identity and can decrypt each other’s secrets.

When connecting to an existing sync repository with dotweave init <repo>, providing that private key is required.

---

Tracking Files as Secrets

Use --mode secret when tracking sensitive files:

dotweave track ~/.ssh/config --mode secret
dotweave track ~/.aws/credentials --mode secret
dotweave track ~/.config/gh/hosts.yml --mode secret

Then push to encrypt and store them:

dotweave push

In the sync directory, encrypted files get an .age suffix:

sync-directory/
├── default/
│   ├── .ssh/
│   │   └── config.age
│   └── .aws/
│       └── credentials.age

---

Pulling Secrets on Another Machine

1. Initialize dotweave on the new machine with your existing repository and private key:

   dotweave init https://github.com/you/dotfiles.git --key AGE-SECRET-KEY-1ABCDEF...

2. Pull your files:

   dotweave pull

   Dotweave automatically decrypts secret files and writes them to their original paths. Done!

---

Adding Recipients for Multiple Machines

If each of your machines has its own age key pair, you can add additional recipients so secret files are encrypted for all of them.

# On the original machine, add the new device's public key as a recipient
dotweave recipient add age1newdevicepublickey...

After adding the recipient, re-push so files get re-encrypted for all recipients:

dotweave push

Tip

A file encrypted for multiple recipients can be decrypted by any of them independently. That’s how age’s multi-recipient encryption works — each recipient can decrypt without needing the others’ private keys.

---

Important Things to Know

• The file content is encrypted, but the filename and path remain visible in the sync directory. The .age extension also reveals that it’s an encrypted file.
• Your age identity (private key) is not synced by dotweave. You need to transfer it manually — via a password manager, secure copy, or some other trusted channel.
• If you lose your private key and have no other recipients configured, your encrypted files are unrecoverable. Seriously, back it up.