Syncing Secrets · Dotweave

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 as keys.txt in the dotweave app-data directory. 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 keys.txt in the dotweave app-data directory, 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:

# Save the key in a file and pass that file
dotweave init --key-file ~/dotweave.agekey

# Or let dotweave prompt you when importing an existing repository
dotweave init https://github.com/you/dotfiles.git

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 a .dotweave.secret suffix:

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

Pulling Secrets on Another Machine

Initialize dotweave on the new machine with your existing repository and private key:
```
dotweave init https://github.com/you/dotfiles.git --key-file ~/dotweave.agekey
```
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 .dotweave.secret suffix 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.