Skip to main content
reliquary-tc reads one JSON config file, passed as the first CLI argument or via RELIQUARY_TC_CONFIG. Zero-config also works: pass a vault folder instead and the server boots a single vault with id main and every default below. Inspect any config with reliquary-tc config show <path> (secrets redacted) or reliquary-tc config validate <path>. This page is the complete option surface, derived from ServerConfigSchema (packages/shared/src/config.schema.ts). Fields marked (optional) may be omitted entirely; every other block is fully defaulted, so any subset of this document is a valid config.

The full shape (all defaults shown)

The block below is generated by bun run docgen:render — it is ServerConfigSchema.parse() run against nothing but a vaults entry, so it is literally what the server materialises. Do not hand-edit between the markers; change the schema and regenerate. It was hand-maintained until this generator existed, by which point five entire defaulted blocks had gone missing from it.
Every value above is the schema’s own default, materialised by parsing a config containing nothing but the vaults entry — so this is literally what the server fills in for you. vaults[] is the only block with no default: it needs a real path. Keys that are optional rather than defaulted — toolVisibility and the vaults[] sub-blocks (acl, bridges, plugins, commands, memory, workspace) — are absent here on purpose. They are documented in the sections below and in the Configuration Reference table.

Vault entries (vaults[], min 1)

Excluded files

reliquary-tc honors the Excluded files list Obsidian keeps for each vault (Settings → Files & links → Excluded files, stored as userIgnoreFilters in <vault>/.obsidian/app.json), and you can add entries for a vault with vaults[].index.excludePaths. The two lists are merged. Nothing needs configuring when the vault already has an Excluded files list. Pattern dialect. The Obsidian help site does not state how an entry is matched, so this mirrors the Obsidian 1.13.7 app source (updateUserIgnoreFilters and isUserIgnored): What an excluded note is. Obsidian treats an excluded file as hidden from Search and the Graph view but still a file in the vault: links to it resolve, and it still appears in backlinks and outgoing links. reliquary-tc does the same. Dot-folders (.obsidian, .git, .trash) are a different mechanism: they are not loaded at all, so notes inside them are not even link targets. egress.excludePaths is also separate: it only withholds text from model providers and leaves the note searchable. Live reload. The server watches .obsidian/app.json. When the effective list changes, the vault is reconciled: newly excluded notes are de-indexed (their open contradiction rows are dismissed with a reason), and notes no longer excluded are indexed again. A malformed app.json keeps the last good list. Without the file watcher (watch.enabled: false), the new list applies on the next index_vault or server start. doctor --probe prints the effective list, how many notes it excludes, and any invalid entry.

auth

mode: "jwt" requires jwtSecret or a JWKS — the config refuses to load otherwise. Fail-closed interlock: the config is rejected when transports.http.enabled is true on a non-loopback host while auth.mode is none. An unauthenticated server never binds a routable address.

Bundled authorization server (auth.as)

Opt-in. Everything under auth.as is off while auth.as.enabled is false (the default), and the bearer paths do not change. When enabled it needs auth.mode: jwt, auth.resource and auth.as.issuer (it is refused under none and oidc). It serves the discovery document, the authorize, consent, token and revoke routes, client registration by metadata document and optionally by RFC 7591 (dynamicRegistration, off by default) and the operator login; see the authorization server. A minimal example: the bundled server with Dynamic Client Registration turned off and one pre-registered client.
The config file is JSON. The loader reads no other format. Cross-checks refused at load: auth.authorizationServers, when set, must list auth.as.issuer first (it defaults to [issuer]); auth.jwksUri may not point at this server’s own /.well-known/jwks.json; clientIds must be unique. Hand-minted tokens keep their rules: enabling the AS does not bind an aud to them (a hand-minted HS256 token without aud is still accepted); only auth.audience, or an explicit auth.authorizationServers list with auth.resource, does that. The tokens the AS issues are always checked against auth.resource. A configured auth.jwks or auth.jwksFile that contains the public key of the server’s own as key stops the server at boot, naming the kid: a JWKS key is verified under the hand-minted-token rules, which would let a token signed by the as key skip the stricter as rules. A remote auth.jwksUri cannot be checked at boot, so keep the authorization server’s key out of any key set you publish. reliquary-tc doctor has an auth.as check. See the bundled authorization server.

