Synapsis/README.md

Synapsis

Your node. Your network. Your identity.

Synapsis is an open-source federated social network built around sovereign DIDs, portable user-owned media storage, and the Swarm network.

Run a node on a VPS

Synapsis runs directly under systemd. It does not require Docker, PostgreSQL, or a bundled reverse proxy.

Prerequisites:

• A Linux VPS with systemd
• Node.js 20 or newer
• Git, npm, and OpenSSL
• Your own nginx, Caddy, Traefik, or other reverse proxy

Install from a checkout:

sudo bash deploy/install.sh
sudo nano /etc/synapsis.env
sudo bash /opt/synapsis/deploy/update.sh

The service binds only to 127.0.0.1:43821. Point your reverse proxy at that address and terminate TLS there. PORT can be overridden in /etc/synapsis.env if needed.

The installer creates:

• Application checkout: /opt/synapsis
• Environment file: /etc/synapsis.env
• Embedded Turso database: /var/lib/synapsis/synapsis.db
• Service: synapsis.service
• Mandatory update timer: synapsis-update.timer

Every node checks origin/main about once per minute. When a new commit is available, Synapsis fast-forwards the checkout, replaces the single backups/latest database snapshot, installs dependencies, runs migrations, builds, and restarts automatically. The repository commit count is shown in the Network Info card; /api/version exposes both that number and the full deployed commit hash.

While an update is being installed, synapsis-maintenance.service temporarily serves a branded maintenance page on the node's configured PORT. Existing reverse proxies continue receiving an HTTP response instead of showing a gateway error, and browsers automatically reload when Synapsis is ready.

For a node installed before automatic updates existed, bootstrap the timer once with:

sudo -u synapsis git -C /opt/synapsis pull --ff-only
sudo /opt/synapsis/deploy/update.sh

Useful commands:

sudo systemctl status synapsis
sudo systemctl status synapsis-update.timer
sudo journalctl -u synapsis -f
sudo journalctl -u synapsis-update -f
sudo /opt/synapsis/deploy/update.sh
sudo /opt/synapsis/deploy/uninstall.sh

Uninstalling preserves the database and environment by default. Pass --purge-data only when you intentionally want to remove both.

Storage and account portability

The node database is a local embedded Turso/SQLite file. Media remains in storage controlled by each user, so exported accounts retain portable media URLs and can move between Synapsis nodes without requiring the old node to transfer a shared upload directory.

Stuffbox is the default integration. New installs use https://stuffbox.xyz; set STUFFBOX_URL to a different public URL when using another or self-hosted Stuffbox service. Synapsis uses a consent and PKCE flow, keeps the resulting tokens encrypted with AUTH_SECRET, and sends file bytes directly from the user's browser to Stuffbox.

User-owned S3-compatible storage remains available as an advanced fallback. Supported providers include AWS S3, Cloudflare R2, Backblaze B2, Wasabi, and Contabo.

Development

git clone https://githop.xyz/GnosysLabs/Synapsis.git
cd Synapsis
npm install
cp .env.example .env
npm run db:migrate
npm run dev

The development database defaults to ./data/synapsis.db. No separate database server is needed.

Common commands:

npm run type-check
npm test
npm run db:generate
npm run db:migrate
npm run build

Architecture

• Framework: Next.js 16 and React 19
• Database: embedded Turso with Drizzle ORM's relational-query v2 API
• Identity: DIDs and per-user signing keys
• Media: user-owned Stuffbox or S3-compatible storage
• Federation: Synapsis Swarm discovery and signed interactions
• Deployment: native Node.js process managed by systemd

License

Licensed under the Apache License 2.0.