Configuration

Configure apps, adapters, cache, queues, rate limits, history, recovery, webhooks, and push notifications.

Sockudo configuration should describe the runtime shape explicitly: app storage, fanout adapter, cache, queue, protocol features, security controls, metrics, webhooks, and push notification providers. For TOML versus JSON, file discovery, --config, environment precedence, and secret placement, start with Static configuration.

Minimal local config

port = 6001
host = "0.0.0.0"
debug = true

[app_manager]
driver = "memory"

[app_manager.array]
[[app_manager.array.apps]]
id = "app-id"
key = "app-key"
secret = "app-secret"
enabled = true

[app_manager.array.apps.policy.limits]
max_connections = 1000

[app_manager.array.apps.policy.features]
enable_client_messages = false

Production shape

port = 6001
host = "0.0.0.0"
debug = false

[app_manager]
driver = "postgres"

[adapter]
driver = "redis"

[cache]
driver = "redis"

[queue]
driver = "redis"

[metrics]
enabled = true
host = "0.0.0.0"
port = 9601

[metrics.tcp_exporter]
enabled = false
host = "127.0.0.1"
port = 5000
buffer_size = 1024

App manager

The app manager stores app credentials and app-level policy. Memory is useful for local development; persistent managers are preferred for production.

Driver	Use when
`memory`	Credentials are static and local to one process.
`postgres` or `mysql`	You need relational app records and standard operational tooling.
`redis`	You need lightweight shared app state.
`dynamodb`	You run on AWS and want managed key-value storage.
`scylladb`	You need wide-column scale.
`surrealdb`	You use SurrealDB 3 for app metadata.

Adapter

The adapter controls cross-node fanout.

[adapter]
driver = "redis"
enable_socket_counting = true
aggregate_counts = false
fast_presence_transitions = false

[adapter.redis]
host = "redis"
port = 6379
prefix = "sockudo"

Use a shared adapter for every multi-node deployment. Local memory adapters are intentionally process-local.

enable_socket_counting keeps the adapter's request/reply socket-count path enabled by default. aggregate_counts is off by default; enable it when you want each node to maintain gossiped cluster-wide channel counts for local count reads. fast_presence_transitions is off by default. Enabling it uses the replicated presence registry for first-join and last-leave checks, which avoids request/reply fanout but makes presence webhook/history transition decisions eventually consistent.

For high-churn benchmark runs that should avoid distributed count fanout, use:

ADAPTER_ENABLE_SOCKET_COUNTING=false
ADAPTER_AGGREGATE_COUNTS=true
# Optional: enables eventual-consistency presence transition checks.
ADAPTER_FAST_PRESENCE_TRANSITIONS=true

Recovery and history

[recovery]
enabled = true
buffer_size = 1000
ttl_seconds = 120

[history]
enabled = true
retention_seconds = 86400
max_items_per_channel = 10000

Recovery buffers are for reconnect continuity. Durable history is for API reads, rewind, versioned messages, and operational inspection. Keep those concerns separate.

Push notifications

Push is a core Sockudo subsystem. Configure it with a queue, provider credentials, retention, admission limits, and metrics before sending production traffic.

[push]
storage_driver = "postgres"
queue_driver = "redis"
publish_status_ttl_days = 30
analytics_retention_days = 30
scheduler_interval_secs = 5
cleanup_interval_secs = 300
cleanup_batch_size = 1000
cleanup_max_deleted_per_tick = 100000

# Runtime env for FCM monolith workers:
# PUSH_FCM_ENABLED=true
# PUSH_FCM_SERVICE_ACCOUNT_JSON_PATH=/var/run/secrets/fcm-service-account.json
# PUSH_FCM_PROJECT_ID is optional when the service account JSON has project_id.

# Runtime env for APNs monolith workers:
# PUSH_APNS_ENABLED=true
# PUSH_APNS_TOPIC=com.example.app
# PUSH_APNS_PRIVATE_KEY_PATH=/var/run/secrets/apns-auth-key.p8

Use the queue backend for push fanout. Direct synchronous provider delivery is only suitable for tests and can hide production latency.

Channel push rules are top-level entries. They trigger the existing push pipeline after matching realtime publishes:

[[push_rules]]
enabled = true
channel_pattern = "notifications:*"
event_filter = ["agent-complete"]
rate_limit_per_second = 100

[push_rules.payload_mapping]
title_field = "title"
body_field = "body"
template_data_field = "data"
include_remaining_fields = true

Presence

[presence]
max_members_per_channel = 100
max_member_size_in_kb = 2
update_rate_limit_per_member_per_second = 10
ungraceful_timeout_seconds = 0

ungraceful_timeout_seconds = 0 preserves legacy immediate member_removed behavior. Set it to 15 for agent presence channels that should tolerate short abnormal reconnects without leave/enter flaps.

Webhooks

[webhooks]
enabled = true
batching_enabled = true
max_batch_size = 50
flush_interval_ms = 500
timeout_ms = 5000

Webhook consumers must validate signatures with the raw request body. Configure retry behavior and dead-letter visibility before relying on webhooks for workflows.

Rate limits

[rate_limiter]
enabled = true
driver = "redis"

[rate_limiter.limits]
connection_per_ip = 50
events_per_second = 100

Keep limits close to product intent. A collaboration app, trading dashboard, and push-heavy mobile app need different ceilings.

Environment variables

Use environment variables for secrets and deployment-specific settings:

SOCKUDO_DEFAULT_APP_ID=app-id
SOCKUDO_DEFAULT_APP_KEY=app-key
SOCKUDO_DEFAULT_APP_SECRET=app-secret
REDIS_URL=redis://redis:6379/0
PUSH_FCM_PROJECT_ID=project-id
PUSH_FCM_PROVIDER_TOKEN=oauth2-access-token

Avoid putting app secrets, encryption master keys, webhook secrets, and push provider credentials in committed config files.

Every runtime environment override is listed in the environment variable reference.

On this page