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.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 asuserIgnoreFilters 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.
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./: writePrivate/**,notes/**; - a trailing separator (
notes\private\): that is the exact pathnotes/private/, not the folder. Writenotes/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.
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:
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):
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:
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 helplists 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.setupis the odd one out — it takes no config path at all (it WRITES one); see First Run.