Server

Environment Variables

Complete reference of all environment variables supported by Sockudo.

Environment variables override values from config/config.json and have the highest priority.

Core Runtime

Variable	Type	Default	Description
`HOST`	`string`	`0.0.0.0`	Bind address
`PORT`	`u16`	`6001`	HTTP/WebSocket port
`ENVIRONMENT`	`string`	`production`	Runtime mode
`DEBUG`	`bool`	`false`	Force debug mode on (takes precedence over `DEBUG_MODE`)
`DEBUG_MODE`	`bool`	`false`	Enable debug mode
`ACTIVITY_TIMEOUT`	`u64`	`120`	Connection activity timeout in seconds
`SHUTDOWN_GRACE_PERIOD`	`u64`	`10`	Graceful shutdown timeout in seconds
`USER_AUTHENTICATION_TIMEOUT`	`u64`	`3600`	User authentication timeout in seconds
`WEBSOCKET_MAX_PAYLOAD_KB`	`u32`	`64`	Max WebSocket payload size in KB
`INSTANCE_PROCESS_ID`	`string`	`<uuid>`	Unique instance identifier

Default App Bootstrap

Create a default app from environment variables without a config file.

Variable	Type	Default	Description
`SOCKUDO_DEFAULT_APP_ID`	`string`	—	App ID (required with key+secret)
`SOCKUDO_DEFAULT_APP_KEY`	`string`	—	App key (required with id+secret)
`SOCKUDO_DEFAULT_APP_SECRET`	`string`	—	App secret (required with id+key)
`SOCKUDO_DEFAULT_APP_ENABLED`	`bool`	`true`	Enable the default app
`SOCKUDO_ENABLE_CLIENT_MESSAGES`	`bool`	`false`	Allow client-to-client events
`SOCKUDO_DEFAULT_APP_ENABLE_USER_AUTHENTICATION`	`bool`	`false`	Enable user authentication
`SOCKUDO_DEFAULT_APP_MAX_CONNECTIONS`	`u32`	`100`	Max simultaneous connections
`SOCKUDO_DEFAULT_APP_MAX_CLIENT_EVENTS_PER_SECOND`	`u32`	`100`	Client event rate limit
`SOCKUDO_DEFAULT_APP_MAX_READ_REQUESTS_PER_SECOND`	`u32`	`100`	Read request rate limit
`SOCKUDO_DEFAULT_APP_MAX_BACKEND_EVENTS_PER_SECOND`	`u32`	`100`	Backend event rate limit
`SOCKUDO_DEFAULT_APP_MAX_PRESENCE_MEMBERS_PER_CHANNEL`	`u32`	`100`	Max presence members per channel
`SOCKUDO_DEFAULT_APP_MAX_PRESENCE_MEMBER_SIZE_IN_KB`	`u32`	`100`	Max presence member data size in KB
`SOCKUDO_DEFAULT_APP_MAX_CHANNEL_NAME_LENGTH`	`u32`	`100`	Max channel name length
`SOCKUDO_DEFAULT_APP_MAX_EVENT_CHANNELS_AT_ONCE`	`u32`	`100`	Max channels per event broadcast
`SOCKUDO_DEFAULT_APP_MAX_EVENT_NAME_LENGTH`	`u32`	`100`	Max event name length
`SOCKUDO_DEFAULT_APP_MAX_EVENT_PAYLOAD_IN_KB`	`u32`	`100`	Max event payload size in KB
`SOCKUDO_DEFAULT_APP_MAX_EVENT_BATCH_SIZE`	`u32`	`100`	Max events per batch
`SOCKUDO_DEFAULT_APP_ENABLE_WATCHLIST_EVENTS`	`bool`	`false`	Enable watchlist events
`SOCKUDO_DEFAULT_APP_ALLOWED_ORIGINS`	`string`	—	Comma-separated list of allowed origins

Driver Selection

Variable	Type	Default	Description
`ADAPTER_DRIVER`	`string`	`local`	Pub/sub adapter: `local`, `redis`, `redis-cluster`, `nats`
`CACHE_DRIVER`	`string`	`memory`	Cache backend: `memory`, `redis`, `redis-cluster`, `none`
`QUEUE_DRIVER`	`string`	`redis`	Queue backend: `memory`, `redis`, `redis-cluster`, `sqs`, `none`
`APP_MANAGER_DRIVER`	`string`	`memory`	App store: `memory`, `mysql`, `postgres`, `dynamodb`, `scylladb`
`RATE_LIMITER_DRIVER`	`string`	`memory`	Rate limiter backend: `memory`, `redis`, `redis-cluster`, `none`
`METRICS_DRIVER`	`string`	`prometheus`	Metrics backend: `prometheus`

