Configuration

SocketX Server is configured with environment variables. A .env file is loaded automatically when present, which is useful for local development.

Required Variables

Variable	Description
DOMAIN_MAP	JSON string that maps incoming Host headers to upstream WebSocket URLs and allowed origins.

Interactive Builder

Use the DOMAIN_MAP Builder tool to configure your domain mappings visually and copy a ready-to-use DOMAIN_MAP value.

Optional Variables

Variable	Default	Description
LISTEN_HOST	0.0.0.0	Address the server binds to.
LISTEN_PORT	8080	Port the server listens on.
LOG_LEVEL	info	Zerolog level: trace, debug, info, warn, error, fatal, panic, or disabled. Invalid values fall back to info.
MTE_KYBER_STRENGTH	1024 (v2) / 512 (v1)	Kyber strength: 0, 512, 768, or 1024. See version note below.
MTE_DECODER_WINDOW_SIZE	1000	MTE decoder re-sequencing window.
WS_READ_BUFFER_SIZE	1024	WebSocket read buffer size in bytes.
WS_WRITE_BUFFER_SIZE	1024	WebSocket write buffer size in bytes.
WS_MAX_MESSAGE_SIZE	16777216	Maximum message size in bytes (16 MiB), enforced on both the client and upstream connections. Oversized frames are refused with close code 1009. 0 disables the limit.
CLIENT_PONG_TIMEOUT	60	Seconds allowed to receive a pong from the client.
CLIENT_PING_INTERVAL	54	Seconds between proxy-to-client pings. Keep below CLIENT_PONG_TIMEOUT.
UPSTREAM_PONG_TIMEOUT	60	Seconds allowed to receive a pong from upstream.
UPSTREAM_PING_INTERVAL	54	Seconds between proxy-to-upstream pings. Keep below UPSTREAM_PONG_TIMEOUT.
WRITE_TIMEOUT	10	Seconds allowed for WebSocket writes, including ping frames.
USE_CONSOLE_LOGS	false	Set to true for human-readable console logs instead of JSON logs.
MTE_EVENT_SAMPLE_RATE	1.0	v2 only. Fraction (0.0–1.0) of per-message MTE encryption/decryption events that are logged. Lower it to control log ingest cost on platforms that bill per GB (Datadog, New Relic). Connection audits and recovery events are never sampled.

Kyber strength default by version

The MTE_KYBER_STRENGTH default depends on the SocketX Server version: v1 (the currently released version) defaults to 512, while v2 (the next version, not yet released) changes the default to 1024. Set the variable explicitly if you need a specific strength regardless of version.

DOMAIN_MAP

DOMAIN_MAP is a JSON object. Each key is an incoming Host value or wildcard pattern. Each value must contain:

• upstream: the base upstream WebSocket URL, including ws:// or wss://.
• allowedOrigins: a list of allowed browser Origin values.

{
  "api.example.com": {
    "upstream": "wss://backend.example.com/socket",
    "allowedOrigins": ["https://app.example.com"]
  },
  "*.staging.example.com": {
    "upstream": "ws://staging-backend:8080",
    "allowedOrigins": ["https://*.staging.example.com"]
  },
  "*": {
    "upstream": "ws://default-backend:8080",
    "allowedOrigins": ["*"]
  }
}

Matching order:

1. Exact host match.
2. Subdomain wildcard match such as *.example.com.
3. Global wildcard match *.

Important details:

• Host may include a port. For local development, map localhost:8080 or use *.
• Exact origins include the scheme, such as https://app.example.com.
• Origin wildcard entries must begin with *. as implemented, such as https://*.example.com.
• allowedOrigins is required in practice. If the list is empty or omitted, origin validation rejects the connection.
• Non-browser clients may omit the Origin header. Use allowedOrigins: ["*"] or deliberately allow the empty origin if that is required for your environment.

Example Configurations

Minimal

DOMAIN_MAP={"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}

Full

DOMAIN_MAP={"*":{"upstream":"ws://example.com","allowedOrigins":["*"]}}
LISTEN_HOST=0.0.0.0
LISTEN_PORT=8080
LOG_LEVEL=info
WS_READ_BUFFER_SIZE=2048
WS_WRITE_BUFFER_SIZE=2048
CLIENT_PONG_TIMEOUT=60
CLIENT_PING_INTERVAL=54
UPSTREAM_PONG_TIMEOUT=60
UPSTREAM_PING_INTERVAL=54
WRITE_TIMEOUT=10
USE_CONSOLE_LOGS=false