Configuration reference¶

Every key of jezero.toml, generated from the configuration models. A complete, commented example lives in jezero.example.toml.

Jezero reads the file given with --config, else $JEZERO_CONFIG, else ./jezero.toml, and loads a .env file next to it (variables already set win). Relative paths are relative to the file. Unknown keys are an error, so a typo never goes unnoticed.

Note

Secrets never go in this file. Keys ending in _env hold the name of an environment variable, and an option that looks like a secret without _env is rejected.

Table
`[storage]`	Where the library lives.
`[search]`	How results are ranked and how many come back.
`[summarizer]`	The model that writes each item.
`[server]`	The MCP server and its HTTP routes.
`[[clients]]`	Who may read (and upload). One block per key.
`[[connectors]]`	Where items come from. One block per source.
`[inbox]`	Where uploaded sessions land.
`[projects]`	How a session's folder maps to a project.
`[redaction]`	What is removed before anything is stored.
`[watchdog]`	When `jezero health` raises an alarm.

storage¶

Where the library lives.

[storage]

Key	Type	Default	Meaning
`path`	path	`"data/jezero.db"`	The SQLite file (created by `jezero init`). Relative to the config file.
`tokenizer`	string	`"trigram remove_diacritics 1"`	FTS5 tokenizer. The default matches plurals as substrings and ignores accents.

search¶

How results are ranked and how many come back.

[search]

Key	Type	Default	Meaning
`default_limit`	integer (≥ 1, ≤ 100)	`10`	Results returned when a caller does not ask for a number.
`max_limit`	integer (≥ 1, ≤ 500)	`50`	Most results any single call may return, whatever it asks for.
`candidate_pool`	integer (≥ 10, ≤ 5000)	`200`	How many BM25 candidates are re-ranked by recency.
`recency_half_life_days`	number (> 0)	`90.0`	Age at which the recency boost of an item is half that of a new one.
`recency_weight`	number (≥ 0.0, ≤ 1.0)	`0.3`	0 = pure BM25, 1 = relevance fully scaled by recency.

summarizer¶

The model that writes each item.

[summarizer]

Key	Type	Default	Meaning
`provider`	`"anthropic"` \| `"openai_compatible"`	`"anthropic"`	API dialect: Anthropic Messages, or any OpenAI-compatible chat endpoint.
`base_url`	string	`"https://api.anthropic.com"`	Endpoint of the provider (for example a local OpenAI-compatible server).
`model`	string (optional)	none	Use a cheap, fast model. Required before running any connector.
`api_key_env`	string	`"JEZERO_SUMMARIZER_API_KEY"`	Environment variable holding the provider's API key.
`max_concurrency`	integer (≥ 1, ≤ 64)	`4`	Summaries requested in parallel.
`timeout_seconds`	number (> 0)	`120.0`	Time allowed for one summary request.
`max_input_chars`	integer (≥ 1000)	`60000`	Longer inputs are split into parts, each summarised on its own.
`known_projects`	list of string	empty	Project slugs the summarizer should prefer when tagging items.
`output_language`	string (optional)	none	Write every summary in this language (e.g. "Spanish") so one query matches all items. Default: the document's main language.

server¶

The MCP server and its HTTP routes.

[server]

Key	Type	Default	Meaning
`host`	string	`"127.0.0.1"`	Address to listen on. Keep loopback and publish through a reverse proxy.
`port`	integer (≥ 1, ≤ 65535)	`8765`	Port to listen on.
`path`	string	`"/mcp"`	URL path of the MCP endpoint.
`public_url`	string (optional)	none	External URL when served behind a reverse proxy, e.g. https://library.example.org/mcp
`allowed_hosts`	list of string	empty	Extra Host header values accepted (DNS-rebinding protection). Derived from public_url.
`require_auth`	boolean	`true`	Ask every request for a client key. May be turned off only on a loopback host.
`client_bundle`	path (optional)	`"dist/jezero-client.tar.gz"`	Plugin bundle offered at /client/jezero-client.tar.gz (public code, no auth).

clients¶

Who may read (and upload). One block per key.

An agent (or person) allowed to query the library over MCP.

[[clients]]

Key	Type	Default	Meaning
`name`	string	required	Unique name: lowercase letters, digits, - and _ (a device's name for plugins).
`token_env`	string (optional)	none	Environment variable holding the client's bearer token.
`token_sha256`	string (optional)	none	Or: the SHA-256 hex digest of the token (`jezero new-token` prints one).
`sources`	list of string	`['*']`	Source names (glob patterns) this client may read. Default: everything.
`upload`	boolean	`false`	May deliver raw session files to the inbox (a device running the Jezero plugins).

connectors¶

Where items come from. One block per source.

One configured source. type selects the implementation, name identifies it.

[[connectors]]

Key	Type	Default	Meaning
`name`	string	required	Unique name, which becomes the `source` of its items (`agent-codex-laptop`).
`type`	string	required	Connector type: see the connectors reference.
`enabled`	boolean	`true`	Disabled connectors keep their cursor and are skipped by `jezero run`.
`interval_minutes`	integer (≥ 1)	`15`	How often `jezero run --due` runs it.
`project`	string (optional)	none	Default project for items from this source, when the connector cannot infer one.
`trust`	`"own"` \| `"external"` (optional)	none	`own` for your agents' work; `external` for text written by others (mail). Default: the connector type's own default (`external` for gmail, `own` otherwise).
`options`	table of any	empty	Type-specific settings (paths, filters). Secrets go through *_env keys only.

inbox¶

Where uploaded sessions land.

Where devices deliver raw session files (see jezero.inbox).

[inbox]

Key	Type	Default	Meaning
`dir`	path	`"data/inbox"`	Folder for uploads, one subfolder per device. Relative to the config file.
`max_mb`	number (> 0)	`64.0`	Largest accepted file, after decompression.

projects¶

How a session's folder maps to a project.

How a session's folder maps to a project (see jezero.projects).

[projects]

Key	Type	Default	Meaning
`paths`	table of string	empty	Folder -> project; `~` matches any home folder. Wins over everything else.
`roots`	list of string (optional)	none	Folder names that hold projects; default: projects, code, dev, src, repos, ...
`aliases`	table of string	empty	Rename a detected project (`"atlas-wt" = "atlas"`).
`git`	boolean	`true`	Use the git repository's name when the folder exists on this computer.

redaction¶

What is removed before anything is stored.

[redaction]

Key	Type	Default	Meaning
`enabled`	boolean	`true`	Redact known secret formats (keys, tokens, passwords) before storing anything.
`extra_patterns`	list of string	empty	Additional regular expressions to redact before summarising and indexing.

watchdog¶

When jezero health raises an alarm.

[watchdog]

Key	Type	Default	Meaning
`max_silence_hours`	number (> 0)	`24.0`	Alert when an enabled connector has not succeeded for this long.
`alert_webhook_env`	string (optional)	none	Env var holding a webhook URL that receives a JSON alert.
`realert_hours`	number (> 0)	`12.0`	Repeat an alert for the same connector at most this often.
`heartbeat_url_env`	string (optional)	none	Env var holding a push URL (for example an Uptime Kuma push monitor). Every health check calls it with status=up or status=down, so silence itself becomes an alert.