Adapter

Variable	Type	Default	Description
`ADAPTER_BUFFER_MULTIPLIER_PER_CPU`	`usize`	`64`	Concurrent operations per CPU core
`ADAPTER_ENABLE_SOCKET_COUNTING`	`bool`	`true`	Enable connection counting across nodes

Database: Redis

Variable	Type	Default	Description
`DATABASE_REDIS_HOST`	`string`	`127.0.0.1`	Redis host
`DATABASE_REDIS_PORT`	`u16`	`6379`	Redis port
`DATABASE_REDIS_DB`	`u32`	`0`	Redis database number
`DATABASE_REDIS_USERNAME`	`string`	—	Redis username (ACL)
`DATABASE_REDIS_PASSWORD`	`string`	—	Redis password
`DATABASE_REDIS_KEY_PREFIX`	`string`	`sockudo:`	Key prefix for all Redis keys
`REDIS_URL`	`string`	—	Override all Redis connections with a single URL

Redis Cluster

Variable	Type	Default	Description
`REDIS_CLUSTER_NODES`	`string`	—	Comma-separated cluster node URLs
`DATABASE_REDIS_CLUSTER_NODES`	`string`	—	Same as above (alias)
`DATABASE_REDIS_CLUSTER_USERNAME`	`string`	—	Cluster auth username
`DATABASE_REDIS_CLUSTER_PASSWORD`	`string`	—	Cluster auth password
`DATABASE_REDIS_CLUSTER_USE_TLS`	`bool`	`false`	Use TLS for cluster connections

Database: MySQL

Variable	Type	Default	Description
`DATABASE_MYSQL_HOST`	`string`	`localhost`	MySQL host
`DATABASE_MYSQL_PORT`	`u16`	`3306`	MySQL port
`DATABASE_MYSQL_USERNAME`	`string`	`root`	MySQL username
`DATABASE_MYSQL_PASSWORD`	`string`	(empty)	MySQL password
`DATABASE_MYSQL_DATABASE`	`string`	`sockudo`	MySQL database name
`DATABASE_MYSQL_TABLE_NAME`	`string`	`applications`	Table name for app manager
`DATABASE_MYSQL_POOL_MIN`	`u32`	—	Min pool connections (per-DB override)
`DATABASE_MYSQL_POOL_MAX`	`u32`	—	Max pool connections (per-DB override)

Database: PostgreSQL

Variable	Type	Default	Description
`DATABASE_POSTGRES_HOST`	`string`	`localhost`	PostgreSQL host
`DATABASE_POSTGRES_PORT`	`u16`	`3306`	PostgreSQL port
`DATABASE_POSTGRES_USERNAME`	`string`	`root`	PostgreSQL username
`DATABASE_POSTGRES_PASSWORD`	`string`	(empty)	PostgreSQL password
`DATABASE_POSTGRES_DATABASE`	`string`	`sockudo`	PostgreSQL database name
`DATABASE_POSTGRES_POOL_MIN`	`u32`	—	Min pool connections (per-DB override)
`DATABASE_POSTGRES_POOL_MAX`	`u32`	—	Max pool connections (per-DB override)

Database: DynamoDB

Variable	Type	Default	Description
`DATABASE_DYNAMODB_REGION`	`string`	`us-east-1`	AWS region
`DATABASE_DYNAMODB_TABLE_NAME`	`string`	`sockudo-applications`	DynamoDB table name
`DATABASE_DYNAMODB_ENDPOINT_URL`	`string`	—	Custom endpoint (for local testing)
`AWS_ACCESS_KEY_ID`	`string`	—	AWS access key
`AWS_SECRET_ACCESS_KEY`	`string`	—	AWS secret key

Database Pooling

Variable	Type	Default	Description
`DATABASE_POOLING_ENABLED`	`bool`	`true`	Enable connection pooling
`DATABASE_POOL_MIN`	`u32`	`2`	Global minimum pool connections
`DATABASE_POOL_MAX`	`u32`	`10`	Global maximum pool connections
`DATABASE_CONNECTION_POOL_SIZE`	`u32`	`10`	Pool size (applies to both MySQL and PostgreSQL)

