secbyd/proton-carddav-sync repository overview

⁠proton-carddav-sync

Sync your Proton Mail contacts with any CardDAV server — Nextcloud, Radicale, Baïkal, iCloud, and others. A small, self-hosted Go daemon.

📦 Source & full docs: https://github.com/secbyd/proton-carddav-sync⁠

⁠What it does

• Bidirectional sync (Proton ↔ CardDAV) with a per-property three-way merge, so changing one field on one side never wipes fields the other side has. One-way modes are available too.
• Password-free, long-lasting Proton session (à la hydroxide/ferroxide): you log in once; the daemon resumes via a refresh token and never stores your account password.
• Encrypted at rest — the Proton session and CardDAV password are AES-256-GCM encrypted in a local SQLite database with a key derived from PCS_ENCRYPTION_KEY. Nothing secret is written to the config file.
• Gentle on Proton — all Proton API calls are rate-limited (default ~1/sec) to stay well under Proton's anti-abuse limits, with an optional per-run cap on new contacts for large first imports.
• TOTP/2FA supported during setup.

⁠Tags & architectures

• latest — the current main build
• vX.Y.Z — tagged releases
• sha-<short> — a specific commit

Images are multi-arch: linux/amd64 and linux/arm64.

⁠Volumes & configuration

PCS_ENCRYPTION_KEY (a long random passphrase) must be passed at runtime — it is never baked into the image, and the same value is required by init and the daemon.

⁠Usage

⁠1. Initialise (interactive — prompts for passwords + TOTP)

docker run --rm -it \
  -e PCS_ENCRYPTION_KEY="a-long-random-passphrase" \
  -v pcs-config:/config -v pcs-data:/data \
  secbyd/proton-carddav-sync \
  init --config /config/config.yaml

With no config present, init asks for every setting (set database.path to /data/sync.db), logs in to Proton (asking for a TOTP code if 2FA is enabled), and stores the encrypted session.

If your platform can't run an interactive one-off container (e.g. Portainer or Unraid), start the container with the idle command instead, then:

docker exec -it <container> proton-carddav-sync init --config /config/config.yaml

…and restart it with the default command afterwards.

⁠2. Run the daemon

docker run -d --name proton-carddav-sync --restart unless-stopped \
  -e PCS_ENCRYPTION_KEY="a-long-random-passphrase" \
  -v pcs-config:/config -v pcs-data:/data \
  secbyd/proton-carddav-sync

⁠docker compose

services:
  proton-carddav-sync:
    image: secbyd/proton-carddav-sync:latest
    restart: unless-stopped
    environment:
      PCS_ENCRYPTION_KEY: "a-long-random-passphrase"
    volumes:
      - pcs-config:/config
      - pcs-data:/data
volumes:
  pcs-config:
  pcs-data:

Run init once before up -d: docker compose run --rm -it proton-carddav-sync init --config /config/config.yaml

⁠Environment variables

⁠Notes

• Proton enforces a strict Acceptable Use Policy. A first sync of a large address book is paced automatically; for hundreds of contacts you can also cap new creates per run. See the GitHub README for details.
• Built on a glibc debian:bookworm-slim base so the CGO SQLite driver works without musl/static-link complications.

⁠License

See the repository⁠ for license and full documentation.