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 syncenv and initialize the first peer. This device becomes the initial trust anchor for the network.

# install syncenv
curl -fsSL https://syncenv.yuvrajthapa.com/install.sh | sudo bash

# verify
syncenv --version

# switch to secure-peer mode
syncenv mode set secure-peer --yes

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

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

Each OS user runs their own server; a second user auto-bumps to a free per-user port (persisted in ~/.config/syncenv/port). Use serve -p to pin an explicit port.

Add your initial secrets

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

# verify everything is running
syncenv 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
syncenv peer invite --expiry 24h

This outputs an enrollment token and the peer ID of the first device (user@host, e.g. alice@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 syncenv
curl -fsSL https://syncenv.yuvrajthapa.com/install.sh | sudo bash

# switch to secure-peer mode
syncenv mode set secure-peer --yes

# initialize with encryption
syncenv init --encrypted

# start the local mTLS server
syncenv serve -d

# request access using the invitation token
syncenv peer request alice@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
syncenv peer list

# approve the new device
syncenv peer approve bob@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
syncenv key import <FIRST_DEVICE_PUBKEY> alice@first-device.local

# on the first device — import the new device's AGE public key
syncenv key import <NEW_DEVICE_PUBKEY> bob@new-device.local

# sync from either device
syncenv 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 syncenv peer invite --expiry 24h.
2. The new device installs, initializes, and runs syncenv peer request.
3. The inviting peer (or any approved peer) runs syncenv peer approve.
4. Exchange AGE public keys and sync.

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

# -- on the new device --
curl -fsSL https://syncenv.yuvrajthapa.com/install.sh | sudo bash
syncenv mode set secure-peer --yes
syncenv init --encrypted
syncenv serve -d
syncenv peer request alice@approver.local <TOKEN>

# -- on the approving peer --
syncenv peer approve bob@new-device.local
syncenv key import <NEW_DEVICE_PUBKEY> bob@new-device.local

# -- on the new device --
syncenv key import <APPROVER_PUBKEY> alice@approver.local
syncenv 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
syncenv peer list

# check trust details for a specific peer
syncenv peer trust show alice@peer-hostname.local

# view all trusted fingerprints
syncenv peer trust list

# check sync status
syncenv status

Automate sync

# install cron job (syncs every 30 minutes)
syncenv cron --install

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

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

# Linux (systemd)
syncenv service install
systemctl --user enable syncenv

# macOS (launchd)
syncenv 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
syncenv peer revoke bob@departed-device.local

# verify revocation
syncenv 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
syncenv service uninstall
syncenv cron --remove

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

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

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.