Cache

Variable	Type	Default	Description
`CACHE_TTL_SECONDS`	`u64`	`300`	Global cache TTL (applies to app manager cache, channel limits, DB caches, and memory cache)
`CACHE_CLEANUP_INTERVAL`	`u64`	`60`	Cache cleanup interval in seconds
`CACHE_MAX_CAPACITY`	`u64`	`10000`	Max cache entries

SSL / TLS

Variable	Type	Default	Description
`SSL_ENABLED`	`bool`	`false`	Enable TLS
`SSL_CERT_PATH`	`string`	(empty)	Path to certificate file
`SSL_KEY_PATH`	`string`	(empty)	Path to private key file
`SSL_REDIRECT_HTTP`	`bool`	`false`	Redirect HTTP to HTTPS
`SSL_HTTP_PORT`	`u16`	`80`	HTTP port for redirect listener

Unix Socket

Variable	Type	Default	Description
`UNIX_SOCKET_ENABLED`	`bool`	`false`	Enable Unix socket listener
`UNIX_SOCKET_PATH`	`string`	`/var/run/sockudo/sockudo.sock`	Socket file path (must be absolute)
`UNIX_SOCKET_PERMISSION_MODE`	`string`	`660`	Octal file permissions (e.g. `660`, `750`)

Metrics

Variable	Type	Default	Description
`METRICS_ENABLED`	`bool`	`true`	Enable metrics endpoint
`METRICS_HOST`	`string`	`0.0.0.0`	Metrics bind address
`METRICS_PORT`	`u16`	`9601`	Metrics port
`METRICS_PROMETHEUS_PREFIX`	`string`	`sockudo_`	Prometheus metric name prefix

Rate Limiter

Variable	Type	Default	Description
`RATE_LIMITER_ENABLED`	`bool`	`true`	Enable rate limiting
`RATE_LIMITER_API_MAX_REQUESTS`	`u32`	`100`	Max API requests per window
`RATE_LIMITER_API_WINDOW_SECONDS`	`u64`	`60`	API rate limit window
`RATE_LIMITER_API_TRUST_HOPS`	`u32`	`0`	Trusted proxy hops for API
`RATE_LIMITER_WS_MAX_REQUESTS`	`u32`	`20`	Max WebSocket connections per window
`RATE_LIMITER_WS_WINDOW_SECONDS`	`u64`	`60`	WebSocket rate limit window
`RATE_LIMITER_REDIS_PREFIX`	`string`	`sockudo_rl:`	Redis key prefix for rate limiter

Queue: Redis

Variable	Type	Default	Description
`QUEUE_REDIS_CONCURRENCY`	`u32`	`5`	Concurrent queue workers
`QUEUE_REDIS_PREFIX`	`string`	`sockudo_queue:`	Redis queue key prefix

Queue: Redis Cluster

Variable	Type	Default	Description
`REDIS_CLUSTER_QUEUE_CONCURRENCY`	`u32`	`5`	Cluster queue concurrency
`REDIS_CLUSTER_QUEUE_PREFIX`	`string`	`sockudo_queue:`	Cluster queue key prefix

Queue: SQS

Variable	Type	Default	Description
`QUEUE_SQS_REGION`	`string`	`us-east-1`	AWS region
`QUEUE_SQS_VISIBILITY_TIMEOUT`	`i32`	`30`	Message visibility timeout
`QUEUE_SQS_MAX_MESSAGES`	`i32`	`10`	Max messages per poll
`QUEUE_SQS_WAIT_TIME_SECONDS`	`i32`	`5`	Long polling wait time
`QUEUE_SQS_CONCURRENCY`	`u32`	`5`	Concurrent SQS workers
`QUEUE_SQS_FIFO`	`bool`	`false`	Use FIFO queue
`QUEUE_SQS_ENDPOINT_URL`	`string`	—	Custom SQS endpoint (for local testing)

Webhooks

Variable	Type	Default	Description
`WEBHOOK_BATCHING_ENABLED`	`bool`	`true`	Enable webhook batching
`WEBHOOK_BATCHING_DURATION`	`u64`	`50`	Batch window duration in ms

NATS Adapter

