Configuration reference

Stream Trace is configured entirely through environment variables prefixed ST_. ST_NATS_URL is required for the normal API/indexer runtime; the isolated ./stream-trace migrate command needs only database and logging settings. When authentication is enabled (the default), normal runtime also needs a JWT key ring.

NATS

Variable	Default	Description
ST_NATS_URL	(required)	One validated NATS connection URL. Multiple cluster seed URLs are not supported as a first-class beta configuration.
ST_NATS_MAX_RECONNECTS	-1	Max reconnect attempts; -1 = unlimited.
ST_NATS_RECONNECT_WAIT_SEC	2	Seconds between reconnect attempts (1–300).

See Connecting to NATS for URL formats and auth.

Database

Variable	Default	Description
ST_DB_TYPE	sqlite	sqlite or postgres.
ST_DB_URL	file:stream-trace.db?_foreign_keys=on&_journal_mode=WAL&_busy_timeout=5000	Connection string / DSN. Required for postgres.
ST_DB_AUTO_MIGRATE	true	Apply pending migrations during normal startup. The explicit ./stream-trace migrate command always runs migrations.
ST_DB_READ_MAX_OPEN_CONNS	10	Read pool max open connections.
ST_DB_READ_MAX_IDLE_CONNS	5	Read pool max idle connections.
ST_DB_READ_CONN_MAX_LIFETIME_SEC	300	Read connection max lifetime.
ST_DB_READ_CONN_MAX_IDLE_TIME_SEC	300	Read connection max idle time.
ST_DB_WRITE_MAX_OPEN_CONNS	5	Write pool max open connections.
ST_DB_WRITE_MAX_IDLE_CONNS	5	Write pool max idle connections.
ST_DB_WRITE_CONN_MAX_LIFETIME_SEC	300	Write connection max lifetime.
ST_DB_WRITE_CONN_MAX_IDLE_TIME_SEC	300	Write connection max idle time.

See Databases.

Runtime & server

Variable	Default	Description
ST_RUNTIME_MODE	api,indexer	Comma-separated roles: api, indexer. SQLite requires both together; Postgres can split them.
ST_PORT	4000	HTTP listen port.
ST_SHUTDOWN_TIMEOUT_SEC	20	Graceful shutdown timeout (1–300).
ST_LOG_LEVEL	info	debug, info, warn, error.
ST_LOG_FORMAT	json	text (colored, local) or json.

CORS

Variable	Default	Description
ST_CORS_ALLOW_ORIGINS	*	Comma-separated origins, or *.
ST_CORS_ALLOW_METHODS	GET,POST,PUT,DELETE,OPTIONS	Allowed methods.
ST_CORS_ALLOW_HEADERS	*	Allowed headers, or *.
ST_CORS_ALLOW_CREDENTIALS	false	Include credentials in CORS responses.

Authentication (local)

Variable	Default	Description
ST_AUTH_ENABLED	true	Master switch for authentication.
ST_AUTH_LOCAL_ENABLED	true	Enable email/password login & signup.
ST_AUTH_BREAK_GLASS_LOCAL_ENABLED	false	Emergency local instance_admin login when local auth is otherwise off.
ST_AUTH_SIGNUP_MODE	disabled	enabled, disabled, or invite_only.
ST_AUTH_ALLOWED_EMAIL_DOMAINS	(empty)	Comma-separated allow-list; empty = allow all.
ST_AUTH_ACCESS_TOKEN_TTL	15m	Access-token lifetime.
ST_AUTH_REFRESH_TOKEN_TTL	720h	Refresh-token lifetime.
ST_AUTH_COOKIE_SECURE	true	Secure flag on auth cookies (set false only for local HTTP).
ST_AUTH_COOKIE_SAME_SITE	lax	lax, strict, or none.
ST_AUTH_JWT_ACTIVE_KEY_ID	(empty)	ID of the active signing key. Required when auth is enabled.
ST_AUTH_JWT_KEYS	(empty)	JSON array of {id, secret} keys (secret ≥ 32 bytes). Required when auth is enabled.
ST_AUTH_BOOTSTRAP_ADMIN_EMAIL	(empty)	Create the first admin at startup.
ST_AUTH_BOOTSTRAP_ADMIN_PASSWORD	(empty)	Password for the bootstrap admin.
ST_AUTH_BOOTSTRAP_ADMIN_DISPLAY_NAME	(empty)	Display name for the bootstrap admin.

Email / SMTP

