Encryption with AGE

This page focuses on real configuration patterns for encrypted backups.

For the “what is AGE” primer, see docs/docs_file/what_is_age.md. For decrypt usage, see docs/docs_file/decryption.md.

Example 1 — Enable encryption (wizard-managed recipient file)

The recommended setup is to let the installer/newkey flow create and manage the recipient file under identity/.

# configs/backup.env
ENCRYPT_ARCHIVE=true
AGE_RECIPIENT=
AGE_RECIPIENT_FILE=${BASE_DIR}/identity/age/recipient.txt

If you haven’t configured AGE yet, run:

proxsave --newkey

CLI prompts (no TUI):

proxsave --newkey --cli

Example 2 — Provide a recipient inline (advanced)

If you already have an AGE public key and want it explicitly in backup.env:

# configs/backup.env
ENCRYPT_ARCHIVE=true
AGE_RECIPIENT=age1exampleexampleexampleexampleexampleexampleexampleexample
AGE_RECIPIENT_FILE=

Example 3 — Encrypted backups + bundling (common for cloud uploads)

# configs/backup.env
ENCRYPT_ARCHIVE=true
BUNDLE_ASSOCIATED_FILES=true

This produces an encrypted main archive plus associated files, and (when bundling is enabled) a single .bundle.tar you can copy/upload.

Example 4 — Decrypt an encrypted bundle (interactive)

Decrypt is an interactive workflow:

proxsave --decrypt

If you need text prompts:

proxsave --decrypt --cli

For troubleshooting:

proxsave --decrypt --cli --log-level debug

Example 5 — Restore from an encrypted backup

The restore workflow can decrypt as part of the process:

proxsave --restore

CLI + debug:

proxsave --restore --cli --log-level debug