Federation

LynxPrompt instances can join a federated network for discovery and visibility. Federation lets you see what other instances exist, what version they run, and how many public blueprints they host.

What Is Federation?

Federation is a lightweight protocol that connects independent LynxPrompt instances into a shared directory. Each self-hosted instance can register with a central registry (by default, lynxprompt.com) so that other instances — and their users — can discover it.

Instance Directory

Registered instances appear on the /federation page with their name, version, blueprint count, and online status.

Zero Trust Verification

The registry verifies every instance by fetching its .well-known/lynxprompt.json endpoint. Domain ownership is confirmed before listing.

How It Works

The federation protocol has three steps: registration, verification, and heartbeat.

Register

When an instance with ENABLE_FEDERATION=true starts, it sends its domain to the registry via POST /api/v1/federation/register.

Verify

The registry fetches https://your-domain/.well-known/lynxprompt.json to confirm the instance is a real LynxPrompt deployment. It checks that federation, domain, name, and version are present and that the domain matches.

Heartbeat

Registered instances send periodic heartbeats via POST /api/v1/federation/heartbeat. The registry re-verifies the .well-known endpoint and updates the instance's version, blueprint count, and last-seen timestamp. Instances not seen in 24 hours are marked inactive.

What's Available Now

Federation currently provides instance registration and discovery.

Registration

Self-hosted instances register automatically on startup. No API keys or manual steps required.

Discovery

Browse all federated instances on the /federation page with live status indicators.

Blueprint Catalog API

Each instance exposes its public blueprints via /api/v1/federation/blueprints for programmatic access.

What's Coming

Federation is being extended with cross-instance features:

Cross-Instance Blueprint Browsing & Sharing

Browse and download public blueprints from any federated instance directly in your local UI — no need to visit each instance separately. This is not yet implemented but is the next step for federation.

Self-Hosting Configuration

Joining the federation requires a single environment variable. The registry URL is optional and only needed if you run your own registry.

Variable	Default	Description
`ENABLE_FEDERATION`	true	Register this instance with the federation and enable the `/federation` page
`FEDERATION_REGISTRY_URL`	https://lynxprompt.com	URL of the registry to register with. Only set this if you operate your own registry

# Minimal — join the default public network
ENABLE_FEDERATION=true

# Custom registry (only if running your own)
ENABLE_FEDERATION=true
FEDERATION_REGISTRY_URL=https://lynxprompt.yourcompany.com

Requirement: Your instance must be reachable over HTTPS with a valid .well-known/lynxprompt.json endpoint. LynxPrompt serves this automatically — just make sure your domain and TLS are configured correctly.

Federation API

All federation endpoints live under /api/v1/federation/ and require federation to be enabled.

POST/register

POST/heartbeat

Send a heartbeat for a registered instance. Body: { "domain": "lynx.example.com" }. Updates last-seen time, version, and blueprint count.

GET/instances

List all verified instances. Pass ?active=true to filter to instances seen in the last 24 hours.

GET/blueprints

List public blueprints on this instance. Supports ?limit=50&offset=0 pagination (max 100 per page).

See the network

Browse all federated LynxPrompt instances and their public blueprints.

View Federation