Settings

Applies to OML v0.6.x · Status: Generated · Last verified 2026-11-06

A server reads one TOML file, oml.toml by default (--config <path>), and the environment. The environment wins over the file, and the file wins over the defaults. An environment name is OML_, then the dotted key in capitals with __ between the parts: search.rerank.depth becomes OML_SEARCH__RERANK__DEPTH.

Generated by scripts/gen_settings_reference.py; edit the source, not this page. Keys come from crates/bins/oml-server-lead/src/lib.rs; words from scripts/settings_notes.yaml.

A value that does not parse stops the server at start and names the key. Per-tenant policy, such as a workarea's review rules, is not a setting: an administrator changes it with the CLI.

Server settings

Key	Environment variable	Default	What it does
postgres.url	OML_POSTGRES__URL	none (required)	The connection string of the serving role, a Postgres role that owns nothing and holds only the privileges the server's statements need.
postgres.owner_url	OML_POSTGRES__OWNER_URL	none (required)	The connection string of the owner role. The server runs its migrations under it at start and serves under postgres.url. A start without it is refused as postgres.role_split.
server.listen	OML_SERVER__LISTEN	127.0.0.1:8080	The address of the API listener.
kms.adapter	OML_KMS__ADAPTER	the file keyring	Which key store wraps each memory's encryption key. This build has one, file, the keyring file; any other value stops the server at start.
kms.keyring_path	OML_KMS__KEYRING_PATH	oml-keyring	The keyring file, for the file adapter. Back it up with the database; a database restored without it cannot be read.
oauth.issuer	OML_OAUTH__ISSUER	unset (connections off)	The public origin of the server, https with no path and no trailing slash, such as https://memory.example.com. It turns on OAuth connections for claude.ai and the web pages. Set it to the address people reach, not the address the process binds behind its proxy.
server.trusted_proxies	OML_SERVER__TRUSTED_PROXIES	empty (no proxy trusted)	Addresses and CIDR ranges of reverse proxies, a TOML array in the file and comma-separated in the environment. Only a request from a listed peer has its client address read from X-Forwarded-For. Behind a proxy on the same host, set loopback.
server.metrics_listen	OML_SERVER__METRICS_LISTEN	unset (no metrics listener)	The address of a second listener that serves GET /metrics and nothing else, unauthenticated. Bind it where only the scraper reaches. The API listener never serves /metrics.
server.otlp_endpoint	OML_SERVER__OTLP_ENDPOINT	unset (no trace export)	The http or https base URL of an OpenTelemetry collector. The server posts spans to <endpoint>/v1/traces over OTLP with protobuf and sends no authentication header.
web.google.client_id	OML_WEB__GOOGLE__CLIENT_ID	unset (Google sign-in off)	The OAuth client ID of your Google application. Register the redirect URI <oauth.issuer>/web/callback/google.
web.google.client_secret	OML_WEB__GOOGLE__CLIENT_SECRET	unset	The matching secret. The server never logs it. Set both or neither.
web.github.client_id	OML_WEB__GITHUB__CLIENT_ID	unset (GitHub sign-in off)	The client ID of your GitHub OAuth app. Its callback is <oauth.issuer>/web/callback/github.
web.github.client_secret	OML_WEB__GITHUB__CLIENT_SECRET	unset	The matching secret. Set both or neither. The web pages need oauth.issuer and at least one provider.
brief.max_tokens	OML_BRIEF__MAX_TOKENS	400	The token budget a workarea's brief is cut to when an agent reads the workarea. The first member that does not fit ends the brief.
signup.mode	OML_SIGNUP__MODE	allowlist: the sign-in allowlist, unchanged	open lets a person whose provider-verified email no entry holds create an account after accepting the terms: a drawn user, a private root, <user>-web and <user>-review (ADR-0068 d1). open requires oauth.issuer, a sign-in provider (web.google.* or web.github.*) and every signup.* setting except per_ip_per_hour. A missing one, a tenant id that does not parse, or an issuer that is not a live admin key of that tenant stops the process at start, naming the setting.
signup.tenant	OML_SIGNUP__TENANT	unset	The tenant id sign-ups land in. Every person of that tenant is under the quota.* limits.
signup.issuer	OML_SIGNUP__ISSUER	unset	The name of an admin key of the sign-up tenant that adds each entry and issues its session keys.
signup.terms_version	OML_SIGNUP__TERMS_VERSION	unset	The terms version a person accepts, recorded on their entry and in web.signed_up. Changing it makes an open terms page refuse with terms_version.
signup.terms_url	OML_SIGNUP__TERMS_URL	unset	The terms page the terms checkbox links.
signup.privacy_url	OML_SIGNUP__PRIVACY_URL	unset	The privacy page the terms checkbox links.
signup.per_ip_per_hour	OML_SIGNUP__PER_IP_PER_HOUR	5, the operator's choice, unmeasured (#164)	New accounts from one client address in a rolling hour, counted per process; an IPv6 address counts by its /64 and an IPv4 address by itself. The address is the request line's, so behind a proxy set server.trusted_proxies, or every sign-up shares one bucket (oml doctor warns).
quota.memories	OML_QUOTA__MEMORIES	1000, the operator's choice, unmeasured (#164)	Live memories in a person's root, counted as chains, so a new version of a memory is not a new memory. Past it, limit.quota. An admin overrides one person's limit on /web/admin/users, journaled as web.quota_set. A value above 1,000,000 stops the start.
quota.keys	OML_QUOTA__KEYS	5, the operator's choice, unmeasured (#164)	Live agent keys of a person. Past it, limit.quota.
quota.connections	OML_QUOTA__CONNECTIONS	5, the operator's choice, unmeasured (#164)	Open connections of a person. Past it, limit.quota.
quota.requests_per_minute	OML_QUOTA__REQUESTS_PER_MINUTE	120, the operator's choice, unmeasured (#164)	Requests per key per UTC minute, counted per process. Past it, limit.rate.
search.enabled	OML_SEARCH__ENABLED	keyword-any, bm25, bm25-postings	The search pipelines the server offers, a TOML array in the file and comma-separated in the environment. A pipeline that is not listed answers search.unavailable.
search.default	OML_SEARCH__DEFAULT	bm25-postings	The pipeline a recall uses when neither the request nor the tenant names one. It must be in search.enabled.
search.rerank.model	OML_SEARCH__RERANK__MODEL	ms-marco-MiniLM-L6-v2	The cross-encoder the reranking pipeline loads. This build pins ms-marco-MiniLM-L6-v2 and ms-marco-MiniLM-L4-v2, both Apache-2.0.
search.rerank.model_dir	OML_SEARCH__RERANK__MODEL_DIR	<state>/models/<model>	An absolute directory holding config.json, tokenizer.json and model.safetensors. The server checks each file against a pinned SHA-256 and stops at start on a mismatch.
search.rerank.fetch	OML_SEARCH__RERANK__FETCH	false	true lets the server download missing model files at start from the pinned revision on Hugging Face and check each digest. false never uses the network.
search.timings	OML_SEARCH__TIMINGS	false	true lets a recall ask for each stage's milliseconds. Off by default because stage times over rows a key cannot read reveal how many there are.
search.rerank.depth	OML_SEARCH__RERANK__DEPTH	10	How many of the best candidates the cross-encoder reorders, 1 to 100.
search.rerank.floor	OML_SEARCH__RERANK__FLOOR	off	A relevance between 0 and 1 below which a reranked hit is withheld. A recall whose candidates all fall below it answers no hit and reports how many it withheld.
search.rerank.max_concurrent	OML_SEARCH__RERANK__MAX_CONCURRENT	2	Reranks that run at once. A recall that waits past its deadline for a slot serves the unreranked order and says why.
search.rerank.timeout_ms	OML_SEARCH__RERANK__TIMEOUT_MS	1000	The deadline of one rerank in milliseconds, waiting for a slot included. Past it the recall serves the unreranked order.
search.rerank.threads	OML_SEARCH__RERANK__THREADS	2	The threads of the reranker's own pool, shared by every rerank.
search.rerank.max_tokens	OML_SEARCH__RERANK__MAX_TOKENS	256	The longest query-and-passage pair the model reads, 64 to 512 tokens.
search.sparse.model_dir	OML_SEARCH__SPARSE__MODEL_DIR	<state>/models/opensearch-neural-sparse-encoding-doc-v3-distill	An absolute directory holding the sparse model's config.json, tokenizer.json, model.safetensors and idf.json. Read only when search.enabled names a sparse pipeline.
search.sparse.fetch	OML_SEARCH__SPARSE__FETCH	false	true lets the server download missing sparse-model files at start and check each digest.
search.sparse.threads	OML_SEARCH__SPARSE__THREADS	2	The threads of the sparse encoder's own pool. It writes each version's postings after the write commits, off the commit path.

