Environment Variables

Curated cheat-sheet of the most-used RELATA_* variables. For the full subsystem-by-subsystem list (~166 variables), see docs/src/end-users/environment-variables.md in the main repo.

— means the feature is disabled / unset by default.

Profile & bind

Variable	Default	Description
`RELATA_PROFILE`	`lite`	Deployment profile: `lite` (dev/CI), `server` (single-node prod), `cluster` (multi-node, alpha).
`RELATA_PORT`	`9090`	HTTP API port.
`RELATA_HTTP_BIND`	`0.0.0.0`	HTTP bind address. Use `127.0.0.1` to stay loopback-only.
`RELATA_DOMAIN_PROFILE`	`enterprise`	Domain overlay: `enterprise` \| `lea` \| `finint` \| `security` \| `custom`.

Auth

Variable	Default	Description
`RELATA_BEARER_TOKEN`	—	Expected `Authorization: Bearer` token. Unset = dev mode (no auth, pgwire disabled).
`RELATA_ADMIN_TOKEN`	—	Secondary admin-only token for management operations.
`RELATA_PLAINTEXT_OK`	—	Set `true` to allow HTTP (no TLS) on `server`/`cluster` profiles.
`RELATA_AIRGAP`	—	Set `true` to block all outbound network calls (no LLM, no telemetry).
`RELATA_PURPOSE_MODE`	`strict`	`strict` (only registered purposes) or `open` (any non-empty string — dev).
`RELATA_PURPOSES`	—	Comma-separated registered purposes (`analytics,audit,compliance,...`).

Rate limits (set high to disable)

Variable	Default	Description
`RELATA_RATE_LIMIT_RPS`	profile-dependent	Requests/sec per principal.
`RELATA_RATE_LIMIT_AUTH_FAIL_RPS`	profile-dependent	Auth-failure rate cap (`0` is treated as `1`; use `99999` to disable).

For air-gapped / demo / testing:


RELATA_RATE_LIMIT_AUTH_FAIL_RPS=99999 RELATA_RATE_LIMIT_RPS=99999 relata serve
# or just:
RELATA_AIRGAP=true relata serve

Storage / durability

Variable	Default	Description
`RELATA_DATA_DIR`	`./data/relata`	Root for config files and WAL state.
`RELATA_LOCAL_DATA_DIR`	—	Explicit local object-store path (no MinIO needed).
`AWS_ENDPOINT_URL`	—	S3-compatible object-store endpoint; when set, S3 takes priority over local disk.
`RELATA_IN_MEMORY`	—	Set `true` for an in-memory store (data lost on restart — never in prod).
`RELATA_WAL_SYNC`	`true`	`fsync` the WAL on every append (durable). `false` trades durability for throughput.

Caps (RAM / cache / scaling walls)

Variable	Default	Description
`RELATA_STORE_MAX_RAM_MB`	`1024` (server/cluster), unbounded (lite)	Row-store RAM budget before spill-to-disk. Cap is byte-aware — small datasets never spill.
`RELATA_DISKANN_MAX_RESIDENT`	`0` (unbounded)	Soft cap on RAM-resident vectors before the index warns to shard/restart.
`RELATA_MV_MAX_ROWS`	`1000000`	Cap on a materialized view’s cached rows before eviction to base-table fallback (`0` = unbounded).
`RELATA_VECTOR_COLD_RESIDENT_MAX`	`100000`	Soft cap on RAM-resident vectors in an IVF cold bucket’s staging area before spill to `PagedAnnIndex`.
`RELATA_CACHE_CAPACITY_BYTES`	—	Tiered cache size budget.

Cold load / restart

Variable	Default	Description
`RELATA_FLUSH_SEGMENT_MAX_ROWS`	`250000`	Max rows per flushed Parquet segment. A larger flush delta is split into `ceil(delta/N)` segments. `0` = unbounded/legacy single-segment.
`RELATA_LAZY_RESTART`	`false`	When `true`, startup loads the manifest catalog only — O(manifest), not O(rows).
`RELATA_HYDRATE_RECENT_SEGMENTS`	`0`	With lazy restart on, hydrate only the newest N segments into RAM at startup.

Media worker

Variable	Default	Description
`RELATA_EMBED_BATCH_SIZE`	`32`	Texts batched into one GPU/CPU `embed()` call per drain cycle.
`RELATA_EMBED_CONCURRENCY`	`4`	Number of concurrent drain-worker tasks.
`RELATA_SEARCH_PRESET`	`balanced`	BM25/FTS query preset — `strict` / `balanced` / `lenient`. Controls edit-distance fuzzy expansion.

SmartIngest (identity auto-detection)

Variable	Default	Description
`RELATA_DETECT_PACKS`	`network,contact,crypto`	SmartIngest identity auto-detection packs. Opt-in: `financial,payment,social,transport,device,ics`. Or `all` / `none`.

S3 door

Variable	Default	Description
`RELATA_S3_ENABLE`	`false`	Enable the S3-compatible door.
`RELATA_S3_PORT`	`9191`	S3 door port.
`RELATA_S3_BIND`	`0.0.0.0`	S3 door bind address.
`RELATA_S3_SECRET_KEY`	= bearer token	SigV4 secret. When set, the door requires verified SigV4.
`RELATA_S3_ALLOW_PLAINTEXT`	`false`	Dev/legacy opt-out — accept plaintext bearer / unsigned auth.
`RELATA_S3_BLOB_THRESHOLD_MB`	`4`	Body size that spills out-of-row into the content-addressed blob store.
`RELATA_S3_BODY_LIMIT_MB`	`128`	Per-GET / per-PUT body cap.
`RELATA_S3_MULTIPART_LIMIT_MB`	`1024`	Total multipart upload cap.

Metrics / observability

Variable	Default	Description
`RELATA_LOG_FORMAT`	`pretty`	`json` \| `pretty`.
`RELATA_LOG_LEVEL`	`info`	Log level.
`RELATA_OTLP_ENDPOINT`	—	OTLP/HTTP traces endpoint. Unset = OpenTelemetry fully disabled.
`RELATA_OTLP_SAMPLE_RATIO`	`0.01`	Parent-based TraceID-ratio sampler.
`RELATA_METRICS_PUBLIC`	—	Set `true` to serve `/metrics` without a bearer token (Prometheus scraper behind network-layer auth).

Cluster (experimental)

Variable	Default	Description
`RELATA_NODE_ID`	auto	Node identifier for cluster membership.
`RELATA_PEERS`	—	Comma-separated peer addresses.
`RELATA_ROLE`	—	Node role: `coordinator` / `reader` / `writer` / `indexer`.

ACL grants (strict mode)

Variable	Default	Description
`RELATA_ACL_GRANT`	—	Grant read/write on a custom type in strict mode, e.g. `AgentTask:read+write`.