Configuration - GenesisDB Documentation

GenesisDB is configured with environment variables. A .env file in the working directory is read if present.

Server

Variable	Default	Meaning
`GENESISDB_AUTH_TOKEN`	required	Administrator token, at least 32 bytes
`GENESISDB_WRITE_TOKEN`	disabled	Read and commit
`GENESISDB_READ_TOKEN`	disabled	Read only
`GENESISDB_HOST`	`127.0.0.1`	Bind address, the container image uses `0.0.0.0`
`GENESISDB_PORT`	`8080`	API port
`GENESISDB_TLS_CERT_FILE`, `GENESISDB_TLS_KEY_FILE`	disabled	TLS certificate and key, supply both
`GENESISDB_DATA_DIR`	`data`	Data directory, owned exclusively by one process
`GENESISDB_TZ`	system	Time zone of event timestamps
`GENESISDB_LOG_LEVEL`	`info`	`debug`, `info`, `warn` or `error`

Limits

All limits are off by default. A request that hits one fails explicitly, it is never truncated.

Variable	Default	Meaning
`GENESISDB_MAX_REQUEST_BYTES`	`0` (unbounded)	Request body size, answers `413`
`GENESISDB_MAX_RESTORE_BYTES`	`0` (unbounded)	Restore body size, answers `413`
`GENESISDB_MAX_READ_EVENTS`	`0` (unbounded)	Selected events per request, answers `422`
`GENESISDB_MAX_READ_BYTES`	`0` (unbounded)	Selected bytes per request, answers `422`
`GENESISDB_MAX_CONCURRENT_REQUESTS`	`0` (unbounded)	Active requests including subscriptions, answers `429`
`GENESISDB_REQUEST_TIMEOUT_SECONDS`	`0` (none)	Deadline for non-streaming requests, answers `408`

Cache and storage

Variable	Default	Meaning
`GENESISDB_MEMCACHE`	`true`	Set to `false` to disable the event cache
`GENESISDB_MEMCACHE_SIZE`	`10000`	Cached events, an entry count, not bytes
`GENESISDB_STORAGE_FORMAT`	`auto`	`auto` migrates a 1.x directory on start (back it up first, the backup is mandatory), `keep` leaves it as is for inspection

Metrics

Variable	Default	Meaning
`GENESISDB_METRICS` or `GENESISDB_PROMETHEUS_METRICS`	`false`	Enable Prometheus and OpenTelemetry metrics
`GENESISDB_METRICS_PORT`	`2112`	Separate Prometheus listener
`GENESISDB_LEGACY_METRICS`	`true`	Also expose the historical `eventstore_*` metric names

OTLP export additionally needs OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT. The standard OTEL_* variables apply. Metrics endpoints are unauthenticated, keep them on a trusted network. Subjects are never exported as labels, and at most 256 event types get their own label value.

MCP

Variable	Default	Meaning
`GENESISDB_MCP`	`false`	Serve the MCP endpoint for AI agents at `/mcp` on the API port

Commands

bash

genesisdb                                   # start the server
genesisdb version                           # print the version
genesisdb convert --data-dir <dir>          # migrate a stopped 1.x directory offline, back it up first
genesisdb convert --data-dir <dir> --dry-run