EnvSync

EnvSync is an open-source, local-first, zero-config CLI tool that securely synchronizes environment .env files across machines on the same local network without relying on a cloud relay server.

Features

• 🔒 Secure-First: Uses native Node.js crypto with AES-256-GCM encryption. Payloads are encrypted before network transmission, ensuring that eavesdroppers on the local network cannot read your secrets.
• 🔗 Zero-Config Discovery: Built-in mDNS/DNS-SD (bonjour-service) automatically advertises and discovers peers on the local network. No IP address configuration required!
• 📂 Recursive Multi-File Support: Scans the project directory recursively to find all environment files (default patterns: *.env*, *.env.*) and recreates the exact nested subfolder structure on the receiver machine (useful for monorepos).
• 🛡️ Git Safety Guardrail: Automatically detects and updates .gitignore to prevent committing .envsync-local.json to source control.
• ⚙️ Hands-Free Scripting (Persistent Key): Auto-generates a secure pairing key stored in the local config so you can run syncs from background tasks, cron jobs, or scripts without any prompts or human intervention.
• 🚀 Daily Background Updates: Asynchronously checks the package registry for updates once a day and displays a non-blocking notification on subsequent executions.
• 🌐 Network Filtering: Automatically blocks sync requests originating from public/unauthorized non-local IPs.

Installation

EnvSync is published as @pradeepgudipati/envsync. Use npmjs for the default public install path:

npm install -g @pradeepgudipati/envsync

Or with pnpm:

pnpm add -g @pradeepgudipati/envsync

Confirm the CLI is available:

envsync --help

Configure And Use

1. Initialize Source

Run envsync init in your project root on the source machine.

envsync init
envsync key

Copy the project ID printed by envsync init and the pairing key printed by envsync key. A destination asks for both the first time it listens.

2. Keep Source Ready

Start the source watcher from the source project root:

envsync watch

The watcher scans the local network for matching EnvSync receivers. When a receiver starts or stays available, it automatically sends the configured files using the pairing key saved by envsync init.

[!IMPORTANT] envsync watch starts in the background by default. A stopped source process cannot detect a receiver. Use envsync watch --foreground when you want logs in the current terminal.

3. Start Receiver Once

On a destination machine:

envsync listen

If .envsync-local.json does not exist yet, envsync listen prompts for the source project ID and pairing key, saves them locally, advertises the receiver, accepts one sync, writes the files, and exits.

4. Keep Destination Ready

For a destination that should keep receiving future source updates:

envsync listen --watch

Destination watch mode starts in the background, keeps advertising the receiver, and accepts repeated sync payloads until you stop it. Use envsync listen --watch --foreground when you want logs in the current terminal.

You can also stop a running source watcher or destination listener from another terminal:

envsync stop

5. Manual Push

Manual push remains available:

envsync push

Command Summary

envsync init            # configure the source project
envsync key             # reveal the source pairing key intentionally
envsync watch           # keep the source ready to auto-push to receivers
envsync watch --foreground
envsync listen          # receive one sync on a destination
envsync listen --watch  # keep a destination ready for repeated syncs
envsync listen --watch --foreground
envsync stop            # stop a running source watcher or destination listener
envsync push            # manually push from source to an active receiver

Technical Architecture

sequenceDiagram
    participant Sender
    participant mDNS as Local Network (mDNS)
    participant Receiver
    
    Note over Receiver: envsync listen or listen --watch
    Receiver->>mDNS: Advertises _envsync._tcp (TXT: project_id, port)
    Note over Sender: envsync watch or envsync push
    Sender->>mDNS: Browses for _envsync._tcp
    mDNS-->>Sender: Discovers Receiver (IP, Port, project_id)
    Note over Sender: Encrypts files using AES-256-GCM<br/>(using local pairing_key)
    Sender->>Receiver: HTTP POST /sync (payload: salt:iv:tag:cipher)
    Note over Receiver: Verifies local IP<br/>Decrypts with local pairing_key<br/>Validates project_id matches
    Note over Receiver: Writes environment files recursively
    Receiver-->>Sender: HTTP JSON Response (Success)
    Note over Receiver: One-shot exit or watch for more syncs

Security Details

• Key Derivation: Keys are derived from the pairing key using Node's native crypto.scryptSync with a unique random 16-byte salt for each transmission.
• Encryption: Payloads (containing environment files and metadata) are encrypted using AES-256-GCM.
• Integrity Validation: The GCM authentication tag is generated on encryption and verified on decryption. Any tampering or invalid pairing key will fail decryption and abort file writing.
• Local Isolation: The receiver filters all incoming traffic, blocking any request that does not originate from local/private subnets (e.g. 192.168.x.x, 10.x.x.x, 127.0.0.1, etc.).