@neuraiproject/neurai-relay

The relay server of Neurai Connect. It forwards encrypted messages between a wallet and a website by topic, keeps them in a mailbox until the other side fetches them, and learns nothing else: no addresses, no domains, no content. Clients authenticate with Ed25519 did:key JWTs.

Specification: spec/relay-rpc.md.

Running it

The supported way is the Docker Compose setup in docker/ of the repository: docker-compose.yml for production (Redis-backed mailbox, health checks, log rotation) and docker-compose.dev.yml for local testing (in-memory mailbox, debug logging). Every setting is an environment variable and is documented in docker/.env.example.

cp docker/.env.example docker/.env      # set RELAY_PUBLIC_URL at least
docker compose -f docker/docker-compose.yml up -d --build
curl http://127.0.0.1:19030/health       # {"ok":true}

The package can also run directly with Node 24+:

RELAY_PUBLIC_URL=wss://relay.example.org/v1 npx @neuraiproject/neurai-relay

Two settings deserve a warning:

• RELAY_PUBLIC_URL is the JWT audience. Clients sign the URL they dial, and the relay compares it byte for byte: ws://localhost:19030/v1 and ws://127.0.0.1:19030/v1 are different audiences.
• Never expose the relay without TLS. Keep the port on the loopback and terminate TLS in a reverse proxy (an nginx example is in docker/nginx.example.conf), or set RELAY_TLS_*.

Optional features, each enabled by its variables: Redis persistence (RELAY_STORAGE=redis, REDIS_URL), API keys for the WebSocket upgrade (RELAY_API_KEYS), an allow-list of browser origins (RELAY_ALLOWED_ORIGINS), push notifications through a generic hook (RELAY_PUSH_URL, RELAY_PUSH_TOKEN; without them the nc_push* methods are not exposed) and Prometheus metrics (RELAY_METRICS_ENABLED).

Embedding it

import { createRelayServer, configFromEnv } from "@neuraiproject/neurai-relay";

const server = createRelayServer(configFromEnv(process.env));
await server.start();

This is what the end-to-end tests and the demo of the repository do.

License

MIT. The relay implements the WalletConnect v2 relay protocol (irn_* methods) as documented in the specification; it does not depend on any WalletConnect package.