Relay Parameters (Railway + Vercel)

This document covers all environment variables used by the AIS/OpenSky relay path:

Railway relay process: scripts/ais-relay.cjs
Desktop-product-only OpenSky relay: api/opensky.js (not part of the public API offering)
Vercel relay proxy endpoints (legacy): api/ais-snapshot.js, api/polymarket.js, api/rss-proxy.js

The legacy proxy endpoints in the second bullet are being phased out in favor of the sebuf proto-first approach. The OpenSky route is a restricted desktop-product transport, not a public integration surface. See Adding Endpoints for the current recommended pattern.

Server relay callers: server/worldmonitor/* handlers
Optional browser local fallback callers in src/services/*

1) Minimum Production Setup

Set these before enabling strict relay auth.

Railway (relay)

Variable	Required	Example	Notes
`AISSTREAM_API_KEY`	Yes	`ais_...`	Required for AIS upstream WebSocket feed.
`RELAY_SHARED_SECRET`	Yes	`wm_relay_prod_...`	Must exactly match Vercel value.
`RELAY_AUTH_HEADER`	Recommended	`x-relay-key`	Must match Vercel if changed from default.

Vercel (proxy + server functions)

Variable	Required	Example	Notes
`WS_RELAY_URL`	Yes	`https://<railway-app>.up.railway.app`	HTTPS relay base URL used by server-side proxy calls.
`RELAY_SHARED_SECRET`	Yes	`wm_relay_prod_...`	Must exactly match Railway value.
`RELAY_AUTH_HEADER`	Recommended	`x-relay-key`	Header name used to forward relay secret.

2) Full Parameter Reference

Core Relay/Auth

Variable	Set On	Default	Required	Purpose
`AISSTREAM_API_KEY`	Railway	none	Yes	Auth for AIS upstream stream source.
`VITE_AISSTREAM_API_KEY`	Local dev only	none	No	Local fallback if `AISSTREAM_API_KEY` is missing. Not recommended for production.
`PORT`	Railway/local	`3004`	No	HTTP server listen port for relay process.
`WS_RELAY_URL`	Vercel + server handlers	none	Yes (for relay-backed features)	Base URL used by Vercel/server to reach Railway relay.
`VITE_WS_RELAY_URL`	Browser (local dev)	none	No	Localhost fallback path for direct browser calls in development only.
`RELAY_SHARED_SECRET`	Railway + Vercel + self-hosted	empty	Yes (always)	Shared secret for non-public relay routes. The relay refuses to start without it unless `I_UNDERSTAND_THIS_DISABLES_AUTH=true`.
`RELAY_AUTH_HEADER`	Railway + Vercel	`x-relay-key`	No (but recommended explicit)	Header name carrying relay secret.
`I_UNDERSTAND_THIS_DISABLES_AUTH`	Railway / self-hosted	`false`	No	Dev-only escape hatch. If `true`, the relay boots WITHOUT a shared secret and logs a loud `[SECURITY]` line at boot and every 5 minutes. `/status` and `/wits` still require a configured secret. Never set in production.
`ALLOW_UNAUTHENTICATED_RELAY`	Railway / self-hosted	`false`	No	Deprecated alias of `I_UNDERSTAND_THIS_DISABLES_AUTH`. Still accepted for back-compat; the relay logs a `[DEPRECATED]` warning when this name is used.
`ALLOW_VERCEL_PREVIEW_ORIGINS`	Railway	`false`	No	If `true`, allows `*.vercel.app` origins in relay CORS checks.

WITS tariff transport

The bilateral tariff handler uses WS_RELAY_URL, RELAY_SHARED_SECRET, and RELAY_AUTH_HEADER to fetch WITS through the authenticated GET /wits route. Without WS_RELAY_URL, it calls WITS directly. A configured relay failure remains an upstream failure; the handler does not retry through the direct path. The route accepts one path query parameter for TRN reported rows, MFN AVE rows, reporter/year availability, or country/group metadata. It constructs a fixed https://wits.worldbank.org destination, rejects redirects, and never forwards the relay secret upstream. Requests have a nine-second deadline through body completion and a 4 MiB response limit. Upstream status codes and XML pass through unchanged. The relay sends no-store; the tariff handler retains its existing Redis cache, historical year, source attribution, and tariff basis. Deploy the relay route before the API caller when activating this transport. The caller does not fall back to direct WITS if the relay returns 404 because its route has not been deployed.

Relay-Adjacent Feature Flags

Variable	Set On	Default	Required	Purpose
`VITE_ENABLE_AIS`	Browser/client build env	enabled (unless `false`)	No	Client-side feature gate for AIS UI/polling.
`LOCAL_API_MODE`	Local/server runtime	none	No	If contains `sidecar`, some server handlers bypass relay and call OpenSky directly.
`WINGBITS_API_KEY`	Vercel/server	none	No	Military enrichment/fallback source used by server handlers; not required for relay core.

OpenSky Upstream Auth

Variable	Set On	Default	Required	Purpose
`OPENSKY_CLIENT_ID`	Railway	none	No (recommended)	OAuth client ID for higher OpenSky reliability/rate limits.
`OPENSKY_CLIENT_SECRET`	Railway	none	No (recommended)	OAuth client secret paired with client ID.

OpenSky Cache/Cardinality Controls

Variable	Set On	Default	Required	Purpose
`OPENSKY_CACHE_MAX_ENTRIES`	Railway	`128`	No	Max positive cache keys retained in memory.
`OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES`	Railway	`256`	No	Max negative cache keys (`429/5xx`) retained in memory.
`OPENSKY_BBOX_QUANT_STEP`	Railway	`0.01`	No	Coordinate quantization step for bbox cache key reuse. `0` disables quantization.

AIS Pipeline Tuning

Variable	Set On	Default	Required	Purpose
`AIS_SNAPSHOT_INTERVAL_MS`	Railway	`5000` (min `2000`)	No	Interval for rebuilding snapshot payloads.
`AIS_UPSTREAM_QUEUE_HIGH_WATER`	Railway	`4000` (min `500`)	No	Pause upstream socket when queue reaches this.
`AIS_UPSTREAM_QUEUE_LOW_WATER`	Railway	`1000` (clamped below HIGH_WATER)	No	Resume upstream socket when queue drops below this.
`AIS_UPSTREAM_QUEUE_HARD_CAP`	Railway	`8000` (must be `> HIGH_WATER`)	No	Max queue size before dropping incoming upstream messages.
`AIS_UPSTREAM_DRAIN_BATCH`	Railway	`250` (min `1`)	No	Max messages drained per cycle.
`AIS_UPSTREAM_DRAIN_BUDGET_MS`	Railway	`20` (min `2`)	No	Max CPU time budget per drain cycle.
`AIS_RECONNECT_BASE_MS`	Railway	`5000` (min `50`)	No	Base delay of the exponential upstream reconnect ladder.
`AIS_RECONNECT_MAX_MS`	Railway	`300000` (min `100`)	No	Ordinary ceiling for the reconnect ladder.
`AIS_THROTTLE_RECONNECT_MAX_MS`	Railway	`1800000` (min `100`, and never below `AIS_RECONNECT_MAX_MS`)	No	Escalated ceiling applied once the provider throttles persistently. Clamped up to `AIS_RECONNECT_MAX_MS` when configured lower, so escalation can never shorten the wait and reconnect harder while being throttled.
`AIS_THROTTLE_ESCALATE_AFTER`	Railway	`5` (min `1`)	No	Consecutive HTTP 429 upgrade rejections before the escalated ceiling applies.

Rate Limit / Logging / Metrics

Variable	Set On	Default	Required	Purpose
`RELAY_RATE_LIMIT_WINDOW_MS`	Railway	`60000`	No	Global rate-limit window.
`RELAY_RATE_LIMIT_MAX`	Railway	`1200`	No	Default max requests per IP per window.
`RELAY_OPENSKY_RATE_LIMIT_MAX`	Railway	`600`	No	OpenSky route max requests per IP per window.
`RELAY_RSS_RATE_LIMIT_MAX`	Railway	`300`	No	RSS route max requests per IP per window.
`RELAY_LOG_THROTTLE_MS`	Railway	`10000`	No	Minimum interval between repeated log events per key.
`RELAY_METRICS_WINDOW_SECONDS`	Railway	`60` (min `10`)	No	Rolling window used by `/metrics`.

Platform-Managed Variables (Do Not Manually Set)

These are used only for production detection and are usually injected by platform/runtime.

Variable	Who sets it	Purpose
`NODE_ENV`	Runtime/platform	Used to detect production mode.
`RAILWAY_ENVIRONMENT`	Railway	Used to detect production relay environment.
`RAILWAY_PROJECT_ID`	Railway	Used to detect production relay environment.
`RAILWAY_STATIC_URL`	Railway	Used to detect production relay environment.

3) Recommended Starting Values (High Traffic Baseline)

These are safe starting points for a busy relay:

# Auth + routing — RELAY_SHARED_SECRET is REQUIRED (the relay exits at startup
# without it unless I_UNDERSTAND_THIS_DISABLES_AUTH=true is set).
RELAY_SHARED_SECRET=<strong-random-secret>   # openssl rand -hex 32
RELAY_AUTH_HEADER=x-relay-key
WS_RELAY_URL=https://<your-railway-relay>.up.railway.app
# I_UNDERSTAND_THIS_DISABLES_AUTH=false   # dev-only override; do NOT set in prod

# OpenSky cache/cardinality
OPENSKY_CACHE_MAX_ENTRIES=256
OPENSKY_NEGATIVE_CACHE_MAX_ENTRIES=512
OPENSKY_BBOX_QUANT_STEP=0.01

# AIS pipeline
AIS_SNAPSHOT_INTERVAL_MS=3000
AIS_UPSTREAM_QUEUE_HIGH_WATER=5000
AIS_UPSTREAM_QUEUE_LOW_WATER=1500
AIS_UPSTREAM_QUEUE_HARD_CAP=10000
AIS_UPSTREAM_DRAIN_BATCH=300
AIS_UPSTREAM_DRAIN_BUDGET_MS=20

# Rate limits + metrics
RELAY_RATE_LIMIT_WINDOW_MS=60000
RELAY_RATE_LIMIT_MAX=1200
RELAY_OPENSKY_RATE_LIMIT_MAX=600
RELAY_RSS_RATE_LIMIT_MAX=300
RELAY_LOG_THROTTLE_MS=10000
RELAY_METRICS_WINDOW_SECONDS=60

4) How to Verify Configuration

Health:

curl -sS https://<relay>/health

Metrics (requires relay auth):

curl -sS https://<relay>/metrics \
  -H "x-relay-key: $RELAY_SHARED_SECRET"

or:

curl -sS https://<relay>/metrics \
  -H "Authorization: Bearer $RELAY_SHARED_SECRET"

Expected checks:

auth.enabled is true in /health (canonical operator-visible flag — true only when a shared secret is configured AND the I_UNDERSTAND_THIS_DISABLES_AUTH bypass is NOT engaged). auth.sharedSecretEnabled is preserved for back-compat.
/metrics.opensky.hitRatio is stable and high under load.
/metrics.ais.dropsPerSec stays at 0 in normal operation.
/metrics.ais.queueMax is comfortably below AIS_UPSTREAM_QUEUE_HARD_CAP.

Getting Started

Usage

Platform & Features

Intelligence & Analysis

Workflows

Map Layers

Finance

Panels — AI & PRO

Panels — Data & Tracking

Panels — Catalogues

Desktop Application

MCP & Integrations

HTTP API

Developer Guide

Company

Legal

Relay Parameters (Railway + Vercel)

1) Minimum Production Setup

Railway (relay)

Vercel (proxy + server functions)

2) Full Parameter Reference

Core Relay/Auth

WITS tariff transport

Relay-Adjacent Feature Flags

OpenSky Upstream Auth

OpenSky Cache/Cardinality Controls

AIS Pipeline Tuning

Rate Limit / Logging / Metrics

Platform-Managed Variables (Do Not Manually Set)

3) Recommended Starting Values (High Traffic Baseline)

4) How to Verify Configuration

​1) Minimum Production Setup

​Railway (relay)

​Vercel (proxy + server functions)

​2) Full Parameter Reference

​Core Relay/Auth

​WITS tariff transport

​Relay-Adjacent Feature Flags

​OpenSky Upstream Auth

​OpenSky Cache/Cardinality Controls

​AIS Pipeline Tuning

​Rate Limit / Logging / Metrics

​Platform-Managed Variables (Do Not Manually Set)

​3) Recommended Starting Values (High Traffic Baseline)

​4) How to Verify Configuration

1) Minimum Production Setup

Railway (relay)

Vercel (proxy + server functions)

2) Full Parameter Reference

Core Relay/Auth

WITS tariff transport

Relay-Adjacent Feature Flags

OpenSky Upstream Auth

OpenSky Cache/Cardinality Controls

AIS Pipeline Tuning

Rate Limit / Logging / Metrics

Platform-Managed Variables (Do Not Manually Set)

3) Recommended Starting Values (High Traffic Baseline)

4) How to Verify Configuration