Lake writer

The oml-lakewriter binary takes these as flags or environment variables. See run the lake writer.

Variable	Default	What it does
OML_LAKE_URL	none	The root of the lake, such as file:///var/lib/oml/lake or an object-store URL. Also the --lake flag.
OML_LAKE_DATABASE_URL	none	The connection string of the reader role the lake writer drains the outbox through.
OML_LAKE_OWNER_URL	none	The owner-role connection string, for the command that prepares the lake roles.
OML_LAKE_KEK_FILE	none	The key-encryption key file. The writer checks its permissions and age and warns when it is not given.
OML_LAKE_METRICS_ADDR	127.0.0.1:9466	The address of the lake writer's metrics listener.

Client and plugin

The CLI, the SDKs, the hooks and the agent kit read these. The Claude Code plugin reads its url and api_key options instead.

Variable	What it does
OML_URL	The server's URL, without /mcp. Set with OML_API_KEY or not at all; a source that sets one alone is refused.
OML_API_KEY	The API key. Prefer it, or the credentials file oml login writes, to the --api-key flag, because argv is visible to other processes.
OML_CLI_CREDENTIALS	The path of the credentials file, for tests and for keeping several servers apart.
OML_SESSION_CONTEXT	off stops the session-start hook from loading the workarea's memory into a session. It takes on or off.
OML_SESSION_CONTEXT_MAX_TOKENS	The token budget of the session-start recall, an integer from 1 up.
OML_FAILURE_RECALL	1 makes the plugin recall memories matching the error words after a failed command. Off by default.
OML_TURN_RECALL	1 makes the plugin recall on every prompt, within its budget. Off by default.
OML_METRICS_URL	The lead's metrics listener, so that oml doctor can read rerank skips, scan findings and recall telemetry.