Skip to main content

Overview

FERAL instances on the same network automatically discover each other via mDNS and replicate memory using HLC (Hybrid Logical Clock) timestamps + last-write-wins at the row level, backed by a per-node write-ahead log. All sync is peer-to-peer — no cloud relay is involved.

TLS Setup

Generate a CA and peer certificates using OpenSSL:
Configure each FERAL instance:
The passphrase (FERAL_SYNC_PASSPHRASE) is still checked as a belt-and-suspenders layer on top of TLS.

Static Peer List

When mDNS is blocked (enterprise networks, Docker, VPNs), use a static peer list:
FERAL will use mDNS first. If no peers are discovered within 30 seconds, it falls back to the static list. If mDNS is unavailable entirely (zeroconf not installed), static peers are used immediately.

Troubleshooting mDNS

Conflict Resolution

  • Notes / Knowledge: Last-Writer-Wins by HLC timestamp
  • Episodes: Union merge (never delete remote episodes)
  • Execution log: Append-only (INSERT OR IGNORE)

Architecture