Variable	Default	Description
ST_AUTH_EMAIL_DELIVERY	disabled	disabled, log, or smtp.
ST_AUTH_EMAIL_FROM	(empty)	Sender address (required for smtp).
ST_AUTH_SMTP_HOST	(empty)	SMTP host (required for smtp).
ST_AUTH_SMTP_PORT	587	SMTP port.
ST_AUTH_SMTP_USERNAME	(empty)	SMTP username.
ST_AUTH_SMTP_PASSWORD	(empty)	SMTP password.
ST_AUTH_SMTP_TLS	starttls	starttls, tls, or none.

OIDC & provisioning

Variable	Default	Description
ST_AUTH_OIDC_PROVIDERS_JSON	[]	JSON array of OIDC providers. See SSO / OIDC.
ST_AUTH_PROVISIONED_TEAMS_JSON	[]	Teams to create at startup.
ST_AUTH_PROVISIONED_ROLE_MAPPINGS_JSON	[]	OIDC group → role mappings.
ST_AUTH_STREAM_OWNERSHIP_JSON	[]	Stream → team ownership assignments.

Message indexer

Variable	Default	Description
ST_INDEXER_ENABLED	true	Enable background message indexing.
ST_INDEXER_STREAM_EXCLUDE	_*	Comma-separated stream-name patterns to skip in addition to automatically excluded WorkQueuePolicy streams. Review InterestPolicy retention before indexing.
ST_INDEXER_RETENTION_HOURS	168	Reserved configuration. Automatic cleanup of indexed rows is not implemented; size and back up the database accordingly.
ST_INDEXER_BATCH_SIZE	100	Messages per batch (1–10000).
ST_INDEXER_DISCOVERY_INTERVAL_MS	60000	New-stream discovery interval.
ST_INDEXER_IDLE_POLL_START_MS	2000	Initial idle poll interval.
ST_INDEXER_IDLE_POLL_MAX_MS	30000	Max idle poll interval.
ST_INDEXER_MAX_CONCURRENT_STREAMS	4	Streams indexed in parallel (1–256).
ST_INDEXER_LEASE_DURATION_MS	30000	Coordination lease TTL.
ST_INDEXER_MAX_BATCHES_PER_RUN	10	Batches per discovery cycle.

Payload index (search)

Off by default. See Searching messages.

Variable	Default	Description
ST_PAYLOAD_INDEXING_ENABLED	false	Enable full-text / JSON path scalar search.
ST_PAYLOAD_INDEX_MAX_BYTES	32768	Max payload size to index.
ST_PAYLOAD_INDEX_MAX_JSON_BYTES	32768	Max JSON bytes indexed.
ST_PAYLOAD_INDEX_MAX_JSON_DEPTH	12	Max JSON nesting depth.
ST_PAYLOAD_INDEX_MAX_JSON_SCALARS	512	Max scalar values extracted per message.
ST_PAYLOAD_INDEX_MAX_JSON_PATH_LENGTH	512	Max indexed JSON path length.
ST_PAYLOAD_INDEX_MAX_SCALAR_TEXT_BYTES	1024	Max bytes per indexed scalar.
ST_PAYLOAD_INDEX_STREAM_EXCLUDE	(empty)	Stream patterns to exclude from payload indexing.
ST_PAYLOAD_INDEX_QUERY_MAX_LENGTH	512	Max payload query length.

Dead letter queue

Variable	Default	Description
ST_DLQ_ADVISORY_STREAM	STREAM_TRACE_DLQ	Name of the advisory capture stream.
ST_DLQ_ADVISORY_STREAM_AUTO_CREATE	false	Let Stream Trace create the advisory stream if missing.

See Dead letter queue.

Traces

Variable	Default	Description
ST_TRACE_ID_HEADERS	Nats-Trace-Id,X-Trace-Id	Message headers to read trace IDs from.
ST_TRACE_OBSERVATION_RETENTION_MS	604800000 (7d)	Trace observation retention.

Throughput sampling

Variable	Default	Description
ST_THROUGHPUT_SAMPLE_INTERVAL_MS	30000	Sampling interval.
ST_THROUGHPUT_SAMPLE_RETENTION_MS	1209600000 (14d)	Sample retention.
ST_THROUGHPUT_LEASE_DURATION_MS	60000	Collector lease TTL.
ST_THROUGHPUT_MAX_CONCURRENT_STREAMS	4	Streams sampled in parallel.
ST_THROUGHPUT_TREND_TOLERANCE_PERCENT	10	Trend-change tolerance.

Consumer backlog signals

Variable	Default	Description
ST_CONSUMER_BACKLOG_PENDING_THRESHOLD	5	Pending count that flags a backlog signal.
ST_CONSUMER_BACKLOG_STALE_AFTER_MS	60000	Age after which a backlog is considered stale.