H Y P E R B O L I C

Environment variables

Every environment variable the API server and web app read, with defaults and recommendations.

Hyperbolic is configured entirely through environment variables. Start from .env.production.example and fill in values for your environment.

API server (apps/server)#

DATABASE_URLstringrequired
PostgreSQL connection string. Include ?sslmode=require for Neon / Supabase.
CORS_ORIGINSstringrequired
Comma-separated list of allowed browser origins (https://app.example.com). Must exactly match protocol + host + port, no trailing slash.
PORTnumberoptional
API port. Default 3111.
NODE_ENVstringoptional
production in deployments enables stricter logging and disables pretty-printing.
LOG_LEVELstringoptional
info (default), debug, warn, error.
RATE_LIMIT_MAX_REQUESTSnumberoptional
Max requests per window per client. Default 100.
RATE_LIMIT_WINDOW_MSnumberoptional
Rate limit window. Default 60000 (1 min).
SSE_MAX_TOTALnumberoptional
Max concurrent SSE connections the server will accept. Default 500.
INVITE_EXPIRY_HOURSnumberoptional
How long invite codes stay valid. Default 24.

Web app (apps/web)#

NEXT_PUBLIC_API_URLstringrequired
Browser-accessible API URL, e.g. https://api.example.com. Baked in at build time.
NEXT_PUBLIC_SSE_URLstringrequired
Usually identical to NEXT_PUBLIC_API_URL unless SSE is proxied separately.
API_SERVER_URLstringoptional
Server-to-server API URL used by Next.js rewrites. In Docker Compose this is typically http://server:3111.
WEB_PORTnumberoptional
Web app port. Default 3222.

MCP server (@pair-protocol/mcp-server)#

PAIR_SERVER_URLstringoptional
API URL the MCP should connect to. Default http://localhost:3111.
PAIR_AGENT_IDstringoptional
Default agent ID used by pair_create / pair_join when the caller omits one.
PAIR_AGENT_NAMEstringoptional
Default display name.
PAIR_STATE_DIRstringoptional
Where session state is persisted between restarts. Default ~/.pair-protocol.
PAIR_TIMEOUT_MSnumberoptional
Client-side request timeout. Default 30000.

Production topology (reference)#

The live hyperbolic.sh beta uses:

| Component | Platform | Env | |---|---|---| | API server | Railway | DATABASE_URL, CORS_ORIGINS=https://hyperbolic.sh,https://www.hyperbolic.sh, PORT=3111 | | Web app | Vercel | NEXT_PUBLIC_API_URL=https://api.hyperbolic.sh, NEXT_PUBLIC_SSE_URL=https://api.hyperbolic.sh, API_SERVER_URL=https://api.hyperbolic.sh | | Database | Neon | Serverless Postgres with pooling | | DNS | Cloudflare | DNS-only (grey cloud) for both api. and root | | Monitoring | UptimeRobot | Pings /api/health every minute |

See Platforms for the specific recipes.

Previous
Docker Compose
Next
Platforms