Secrets

Never put a credential in a config file. Reference it instead:

~/.agentsync/mcp/github.toml

[server.env]
GITHUB_TOKEN = "${secret:github.token}"

${secret:…} is resolved at apply time from an age-encrypted vault and written into native config. ${env:…} pulls from the environment. The resolved value is never captured back into your source — agentsync diff even redacts it so a piped diff can’t leak it.

Set up the vault

The vault is encrypted to a recipient (public key — safe to commit); decryption needs the identity (private key — per-machine). agentsync embeds age, but generating the key uses the age-keygen CLI.

1. Install age (for age-keygen): brew install age, apt install age, …

2. Generate a keypair:

   mkdir -p ~/.config/agentsync
   age-keygen -o ~/.config/agentsync/age.key   # prints "Public key: age1…" to stderr
   chmod 600 ~/.config/agentsync/age.key        # agentsync refuses a group/other-readable identity

3. Point agentsync.toml at it — recipient is the age1… public key that age-keygen printed:

   ~/.agentsync/agentsync.toml

   [secrets]
   backend       = "age"
   recipient     = "age1…"
   identity_file = "${env:HOME}/.config/agentsync/age.key"

   Note

   agentsync encrypts to a single X25519 recipient, so use the age-keygen key — not an SSH key.

Store and read secrets

agentsync secrets set accepts the value three ways:

agentsync secrets set github.token --stdin    # from stdin (best for scripts / 1Password CLI)
agentsync secrets set github.token            # interactive prompt, echo off
agentsync secrets set github.token=ghp_…      # back-compat; warns — argv is visible to ps(1)

agentsync secrets edit                        # open the whole vault in $EDITOR
agentsync secrets get github.token            # read one back (to verify)

Back up your age key

Decryption needs the identity file (private key), which is per-machine. agentsync does not back it up for you. Lose it and you lose access to every encrypted secret. Stash it in a 1Password Secure Note or your machine-setup repo.

Why it can’t leak

The dangerous bug class is a resolved cleartext secret being persisted back into your canonical source — often a committed dotfiles repo. agentsync makes this hard to do by accident with several tiers of defense, including a compile-time guarantee (the resolved model is a distinct type that source writers literally cannot accept) and a fail-closed backstop in the capture path that refuses to write rather than risk persisting a credential.

How the leak is prevented The full security model: compile-enforced, value-invariant, lint-fenced, and the capture backstop.