acl (root, inherited by every vault without its own)

Path globs: write /, a backslash is a separator

Every config field that holds a vault path pattern is normalised once, when the config loads: each backslash becomes / and repeated separators collapse. So Private\** (the natural spelling on Windows, written "Private\\**" inside JSON) is exactly Private/**, and notes//drafts is notes/drafts. A vault path can never contain a backslash, so there is nothing to escape in operator input: a backslash is always a separator, and \* is not a way to match a literal *. The fields this covers: acl.rules[].glob, acl.readPaths / writePaths / deletePaths (also under a vault’s own acl), egress.excludePaths, and vaults[].index.excludePaths (path-prefix entries only; an entry written /regex/ is a regular expression and is left exactly as written). acl.rules[].glob and the three *Paths whitelists are stricter than the rest: an ACL pattern is matched against a path relative to the vault root (Private/x.md), so one that is still anchored at a root after normalising can never match. Config load refuses it, with the vault-relative spelling in the error, rather than guessing:
  • a leading separator (/Private/**, \Private\**), a drive letter (C:\notes\**), a UNC prefix (\\server\share), or a leading ./: write Private/**, notes/**;
  • a trailing separator (notes\private\): that is the exact path notes/private/, not the folder. Write notes/private/**.
  • a . or .. path segment anywhere (../Private/**, Private/./**, Private/../**): the server rejects .. and drops . in every path it checks, so a rule written that way never matches the folder it names. Spell the folder itself (Private/**). Names that merely contain dots (.obsidian/**, a..b/**, v1.2/**) are fine;
  • a control character (NUL, tab, newline, DEL and the other C0/C1 controls), which no ACL pattern may contain. NUL in particular is the matcher’s own internal marker for ** and would over-match.
Refusing instead of stripping is deliberate: an acl.rules entry that never matched left its extra scopes unenforced, and stripping the marker from a whitelist entry would turn one that granted nothing into a grant. Upgrade note: a config that carries such a pattern now fails to start (serve, doctor and the other commands print the field and the fix). Those rules never worked, so the fix is to rewrite them vault-relative. The egress and index fields keep stripping a leading separator and widening a trailing one to the folder. Before this, a backslash glob compiled to a pattern no vault path could match. For a whitelist (readPaths and friends) that failed closed, which is safe. For a restriction (egress.excludePaths, acl.rules, index.excludePaths) it failed open: the exclusion silently excluded nothing. reliquary-tc doctor runs config.path-globs, which warns about any configured glob that matches no file in its vault (a typo, the wrong case, a renamed folder). A dead restriction is reported as one that protects nothing; a dead whitelist entry as one that grants nothing.

embeddings

retrieval and experiential

retrieval.densify — graph densification (experimental)

Derived edges added to the vault_edges graph beyond authored wikilinks, so a multi-hop query can reach bridge notes that were never explicitly linked. All off/conservative by default and unmeasured — a prior virtual-hop attempt sat at an 80% bridge-recall ceiling, and the champion figure it was judged against has since been withdrawn as unreproducible (see docs/EVALUATION.md), so densification ships dark behind these flags pending a multi-hop golden-set A/B that establishes its own control, exactly like retrieval.sparse / retrieval.colbert. Derived edges are rebuildable cache and are never written back into notes as wikilinks; hub tags and hub nodes emit no edges. llmEdges is produced out-of-band by reliquary-tc densify-llm (below), not by indexing; tagEdges and knnEdges build inline during index_vault when set.

transports

Governance, safety, and surface shaping

resources (note resources)

The reliquary-tc://<vault>/<path> note resources (resources/read, resources/list and the read_resources tool) read notes in the vault their URI names.

bootstrap (session-bootstrap routing)

Powers session_bootstrap: triages a session’s opening message to lightweight / standard / deep and preloads the matching context notes. The routing table is a judgment value you supply — it never ships baked in.

throttle

Per-scope-class token buckets: read 600/min (burst 100), write 60/20, delete 60/20, bulk 10/3, execute 5/1, admin 5/1 — each {perMinute, burst} — plus maxConcurrentWritesPerVault (16) and a master enabled (true). A trip returns rate_limit with retry_after_ms.

observability

Background schedulers

plur (optional)

Global (not per-vault) read-proxy for a plur engram store: endpoint + apiKey (or the env vars below) for HTTP, or command (argv prefix, e.g. ["plur"]) to shell the local plur CLI — command takes precedence. apiPrefix (""), timeoutMs (5000). Absent endpoint/command → the plur tools degrade to plugin_missing with no network call.

Plain-http endpoints (plainHttpHosts)

experiential.citationInfer.judge and wikiJudge (both with provider: typesafe) send a bearer key and vault-derived text to baseUrl. That URL must be https://, a loopback host, or an http:// URL whose exact hostname is listed in the block’s plainHttpHosts:
A listed host is still checked every time a request is sent. The host is resolved once, and the request is refused, with nothing sent, unless every address it resolves to is loopback, private (RFC 1918: 10/8, 172.16/12, 192.168/16) or IPv6 unique-local (fc00::/7); a listed host may also resolve to a Tailscale tailnet address (100.64.0.0/10, see Tailnet hosts below). Link-local addresses are never allowed, because 169.254.169.254 is the cloud metadata service. The connection then goes to the address that was checked, with the original Host header, so a second DNS answer cannot redirect it. A redirect from the host is refused rather than followed. Entries are exact hostnames (case-insensitive, internationalized names are converted to punycode); wildcards, ports and paths are config errors. A numeric form such as http://0x08080808/ or http://[::ffff:8.8.8.8]/ is the address it spells, so it needs to be private to be sent at all. reliquary-tc doctor lists each plain-http host with the addresses it resolves to and warns about any that are not private. Every http:// request, loopback included, is sent directly: HTTP_PROXY, http_proxy and ALL_PROXY are not applied to it, so a proxy in the environment never receives the key or the vault text. A loopback name such as localhost must resolve only to loopback addresses. https:// requests do honour those variables; through a proxy that is a CONNECT tunnel, so the proxy sees the host and port but cannot read the body. allowPlainHttp: true is deprecated and is removed in the next major release. Until then it means “this baseUrl’s own host is listed”, and it no longer waives the private-address check: a host that resolves to a public address is refused. doctor and server_health (deprecations) warn while it is set. Replace it with plainHttpHosts: ["<the host in baseUrl>"]. The two judge blocks keep their own plainHttpHosts because they refuse an unlisted host when the config loads. Every other provider URL uses the one root list below.

Plain-http provider endpoints (network.plainHttpHosts)

The same policy covers every other outbound provider client: gateway.baseUrl (or RELIQUARY_TC_GATEWAY_URL), embeddings.baseUrl, embeddings.modelTier.dense.baseUrl / .full.baseUrl, reranker.baseUrl, plur.endpoint and each vault’s restApiUrl. They share one top-level list, so a host is named once however many providers use it (a per-provider list would only repeat the same name; the judge blocks are the one exception, above):
What a plain http:// provider URL does: A refusal fails the request with the host and the offending address in the error (never the key, a path or a query) and is not retried. Every plain-http request, loopback included, connects straight to the address that was checked, with the original Host header; a redirect is refused. reliquary-tc doctor lists every plaintext provider host with its resolved address and a status (allowed, allowed (listed tailnet/CGNAT), deprecated-unlisted or refused). server_health (deprecations) gives the same advice, resolved once at startup: only a host that resolves solely to private addresses is told to be listed, a tailnet/CGNAT host is told to be listed only if it is a tailnet peer, and a public or metadata host is told it is refused and to use https://. The entries name hosts, addresses and vault ids, so only a caller that may read every vault sees them; anyone else gets one generic line with the count. On Cave, embeddings.baseUrl and gateway.baseUrl are http://litellm:4000, a Docker bridge address in 172.16.0.0/12. They keep working unchanged; add network: { plainHttpHosts: ["litellm"] } to silence the warning before the next major release.

Tailnet hosts (100.64.0.0/10)

Tailscale gives every peer an address in 100.64.0.0/10. That range is not private in general: an ISP’s carrier-grade NAT space is shared and not encrypted. So it is admitted only for a host you list (network.plainHttpHosts, or a judge block’s own list), and every address the host resolves to must still be loopback, private or in that range. An unlisted host that resolves into it is refused with no deprecation path. Tailscale traffic is WireGuard-encrypted; listing a host is your explicit statement that it is a tailnet peer, so list only tailnet hosts. Link-local and the cloud metadata address stay refused.

JWT-mode key set (auth.jwksUri)

auth.jwksUri follows the same list. It must be https:// on a public host (connected to the address that was validated, never resolved twice), unless the host is loopback (no entry) or listed in network.plainHttpHosts, which admits http:// and loopback, RFC 1918, fc00::/7 and (listed) tailnet addresses. An unlisted host that resolves only to private addresses still works for one more release with a deprecation; add it here to silence it. A public host over plain http://, and link-local or cloud metadata addresses, are refused even when listed. See Remote key set. Not covered, by design: Pensieve (pensieve.baseUrl) is an inbound, key-less GET whose documented target is a tailnet address (100.64.0.0/10), the Readwise and OIDC clients are https-only, and the optional local embedder and reranker download their model files from fixed https hosts.

Environment variables (complete)

Secrets (restApiKey, embedding API keys, the JWT secret, gateway/plur tokens) resolve config-then-env and never appear in logs, error details, or audit rows.

Applying config changes

Config is read at server start; live/headless mode is also resolved once at start. reload_vault re-validates the on-disk file but the server keeps its startup config — restart the server (or your MCP client) to apply changes. Adding or removing a vault always requires a restart; destructive changes (path, embeddings provider/model/dimensions, cacheDir) additionally need reset_vault_cache or a fresh cacheDir.

Hardened deployment profile

The defaults target a trusted, single-user local process (stdio, auth.mode: "none", acl.readOnly: false, strictReadDefault: false, writes.requireCas: false). Governed by default is not the same as least-privilege by default: for a shared, multi-caller, or long-lived deployment, start from the hardened example and tighten from there. The server prints a one-line security posture summary at startup, plus a warning when the permissive local defaults are active, so the running profile is always visible. A committed least-privilege starting point is examples/config.hardened.json:
It fails reads closed on unlisted paths (strictReadDefault), whitelists read/write paths and forbids deletes (least privilege), requires prev_hash on overwrites (writes.requireCas, no stale-hash clobbering), and captures snapshots for restore_note. For a shared or HTTP deployment, additionally set transports.http.enabled: true and auth.mode: "jwt", supplying the secret via RELIQUARY_TC_JWT_SECRET (never commit it). A non-loopback host with auth.mode: "none" is refused by the fail-closed interlock. Consider acl.readOnly: true initially, then open specific write paths.

See also

  • Inference gateway setup — the generative tier.
  • Embedding model migration — changing models safely.
  • The CLI: reliquary-tc help lists the full offline command family (setup, serve, config show|validate, plugin install, cluster, activation-recompute, prefetch, reflect, metrics, gaps, forget, version); each command takes the same config path. setup is the odd one out — it takes no config path at all (it WRITES one); see First Run.