@eryv/federation-server

Federation server for the eryv agentic AI conversation platform. Handles content hosting, the peering protocol, user accounts, and community features. This is the only component that requires hosting infrastructure — the core product (engine + frontend) works without it.

Status: Early development (0.0.1). The server skeleton is in place but API routes are not yet implemented. See the roadmap for timeline.

Overview

The federation server exposes two API surfaces:

Client-Server (C-S) API

How the frontend talks to a federation instance:

• Content CRUD (publish, browse, search, install)
• User authentication and profiles
• Social features (ratings, comments, collections)
• Instance info and rules

Server-Server (S-S) API

How federation instances talk to each other:

• Peering (request, accept, reject)
• Content synchronization (push, pull, since-timestamp)
• Identity verification (vouch for users across instances)
• Moderation signals (reports, blocks)

Design Principles

• Separate from the core product. The engine and frontend never depend on federation being available.
• Every instance is equal. No instance has protocol-level privileges. The main site's advantage is network effects, not protocol advantage.
• Moderation is local. Each instance sets its own policy (NSFW rules, blocked tags, peering approval, rate limits).
• Content is signed at origin. Published content is cryptographically signed by the origin instance.
• Identity is per-instance. Users authenticate with their home instance (@[email protected]).

Running

# Development
pnpm dev

# Production
pnpm build && pnpm start

Docker

# Full stack (federation + postgres)
docker compose up federation-server

# Or build directly
docker build -f packages/federation-server/Dockerfile -t eryv-federation .
docker run -p 3000:3000 \
  -e DATABASE_URL=postgres://user:pass@host:5432/eryv \
  -e JWT_SECRET=change-me \
  eryv-federation

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | DATABASE_URL | Yes | — | Postgres connection string | | PORT | No | 3000 | Server port | | NODE_ENV | No | — | Set to production for deployed instances | | INSTANCE_DOMAIN | No | — | Public domain for federation identity | | JWT_SECRET | Yes (prod) | — | Secret for auth tokens |

License

AGPL-3.0-only