obsidian-tc reads one JSON config file, passed as the first CLI argument or via OBSIDIAN_TC_CONFIG. You can also pass a vault folder directly for zero-config startup (a single vault main with all defaults). Secrets stay off disk via environment variables.

The schema is ServerConfigSchema, exported from @the-40-thieves/obsidian-tc-shared (packages/shared/src/config.schema.ts). Inspect the effective config any time with obsidian-tc config show <path> (secrets redacted) or validate with obsidian-tc config validate <path>.

{
  "vaults": [
    { "id": "main", "path": "/Users/me/vault", "restApiKey": "<local-rest-api-key>" }
  ]
}

One vault, default none auth (loopback only), local Ollama embeddings. restApiKey is only needed for plugin-bridge tools — pure filesystem/search use works without it.

"experiential": {
  "logRetrievals": true,
  "captureEpisodes": true,
  "captureContent": true,
  "activationRerank": false
}

• logRetrievals — append serve-path retrieval events to the quarantined experiential store (local-only telemetry feeding activation recompute and citation inference).
• captureEpisodes — auto-capture agent tool-call outcomes as work episodes (the action axis).
• captureContent — additionally store secret-scanned call arguments (the content axis). On under trusted-local; securityProfile: "hardened" turns it off, as does setting it false yourself. Arguments are secret-scanned and size-capped before storage.
• activationRerank — apply cached ACT-R activation in the graph rerank (dark until its A/B wins).

{
  "id": "main",
  "path": "/Users/me/vault",
  "mode": "auto",
  "restApiUrl": "http://127.0.0.1:27124",
  "restApiKey": "<key from Local REST API plugin>",
  "memory": { "folder": "90-memory" },
  "workspace": { "traceFolder": ".obsidian-tc/traces" },
  "commands": { "enabled": false, "allowlist": [] },
  "bridges": { "timeoutMs": 5000, "probeTimeoutMs": 500, "ocrTimeoutMs": 30000, "templaterTimeoutMs": 30000 },
  "plugins": { "forceEnabled": ["dataview"], "probeSkip": false },
  "acl": { "readOnly": true }
}

mode is live | headless | auto (auto probes the Local REST API once at startup). memory.folder is where composite-context surfaces read/write memory notes (_next-session.md, reflections). commands is the deny-by-default command-execution gate (explicit enable + allowlist + HITL). The optional per-vault acl overrides the root ACL for this vault; omit it to inherit.

HS256 (shared secret):

"auth": { "mode": "jwt", "jwtSecret": "<>= 32 chars, prefer OBSIDIAN_TC_JWT_SECRET env>" }

Asymmetric (RS256 / ES256 / EdDSA) via a JWKS — inline jwks or a jwksFile loaded at boot; algorithms is an allowlist, key rotation is kid-based:

"auth": { "mode": "jwt", "jwksFile": "/etc/obsidian-tc/jwks.json", "algorithms": ["RS256", "EdDSA"] }

mode is none | jwt; in jwt mode supply either jwtSecret or a JWKS. A fail-closed interlock refuses to start when transports.http.enabled && auth.mode === "none" and the host is non-loopback. Optional OAuth 2.0 Protected Resource Metadata (RFC 9728) via auth.resource + auth.authorizationServers. Full model in Security and ACL.

"acl": {
  "readOnly": false,
  "defaultScopes": ["read:vault"],
  "rules": [{ "glob": "02-projects/**", "scopes": ["read:vault", "write:vault"] }],
  "readPaths": ["**"],
  "writePaths": ["02-projects/**", "01-daily/**"],
  "deletePaths": [],
  "strictReadDefault": false
}

readOnly: true is the kill switch. rules are last-match-wins. Omitting readPaths / writePaths / deletePaths leaves that op kind unrestricted; strictReadDefault: true makes an undefined readPaths fail closed on reads.

"embeddings": {
  "provider": "ollama",
  "model": "nomic-embed-text",
  "dimensions": 768,
  "chunkContext": true
}

provider is a name resolved against the provider registry at startup, not a closed enum — an unregistered name is a startup error listing every valid option the registry currently has registered, and the registry's contents grow over time. The built-in names today: ollama, openai, voyage, cohere, bge-m3, the generic openai-compatible, model-tier and the profile-gated module (bge-m3 targets a vLLM/TEI pooling server; model-tier splits dense and multi-vector retrieval across two services; openai-compatible serves anything OpenAI-shaped). None is privileged in code — ollama is only the schema default, and that default is deprecated. chunkContext (default true) embeds each chunk with its note title + heading breadcrumb — measured +0.223 nDCG; the first reconcile after enabling re-embeds in full. Further knobs (local-runner robustness + model-specific behavior): timeoutMs (120000), batchSize (512), maxBatchTokens (2048 — keeps a batch inside a local runner's context), concurrency (4), truncate (false — Matryoshka/MRL truncation for wider models), queryPrefix/documentPrefix ("" — instruct prefixes for models that require them; a document-prefix change needs a fresh cacheDir).

"transports": {
  "stdio": true,
  "http": { "enabled": false, "host": "127.0.0.1", "port": 8765 }
}

A headless deploy with both transports on (docker run -d, a compose service without stdin_open: true, a systemd unit) has stdin backed by /dev/null, which hits stdio EOF immediately — closing only the stdio transport, not the process, as long as http.enabled is true. Set stdio: false for a headless HTTP-only deploy to skip the notice and the stdio transport entirely.

reflect synthesis, knowledge_challenge, the sleep-time plane, the episode evaluator's judge layer, and preference extraction route through one optional OpenAI-compatible endpoint by role — the engine requests model names extract, synthesize, judge. Wire it with the two env vars above; the recommended shape is a self-hosted LiteLLM container (digest-pinned, loopback-only, zero keys for an all-local Ollama-backed policy) whose config maps the three role aliases to real models. Swapping a role to a hosted model is a yaml edit + container restart — obsidian-tc never changes, and every derived note records the resolved provider:model. Absence is a supported state: reflect degrades to recall with available: false and the plane idles. Full recipe: the docs-site page configuration/inference-gateway.md.

Adding or removing a vault requires a restart. reload_vault re-reads and validates the on-disk config but the server keeps its startup config until restart — config changes (including restApiUrl/restApiKey and live/headless mode, which is resolved once at boot) take effect on the next server start. Per-vault isolation (separate SQLite DBs, traces, embeddings, ACL) is detailed in Architecture.

Every key, type, default, and required flag — generated from the Zod schema. Do not hand-edit between the markers.