Variable	Type	Default	Description
`NATS_SERVERS`	`string`	`nats://localhost:4222`	Comma-separated NATS server URLs
`NATS_USERNAME`	`string`	—	NATS username
`NATS_PASSWORD`	`string`	—	NATS password
`NATS_TOKEN`	`string`	—	NATS auth token
`NATS_CONNECTION_TIMEOUT_MS`	`u64`	`5000`	Connection timeout in ms
`NATS_REQUEST_TIMEOUT_MS`	`u64`	`5000`	Request timeout in ms

CORS

Variable	Type	Default	Description
`CORS_ORIGINS`	`string`	`*`	Comma-separated allowed origins
`CORS_METHODS`	`string`	`GET,POST,OPTIONS`	Comma-separated allowed methods
`CORS_HEADERS`	`string`	`Authorization,Content-Type,X-Requested-With,Accept`	Comma-separated allowed headers
`CORS_CREDENTIALS`	`bool`	`true`	Allow credentials

Logging

Variable	Type	Default	Description
`LOG_COLORS_ENABLED`	`bool`	`true`	Enable colored log output
`LOG_INCLUDE_TARGET`	`bool`	`true`	Include target module in logs

Cleanup (Async Disconnect Processing)

Variable	Type	Default	Description
`CLEANUP_ASYNC_ENABLED`	`bool`	`true`	Enable async cleanup
`CLEANUP_FALLBACK_TO_SYNC`	`bool`	`true`	Fall back to synchronous cleanup if async fails
`CLEANUP_QUEUE_BUFFER_SIZE`	`usize`	`50000`	Cleanup queue buffer size
`CLEANUP_BATCH_SIZE`	`usize`	`25`	Disconnect batch size
`CLEANUP_BATCH_TIMEOUT_MS`	`u64`	`50`	Max wait time to fill a batch in ms
`CLEANUP_WORKER_THREADS`	`string`	`auto`	Worker threads: `auto` or a number
`CLEANUP_MAX_RETRY_ATTEMPTS`	`u32`	`2`	Max retry attempts for failed cleanups

Cluster Health

Variable	Type	Default	Description
`CLUSTER_HEALTH_ENABLED`	`bool`	`true`	Enable cluster health monitoring
`CLUSTER_HEALTH_HEARTBEAT_INTERVAL`	`u64`	`10000`	Heartbeat interval in ms
`CLUSTER_HEALTH_NODE_TIMEOUT`	`u64`	`30000`	Node considered dead after this ms
`CLUSTER_HEALTH_CLEANUP_INTERVAL`	`u64`	`10000`	Dead node check interval in ms

Tag Filtering

Variable	Type	Default	Description
`TAG_FILTERING_ENABLED`	`bool`	`false`	Enable tag-based filtering

WebSocket Buffer

Variable	Type	Default	Description
`WEBSOCKET_MAX_MESSAGES`	`string`	`1000`	Max buffered messages per connection (`none` or `0` to disable)
`WEBSOCKET_MAX_BYTES`	`string`	(disabled)	Max buffered bytes per connection (`none` or `0` to disable)
`WEBSOCKET_DISCONNECT_ON_BUFFER_FULL`	`bool`	`true`	Disconnect slow clients vs drop messages
`WEBSOCKET_MAX_MESSAGE_SIZE`	`usize`	`67108864`	Max message size in bytes (64 MB)
`WEBSOCKET_MAX_FRAME_SIZE`	`usize`	`16777216`	Max frame size in bytes (16 MB)
`WEBSOCKET_WRITE_BUFFER_SIZE`	`usize`	`16384`	Write buffer size in bytes (16 KB)
`WEBSOCKET_MAX_BACKPRESSURE`	`usize`	`1048576`	Max backpressure in bytes (1 MB)
`WEBSOCKET_AUTO_PING`	`bool`	`true`	Enable automatic pings
`WEBSOCKET_PING_INTERVAL`	`u32`	`30`	Ping interval in seconds
`WEBSOCKET_IDLE_TIMEOUT`	`u32`	`120`	Idle timeout in seconds (0 disables)
`WEBSOCKET_COMPRESSION`	`string`	`disabled`	Compression mode: `disabled`, `dedicated`, `shared`, `window256b`, `window1kb`, `window2kb`, `window4kb`, `window8kb`, `window16kb`, `window32kb`

If you already provide config/config.json, only set environment variables you need to override per environment.

SSL & Deployment

TLS termination, Unix sockets, reverse proxy setup, and deployment strategies.

HTTP API

Pusher-compatible HTTP endpoints and request signing.