Secure Peers setup

Overview

secure-peer mode is built for scenarios where multiple people need to share secrets without giving each other SSH access. Every peer must be explicitly invited and approved before syncing.

Step 1 — Set up the first device

Install env-sync and initialize the first peer. This device becomes the initial trust anchor for the network.

# install env-sync
curl -fsSL https://envsync.arnav.tech/install.sh | sudo bash

# verify
env-sync --version

# switch to secure-peer mode
env-sync mode set secure-peer --yes

# initialize with encryption (generates AGE key pair + TLS identity)
env-sync init --encrypted

# start the mTLS server (runs in background)
env-sync serve -d

Add your initial secrets

env-sync add OPENAI_API_KEY="sk-abc123xyz"
env-sync add DATABASE_URL="postgres://user:pass@localhost/db"

# verify everything is running
env-sync status

The first device is now serving secrets over HTTPS with mTLS. No other peer can connect yet — they need an invitation.

Step 2 — Invite a second device

The invitation flow has three stages: invite → request → approve.

2a — Create an invitation (on the first device)

# generate a time-limited enrollment token
env-sync peer invite --expiry 24h

This outputs an enrollment token and the hostname of the first device. Share both with the person joining the network (e.g. via a secure channel like Signal or in person).

2b — Install and request access (on the new device)

# install env-sync
curl -fsSL https://envsync.arnav.tech/install.sh | sudo bash

# switch to secure-peer mode
env-sync mode set secure-peer --yes

# initialize with encryption
env-sync init --encrypted

# start the local mTLS server
env-sync serve -d

# request access using the invitation token
env-sync peer request first-device.local <TOKEN>

The new device sends its TLS certificate and AGE public key to the first device. Its status is now pending.

2c — Approve the new peer (on the first device)

# list pending peer requests
env-sync peer list

# approve the new device
env-sync peer approve new-device.local

Once approved, the devices exchange TLS certificates and AGE public keys automatically. Both peers can now sync.

2d — Exchange keys and sync

# on the new device — import the first device's AGE public key
env-sync key import <FIRST_DEVICE_PUBKEY> first-device.local

# on the first device — import the new device's AGE public key
env-sync key import <NEW_DEVICE_PUBKEY> new-device.local

# sync from either device
env-sync sync

Secrets are re-encrypted for both recipients. The new device can now decrypt and read all shared secrets.

Step 3 — Add more devices

Repeat Step 2 for each additional peer. Any already-approved device can create invitations:

1. An approved peer runs env-sync peer invite --expiry 24h.
2. The new device installs, initializes, and runs env-sync peer request.
3. The inviting peer (or any approved peer) runs env-sync peer approve.
4. Exchange AGE public keys and sync.

# quick reference for onboarding the Nth device
# -- on any approved peer --
env-sync peer invite --expiry 24h

# -- on the new device --
curl -fsSL https://envsync.arnav.tech/install.sh | sudo bash
env-sync mode set secure-peer --yes
env-sync init --encrypted
env-sync serve -d
env-sync peer request approver.local <TOKEN>

# -- on the approving peer --
env-sync peer approve new-device.local
env-sync key import <NEW_DEVICE_PUBKEY> new-device.local

# -- on the new device --
env-sync key import <APPROVER_PUBKEY> approver.local
env-sync sync

Membership events propagate automatically — peers that were offline during the approval will catch up on the next sync via signed membership events.

Verify your setup

# list all known peers and their status
env-sync peer list

# check trust details for a specific peer
env-sync peer trust show peer-hostname.local

# view all trusted fingerprints
env-sync peer trust list

# check sync status
env-sync status

Automate sync

# install cron job (syncs every 30 minutes)
env-sync cron --install

# auto-load secrets in your shell
# add to ~/.bashrc or ~/.zshrc:
eval "$(env-sync load 2>/dev/null)"

Make sure env-sync serve -d starts at boot so the mTLS server is always available for incoming sync requests. Consider using your OS service manager:

# Linux (systemd)
env-sync service install
systemctl --user enable env-sync

# macOS (launchd)
env-sync service install

Remove a device from the network

When a team member leaves or a device is compromised, revoke their access:

Revoke the peer (on any approved device)

# revoke access
env-sync peer revoke departed-device.local

# verify revocation
env-sync peer list

The revoked peer's status changes to revoked. A signed membership event is created and propagated to all other peers on the next sync.

What happens after revocation

• The revoked device can no longer authenticate via mTLS.
• New secrets are encrypted only to remaining approved peers — the revoked device cannot decrypt them.
• Peers that are offline will learn about the revocation when they sync and replay membership events.

On the departing device (optional cleanup)

# stop the server and service
env-sync service uninstall
env-sync cron --remove

# delete all local data
rm -rf ~/.config/env-sync

# remove the binary
sudo rm -f /usr/local/bin/env-sync

Important: After revoking a device, rotate any secrets it had access to. The revoked device may still have a cached copy of previously-synced secrets.