Configuration

Precedence

Suchi first resolves boot configuration, last wins:

defaults < config file < process environment

Environment values therefore beat file values. This is useful for container overrides where the file lives in an image layer and the environment comes from the run command. A small, explicit set of administrator-managed values can also be changed live through the web UI. For those values only, the effective chain is:

defaults < stored web setting < config file < process environment

Configuration is resolved per field. A stored value fills an otherwise unconfigured field, while a config-file or process-environment value pins that field and wins. Stored changes to unpinned fields apply without a restart. File and environment changes are read at process start. See Live database settings for the complete stored list. Command flags, where available, override environment values for that command. Mailbox rows and the Email intake or member Mailboxes screen are authoritative for account-specific IMAP configuration. Filing systems are introduced by taxonomy import, never a boot flag or writable enable setting. Tree, Inbox, mode and last-import provenance belong to each system. User/group directories, roles/capabilities, OCR/LLM settings, OAuth client registration, backup and server configuration remain instance-wide.

Config file (optional)

Recommended format: TOML. Explicit typing and no indentation surprises. HUML is the documented alternative. Format is picked from file extension:

Extension	Parser
`.toml`	recommended - `github.com/BurntSushi/toml`
`.huml`	HUML - human-oriented structured data

Search paths

The first file found wins:

$SUCHI_CONFIG — explicit path override (highest priority)
$XDG_CONFIG_HOME/suchi/config.<ext>
$HOME/.config/suchi/config.<ext>
/etc/suchi/config.<ext>
./suchi.<ext> (cwd)

Within each directory, Suchi’s documented formats are probed in the order toml → huml. Setting SUCHI_CONFIG is an explicit instruction: a missing or unreadable path, or a path to a directory, stops startup with an error. When SUCHI_CONFIG is unset, finding no file in the normal search paths is valid and built-in defaults plus environment values are used.

File shape

Keys mirror env var names in lower_snake_case. PUBLIC_URL becomes public_url; BODY_LIMIT becomes body_limit. Nested tables flatten with underscores:

admin_email = "[email protected]"

[oidc]
issuer_url = "https://id.example.com"
client_id = "suchi"

is equivalent to:

[email protected]
OIDC_ISSUER_URL=https://id.example.com
OIDC_CLIENT_ID=suchi

admin_email stays top-level because its environment name is ADMIN_EMAIL; putting it inside [oidc] would produce the unused OIDC_ADMIN_EMAIL key. Arrays become CSV strings: ocr_languages = ["eng", "deu"] matches OCR_LANGUAGES=eng,deu. Full samples:

config.example.toml (recommended)
config.example.huml

SUCHI_CONFIG opts the operator into a specific file and bypasses the search order. Environment values still override that file. Direct secrets and their _FILE forms are treated as one setting, so a direct secret in the environment overrides a file-side secret-file path.

Environment variables — boot configuration

Required

Env var	Purpose
`PUBLIC_URL`	External origin for cookies, OIDC callbacks, mobile pairing and Network share links. The main listener also serves Public links reached through this origin. Must be an absolute `http` or `https` origin with a host and no path, userinfo, query, or fragment. Suchi does not support subpath hosting.

Storage & runtime

Env var	Default	Purpose
`DATA_DIR`	`/data`	Root of `blobs/`, `suchi.db` + WAL, `backups/`, `config.toml`, `staging/`. Created 0750; startup and `suchi doctor` warn when other accounts can reach it.
`LISTEN_ADDR`	`:8000`	HTTP listener. In `SUCHI_DEV=1`, the wildcard default is narrowed to `127.0.0.1:8000`; public/wildcard listeners are refused. Physical-device LAN testing must name one private IP and set `SUCHI_DEV_ALLOW_LAN=1`.
`SHARE_LISTEN_ADDR`	(unset)	Optional share-only listener. Set together with `SHARE_PUBLIC_URL`. This socket exposes only Public recipient routes; all UI, API, health, metrics, asset and extension routes return 404. In `SUCHI_DEV=1`, it must name `localhost` or a loopback IP, never a wildcard or LAN address.
`SHARE_PUBLIC_URL`	(unset)	Internet-facing origin used to create Public links and render their instance identity. Set together with `SHARE_LISTEN_ADDR`; HTTPS is required outside development mode. The address itself is never returned by `/api/whoami`.
`LOG_LEVEL`	`info`	`debug` / `info` / `warn` / `error`.
`SUCHI_PPROF`	(unset)	Set to `1` to expose admin-authenticated `/debug/pprof/*` endpoints. Disable after profiling.
`TRUSTED_PROXY_CIDRS`	(unset)	Comma-separated proxy networks allowed to supply `X-Forwarded-For` identities for login, share-link, and demo rate limits. The direct TCP peer must match; suchi then walks the header right-to-left and selects the first untrusted address. Leave unset when connecting directly. Configure the proxy to append or replace this header.
`BODY_LIMIT`	`500M`	Request-body and fs-watch file-size cap. `0` disables the cap. Accepts `K`/`M`/`G` suffixes or raw bytes. Read at startup; an unchanged watched file skipped for exceeding the cap is retried after Suchi restarts with the limit raised above its size or disabled.
`BACKUP_INTERVAL`	`24h`	`VACUUM INTO` snapshot cadence as a Go duration such as `30m`, `24h`, or `168h`. Writes `$DATA_DIR/backups/suchi-<ts>.db`; `0` disables.
`BACKUP_KEEP`	`7`	Retention — after each snapshot, prune all-but-the-latest N. `0` keeps everything (documented; not the default).
`AUDIT_RETENTION_DAYS`	`20`	Sliding window over ordinary `audit_events`. Non-retained rows older than this are pruned on the backup tick; retained identity-security rows are excluded and require deliberate operator deletion. Range `0–100`; `0` disables pruning. Directly bounds the ordinary storage growth path behind `GET /api/events/`.
`OCR_LANGUAGES`	`eng`	Comma-separated Tesseract language codes handed to every OCR call. The matching packs must be installed separately; see Adding OCR languages. Each enabled pack adds processing work and memory use. Detected document languages are stored on `documents.languages`; they do not change this operator setting. Common Indian scripts include `hin`, `kan`, `tam`, `tel`, `ben`, `mar`, `guj`, `pan`, `mal`, and `urd`.
`DEVICE_OCR_MIN_CONFIDENCE`	`0.65`	Finite `[0,1]` threshold for promoting submitted mobile OCR to provisional searchable content. Confidence/language/receipt-time provenance is retained below the threshold, but the submitted text is discarded. Native PDF text remains authoritative; accepted device text avoids duplicate OCR only for image-only PDFs.
`PDF_MAX_CONTENT_BYTES`	`8M`	Cap on pdftotext output length written to `documents.content`. Truncation is silent + logged at Warn — the doc still lands, FTS still indexes what fit.
`ANYDOC_MAX_CONTENT_BYTES`	`32M`	Cap on Markdown extracted from EPUB and office documents.
`DJVU_MAX_CONTENT_BYTES`	`32M`	Cap on `djvutxt` output length. Same reasoning as EPUB.
`OCR_ENGINE`	`auto`	Scanned-PDF OCR engine. `auto` picks `tesseract` when the tessocr binaries (`pdftoppm` + `tesseract`) are on PATH, else `ocrmypdf`. Explicit values force one engine. `tesseract` is ~4× smaller in the image but produces no searchable-PDF archive.
`SCAN_BLANK_REMOVAL`	`auto`	`auto` (default) → detect and strip blank pages from the working copy before OCR. `off` → skip. The CAS original is untouched either way.
`SCAN_BLANK_WHITENESS_THRESHOLD`	`0.995`	Fraction of mean pixel intensity above which a page is considered blank. Range `(0.0, 1.0]`. Lower it (e.g. `0.98`) if your scanner leaves grey background; raise it (`0.999`) to only strip truly white pages.
`SCAN_ASN_MODE`	`off`	`assign` leaves unlabelled PDFs alone and accepts exactly one valid ASN QR label anywhere in a labelled PDF; `split` leaves unlabelled PDFs alone, but a labelled PDF must start with an ASN and each later ASN-labelled page starts a retained child; `off` ignores ASN labels. Invalid or conflicting plans stop before mutable ingest hooks. See barcode-assisted physical filing.
`SCAN_ASN_PREFIX`	`ASN`	Case-sensitive label prefix. Grammar: `[A-Za-z][A-Za-z0-9._:-]*`; the suffix must be a positive base-10 integer no greater than `9007199254740991`. Used only when `SCAN_ASN_MODE` is `assign` or `split`.
`SCAN_SPLIT_ENABLED`	`off`	`on` enables the legacy disposable-separator workflow. Separator pages are removed; ASN label pages are retained. Enabling both marker families rejects a scan that contains both.
`SCAN_SPLIT_TOKEN`	`SUCHI-SPLIT`	Legacy separator barcode payload. Case-sensitive after surrounding whitespace is removed. When ASN mode is enabled, this token must not begin with `SCAN_ASN_PREFIX`.
`SCAN_SPLIT_DPI`	`150`	Rasterization DPI shared by legacy separator and ASN detection. Range `[72, 600]`; calibrate against the smallest printed code and the scanner’s output.
`INGEST_PASSWORDS_FILE`	(unset)	Optional path to a newline-separated list of candidate PDF passwords tried before an encrypted PDF is parked in `encryption_state='encrypted'`. Blank lines and `#` comments are skipped. Reloaded per-doc so operators can append passwords without restart. Chmod 600 recommended — the file holds secrets.
`DECRYPT_KEY_FILE`	`$DATA_DIR/.decrypt-key`	Path to the AES-256-GCM key that seals remembered PDF passwords, mailbox credentials and OAuth caches, and LLM API keys saved through Archive Configuration. Auto-generated 0600 on first boot. Losing this file makes every corresponding ciphertext unusable — back up `$DATA_DIR` wholesale, not just `suchi.db`.
`PRE_CONSUME_SCRIPT`	(unset)	Optional path to an operator-defined executable that runs on every doc before any built-in ingest logic. See preconsume for the contract (argv, env vars, stdout JSON envelope).
`SUCHI_UI_DISABLED`	(unset)	Set to `1` or `true` to turn off the built-in browser UI at boot. When enabled, `/`, `/app/` (Svelte SPA), `/login`, `/bootstrap`, `/preview/{id}`, `/download/{id}`, `/assets/` don’t register — only `/api/*`, `/healthz`, `/readyz`, `/metrics` are served. Blob access for headless callers keeps working via the `/api/documents/{id}/{preview,download}` mirrors (see api). For deployments where a self-hosted SPA fronts `/api/` externally. Auth (Token/Bearer/OIDC) is unchanged.
`SUCHI_DEMO_MODE`	(unset)	Set to `1` or `true` to enable public-showcase behaviour: SPA renders a persistent “resets daily” banner, `GET /api/demo/mode` reports `enabled=true`. Consumed by the demo instance deploy — no normal deployment should set it.
`SUCHI_DEMO_GLOBAL_RPS`	`5`	Per-IP request rate for demo session mint and upgrade endpoints; burst is twice this value. `0` disables the cap. Range `0–10000`.
`SUCHI_DEMO_SCRATCH_TTL_MINUTES`	`30`	When demo mode is on, bounds how long a per-visitor scratch user (email `visitor-*@demo.local`) survives before the reset ticker sweeps them and their uploads. Ticker cadence is `ceil(TTL/2)` minutes. Range `1–1440`.

Administrators can change ASN mode, prefix, and rasterization DPI under Settings > Archive configuration > Advanced > Scan processing. Saves affect future processing jobs immediately. An explicitly configured SCAN_ASN_MODE, SCAN_ASN_PREFIX, or SCAN_SPLIT_DPI remains authoritative and appears read-only instead of silently accepting an ineffective edit. Removing an override reveals the previously stored value. Legacy disposable-separator enablement and token remain boot configuration.

Ingest pipeline timeouts

Every ingest stage runs inside core/sandbox with a hard per-invocation deadline. Defaults are tuned for small home-servers processing typical 1–20 MB PDFs; larger files (multi-hundred-page reports, big scan sets) routinely need higher caps. Each knob accepts any Go duration string — 60s, 2m, 1h30m. An invalid value logs a warning and falls back to the default so a typo doesn’t kill ingest.

Env var	Default	Stage
`SUCHI_QPDF_TIMEOUT`	`30s`	`qpdf --remove-restrictions --decrypt` normalization. Linear in page count; bump for PDFs with thousands of pages.
`SUCHI_PDFINSPECTOR_TIMEOUT`	`30s`	`pdftotext` text-native probe. Roughly 5–10 ms per page; bump for very long documents.
`SUCHI_ANYDOC_TIMEOUT`	`30s`	Office / image conversion via the `anydoc` binary. Bump for large `.docx` / `.xlsx` / archive-like inputs.
`SUCHI_OCRMYPDF_TIMEOUT`	`10m`	Full-chain `ocrmypdf` OCR. Scales with page count × DPI × language count.
`SUCHI_TESSERACT_TIMEOUT`	`10m`	Native `pdftoppm` → `tesseract` OCR chain. Same scaling as `ocrmypdf`.
`SUCHI_PAGEANALYZE_TIMEOUT`	`60s`	`pdftoppm` rasterization for blank-page detection. Bump when `SCAN_BLANK_REMOVAL=auto` runs on very long PDFs.

Set these when the job dispatcher parks a doc in state='dead' with a ... timeout after 30s last_error. Retries are capped at 5 by MaxAttempts, so a permanently-slow stage burns ~5 × timeout of wall clock before the doc dead-letters — raising the cap once beats the retry churn.

Ingest pipeline max-sizes

The user-facing content-extraction caps (PDF_MAX_CONTENT_BYTES, ANYDOC_MAX_CONTENT_BYTES, DJVU_MAX_CONTENT_BYTES above) bound what gets written to documents.content. The knobs here bound sandbox-level outputs — the intermediate PDFs and shell payloads. Same failure mode as the timeouts (typo warns + falls back). Byte suffixes K/M/G are base-2; bare numbers are raw bytes.

Env var	Default	Stage
`SUCHI_QPDF_MAX_SIZE`	`100M`	qpdf’s normalized output cap. Very large legitimate PDFs (multi-hundred-MB scan books) need this bumped or qpdf.Normalize errors before pdf-inspector sees the file.
`SUCHI_OCRMYPDF_MAX_ARCHIVE`	`200M`	OCRmyPDF’s searchable-PDF output cap. High-DPI OCR grows the archive relative to the input; if OCR runs but the archive is truncated, bump this.
`SUCHI_EMAIL_MAX_ATTACH`	`25M`	email-ingest per-attachment cap. Attachments over this are skipped (with a log line); the parent email doc still lands.
`SUCHI_PRECONSUME_TIMEOUT`	`5m`	Wall-clock deadline for a `PRE_CONSUME_SCRIPT` invocation.
`SUCHI_PRECONSUME_MAX_STDOUT`	`1M`	Preconsume’s stdout JSON envelope size. Bump if the envelope carries a lot of metadata.
`SUCHI_PRECONSUME_MAX_OUTPUT`	`200M`	Preconsume’s `SUCHI_OUTPUT` produced-file cap (the modified doc bytes).

TLS

If a reverse proxy terminates TLS (recommended), leave these unset. A SHARE_PUBLIC_URL can therefore be HTTPS while its proxy target is loopback HTTP. For proxy-less installs, set both:

Env var	Purpose
`TLS_CERT_FILE`	Cert file (PEM), used by every configured listener.
`TLS_KEY_FILE`	Key file (PEM), used by every configured listener.

See Public sharing for isolated Tailscale Funnel and Cloudflare Tunnel examples.

Local auth

No config needed. On first boot with no admin user, suchi prints a one-time setup token to the log at WARN. POST it to /setup with an email + password to create the admin.

Dev mode

Suchi runs in exactly one of three modes. Dev, demo, and production are mutually exclusive by design — no half-blends, no cross-cutting overrides, one login codepath.

Mode	Gate	First user	Login endpoints
developer	`SUCHI_DEV=1` on a local `PUBLIC_URL`	fixed `[email protected]` / `devdevdev` upsert	`POST /login`, `POST /api/token/`
demo	`SUCHI_DEMO_MODE=1`	anonymous visitor scratch users	`POST /api/demo/session`
production	neither flag set	`/setup` token → admin	`POST /login`, `POST /api/token/`, OIDC callback

Dev-mode’s only effect on the running system is guaranteeing the fixed admin row exists with a known password. Login uses the same endpoints production uses — no dev-only mint helper, nothing new to learn.

Env var	Default	Purpose
`SUCHI_DEV`	(unset)	Set to `1` to enable dev-mode. Auto-provisions the fixed `[email protected]` admin at boot; refuses to arm outside the guardrails below.
`SUCHI_DEV_ALLOW_LAN`	(unset)	Set to `1` only for physical-device testing, together with a `LISTEN_ADDR` naming the same private IP literal as `PUBLIC_URL`.

The auto-provisioned admin is fixed: email [email protected], password devdevdev. That’s not a placeholder — the plan is that you copy those two strings into /login (browser) or a POST /api/token/ curl. Rotating the credentials is not a dev-mode concern; if you need a different admin, use production mode. Boot log line to grep for:

level=WARN msg=main.dev.ready
  [email protected]
  password=devdevdev
  browser="open http://localhost:8000/login and sign in with the above"
  curl_token=curl -X POST http://localhost:8000/api/token/ -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"email":"[email protected]","password":"devdevdev"}'

Guardrails (all refusals log at main.dev.refused and exit non-zero):

Narrows the wildcard listener to loopback — the normal :8000 default becomes 127.0.0.1:8000 in dev mode. Explicit wildcard, public-IP, and hostname listeners are refused.
Requires a deliberate LAN opt-in — physical-device testing uses, for example, PUBLIC_URL=http://192.168.1.50:8000, LISTEN_ADDR=192.168.1.50:8000, and SUCHI_DEV_ALLOW_LAN=1. The two IP literals must match; the server never binds every interface in dev mode.
Refuses non-local PUBLIC_URL — allows localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1, bare hostnames without dots, and any *.local name. Anything else exits non-zero.
Refuses when OIDC_ISSUER_URL is set — single auth path only. Drop OIDC env vars for the dev iteration or use a separate DATA_DIR.
Refuses when SUCHI_DEMO_MODE=1 is set — dev and demo are mutually exclusive; both signalled together is a misconfiguration, not a valid combination.
Refuses if any admin other than [email protected] already exists — closes the accidental-prod lateral-takeover path. An operator with a legit [email protected] admin who happens to boot with SUCHI_DEV=1 plus a loopback URL would otherwise gain a second admin row carrying the public default credentials; instead the boot exits with localauth: refusing to arm dev-mode — 1 other admin(s) already exist.
Refuses to promote existing non-admin accounts — if a member row with email [email protected] exists, boot fails rather than silently making them admin.
Does not resurrect a disabled admin — a manually quarantined admin stays quarantined across dev restarts.
Refuses normal startup while the public dev admin is enabled — a data directory armed by SUCHI_DEV=1 cannot later be exposed by starting without dev mode. Disable [email protected] from another active administrator’s session first, or use a different data directory; disabling the account also invalidates its existing tokens.
Emits an audit event (dev_admin.provision) on every arm so post-hoc “was this row dev-created?” queries are easy.

Multi-account testing: dev-mode only touches the [email protected] row. Every other users-table row ([email protected], [email protected]) survives restarts untouched. Create additional users in Settings, or call POST /api/admin/users/ with the dev admin’s authenticated session cookie; admin routes do not accept API tokens. These users persist across dev-mode restarts as normal. Second admin rows will block the next SUCHI_DEV=1 boot — the right behaviour; demote the extra admin to a member before restarting dev mode. A normal boot also refuses this data directory until the public [email protected] account is disabled.

Dev-mode is a DX shortcut, not a production feature. The refusals above are the primary defence; the credentials are public and any network-reachable attacker who lands on a misconfigured prod box would gain admin. If you see main.dev.ready in a prod log, something is misconfigured.

OIDC

All-or-nothing group. Set the whole set or none:

Env var	Purpose
`OIDC_ISSUER_URL`	e.g. `https://id.example.com`
`OIDC_CLIENT_ID`	From your IdP.
`OIDC_CLIENT_SECRET` or `OIDC_CLIENT_SECRET_FILE`	The secret. `_FILE` variant reads from disk (docker/k8s secrets).
`ADMIN_EMAIL`	Required with OIDC. Role bootstrap only: the first matching browser-provisioned identity becomes admin when no administrator exists.

The provider must support discovery and return a signed ID token containing email and the boolean email_verified: true. Suchi requests openid email profile; configure the provider’s ID-token claim mapping accordingly. Claims available only from UserInfo are not sufficient. Missing, false, or non-boolean verification claims are rejected in both browser and bearer sign-in. A provider that cannot truthfully supply verified-email claims is not supported. Suchi stores the verified issuer and subject as the stable OIDC account key. Verified email remains a current provider-managed attribute, not the returning identity lookup. A browser callback with an unknown issuer/subject can create a new account only when its verified email is unused. It never adopts an existing email-matched row, and direct Bearer authentication never provisions or mutates an account. ADMIN_EMAIL does not locate, bind, or merge returning users. To bind a pre-existing unbound account after enabling OIDC, preserve one live browser session and choose Sync from identity provider. The forced provider login must return the same verified email before Suchi records the issuer/subject pair. Without that live session, ordinary login sees the occupied email as a conflict rather than risking an account takeover. Changing issuer, subject assignment, or verified-email ownership likewise fails closed; Suchi has no provider-migration or account-merge fallback. Only configure an issuer you trust to control email assignment, and never map arbitrary user-editable attributes to verified email. See the OIDC standard claims and identity limits. OIDC binding and account-email changes create retained security audit rows. Ordinary AUDIT_RETENTION_DAYS pruning does not remove them; an operator must deliberately delete them. When OIDC is configured, it owns interactive sign-in: anonymous browser entry points redirect to the provider, and local bootstrap/password-login endpoints are disabled. Existing Suchi sessions and scoped API tokens remain valid; API tokens are still the supported path for unattended clients. The health and readiness endpoints remain public for container orchestration. Both Authorization: Token <suchi-token> and Authorization: Bearer <suchi-token> remain supported: Suchi’s 64-lowercase-hex token shape goes to local token authentication, while other Bearer values must validate as OIDC ID tokens. Invalid credentials never fall back to a browser session.

Filesystem-watch ingest

Env var	Default	Purpose
`INGEST_FS_OWNER_EMAIL`	(unset = idle)	User that owns documents discovered in the source directory. Setting this activates the watcher.
`INGEST_FS_DIR`	`$DATA_DIR/staging` when owner is set	Existing readable source directory. Suchi never creates, moves, renames, deletes, or writes its files or sidecars.
`INGEST_FS_SYSTEM`	(unset = original system 1)	Existing target code, for example S02. Does not create a system. The owner must be active and able to enter it.
`INGEST_FS_RECURSIVE`	`on`	Reconcile ordinary files in subfolders. Set to `off` for top-level files only.

Archive Configuration exposes the directory, owner, target and effective recursion state. Saving a new directory, owner, or system validates all three and stores the resolved owner’s numeric user ID in one transaction. The directory must already exist. The supervisor then stops the old reconciler, scans the new source and starts polling it every five seconds. If runtime reload fails, Suchi restores the exact prior settings only when no newer save has replaced them. Reconciliation is deliberately polling-based: it keeps filesystem descriptors bounded instead of registering one kernel watch per subdirectory, recovers from network filesystems that do not forward local events, and cannot overflow an event queue. It processes one file at a time, never follows symbolic links, ignores hidden paths and the legacy top-level errors/ directory, skips special files and mounted filesystems beneath the source, and stops descent after 64 levels. A database checkpoint avoids rehashing unchanged files. Changed files and sidecars are reconsidered. An oversized file remains checkpointed while it exceeds the current BODY_LIMIT; restarting Suchi with the limit raised above its size or disabled retries the unchanged source. Successful checkpoints remain final across later limit changes. Transient failures retry after five minutes; deterministic sidecar/schema failures are blocked and retried hourly. Changing the sidecar retries that file at once, and creating, updating or deleting a custom-field definition under Metadata retries blocked files in that filing system. Blocked files are logged as fswatch.ingest_blocked and recorded as document.ingest.blocked archive events with the reason. Sidecars (<name>.json) remain read-only and apply metadata atomically. Failures stay at their source path and appear in logs and archive events; Suchi never moves them into the old errors/ directory or silently drops invalid fields. Intake rechecks owner entry; sidecars cannot redirect the configured system. Optional sidecar jd_system must agree. jd_address is informational, category-level, and potentially repeated; it never allocates, identifies, or routes a document. The API and UI continue to accept and display the owner’s current email, but the database setting is ingest.fs_watch_owner_id. Because the running watcher owns files by user ID, a successful local or OIDC email change neither rewrites this setting nor reloads the watcher. INGEST_FS_OWNER_EMAIL remains an address-shaped boot configuration boundary. Suchi resolves it to an active user ID before starting the watcher. An email change keeps the running watcher attached to that ID; update an old external email value before the next restart, when it will be resolved again. Import --owner-email is separate invocation-time input and must use the account’s current address on every future run.

Email ingest (IMAP polling)

Mailboxes live in the email_accounts table: one row per mailbox, immutable system, per-account owner, provider preset, auth mode (password or xoauth2), sealed secret at rest, per-account folder / poll interval, and typed intake policy. The supervisor picks up UI and API changes without a restart. Administrators configure accounts in Settings > Archive configuration > Email intake. Members with Manage mailboxes configure their own accounts in Settings > My account > Mailboxes. The equivalent API is /api/email-accounts; there is no boot-time single-mailbox seed. Mailbox lists and editing are restricted to the selected system as well as the existing owner/admin rules. Message and attachment documents inherit the mailbox system, including files-only intake. Microsoft OAuth flows capture actor/system; completion and the sealed_secret_b64 creation handoff cannot cross that boundary.

Env var	Purpose
`INGEST_IMAP_OAUTH_CLIENT_ID_MICROSOFT`	Optional Microsoft/Outlook public-client ID override. It wins over the config file and Suchi’s shipped registration. The ID is public and no client secret is used. Applied at process start.
`INGEST_IMAP_OAUTH_SCOPES_MICROSOFT`	Advanced comma-separated resource-scope override for Microsoft OAuth. Unset uses Exchange `IMAP.AccessAsUser.All`; MSAL adds its required OIDC scopes, including `offline_access`.

How polling works. For every enabled row, every poll interval (new accounts default to 10 min), suchi opens the folder, searches for UIDs above its durable high-water mark, fetches each message’s raw body, stores it in the CAS as message/rfc822, and enqueues a post-ingest job. core/pipeline/eml then fans out one child document per attachment. A configured processed folder moves completed mail; otherwise server read state stays untouched unless mark_seen is explicitly enabled. A failed UID holds the cursor before that message so a later success cannot silently skip it. The intake policy is evaluated locally after the normal UID/date search. Accepted messages may retain the email and its files or files only. Rejected messages advance the local cursor but are not stored, moved, or marked read. Dedup is by Message-ID — a doc with the same Message-ID under the same owner and system is skipped on re-polls. Safe across restarts and transports within that system; equal mail filed into another system is a separate document, though its immutable CAS bytes can be shared. Bridge tip. The built-in Proton relay preset uses protonmail-bridge:143 without TLS because that hop stays on the local container network; Bridge owns the encrypted upstream connection. Enter the Bridge-generated password in the same modal. Use the custom preset and a CA file only when your own relay exposes a TLS listener.

Model assistance (optional; egress on)

The model is off by default. These settings turn on model-backed classification, Ask your documents, and suggested dates and details. Non-local endpoints require the egress acknowledgement. The separate application mode defaults to Apply when confident without enabling a model. Ask your documents sends only the question, bounded recent conversation, and selected document title, sensitivity, text, plus permitted reviewed details. It stores no live conversation. Administrators can choose the bounded reading depth independently of provider configuration; see Ask your documents: Reading-depth presets.

Env var	Purpose
`LLM_ENDPOINT_URL`	e.g. `http://127.0.0.1:11434/v1` for Ollama, or an OpenAI-compatible URL. Unset = classifier disabled.
`LLM_MODEL`	Model identifier passed to the endpoint (e.g. `llama3.1:8b`).
`LLM_API_KEY` or `LLM_API_KEY_FILE`	Optional; blank for local Ollama, required for hosted endpoints.
`LLM_EGRESS_ACK`	Must be `true` for non-local endpoints. Loopback, private, link-local, `.local`, and `.localhost` endpoints skip the check.
`LLM_CONFIDENCE_THRESHOLD`	Model metadata and per-date automatic threshold from `0.50` to `0.95`; default `0.70`. Below-threshold results are flagged for review. Automatic application also requires the shared mode and current guards. When configured, it wins over the stored web setting.

Archive Configuration AEAD-seals API keys before writing them to settings and never reads plaintext keys back. It exposes masked status, a synthetic connection test with validated fields and latency, and an explicit key-clear action. The classification options separate model-free archive matching from model/date thresholds. Save matching options preserves the model’s enabled state. After a successful connection test, Enable model activates the configuration. Apply when confident is the default application mode and covers new dates, model metadata, and local matches. Choose Review first to send inferred changes to Approvals. Save application mode saves only this choice, independently of model activation, credentials, egress, and explicit rules written by a user. Neither startup nor settings saves bulk-accept pending suggestions; new ingests and explicit rescans use the current policy. Compose installs can reach host Ollama at http://host.suchi.local:11434/v1. As described under Precedence, config-file and environment values pin their individual classifier fields. Unpinned activation, configuration changes, key rotation or clearing, disable, and re-enable apply to the running process immediately.

MCP client env (for `suchi mcp` / `suchi-mcp` symlink)

The MCP subcommand acts as a client to a running suchi instance — these tell it how to reach the API. Flags override env.

Env var	Purpose
`SUCHI_URL`	Base URL, e.g. `http://127.0.0.1:8000`. Also honored by `--url`.
`SUCHI_TOKEN`	Scoped API token from `POST /api/token/`. Also honored by `--token`.

Config file loader itself

Env var	Purpose
`SUCHI_CONFIG`	Explicit override for the config file path. Bypasses the search order entirely.
`XDG_CONFIG_HOME`	Standard XDG variable; feeds the search path. Falls back to `$HOME/.config` when unset.
`HOME`	Standard shell variable; the config search reads `$HOME/.config/suchi/config.*` as one of the paths.

Live database settings

The operator-facing settings below live in the settings table and are set via Archive configuration. This is the complete list of stored values that participate in runtime configuration. A stored value fills a field only when that field is absent from the config file and process environment. The running LLM, filesystem watcher, OCR configuration, and backup schedule reload after a successful save; pinned fields retain their boot value.

Key	Purpose
`backup.interval_hours`	Backup cadence in hours when `BACKUP_INTERVAL` is not configured.
`ingest.fs_watch_dir` / `ingest.fs_watch_owner_id` / `ingest.fs_watch_system`	Archive Configuration watcher destination values for fields not pinned at boot; the owner is a durable numeric user ID.
`classification.auto_apply`	Shared automatic application mode; missing means enabled, malformed values fail closed. Saved independently of model configuration.
`classification.archive_enabled` / `classification.archive_auto_threshold` / `classification.archive_review_threshold`	Live local matching, automatic threshold (default `0.90`) and minimum review-suggestion score (default `0.50`). Application also requires the shared mode and current guards.
`llm.subscriptions.{provider}.model`	Saved provider model dropdown preference; selecting it does not activate inference or grant egress consent.
`llm.subscription_provider`	Explicit registered provider ID for the active subscription configuration; empty for endpoint models. `LLM_ENDPOINT_URL` overrides this selection.
`llm.chatgpt_sealed`	Encrypted instance-wide ChatGPT Codex access/refresh credentials. Connect/disconnect in Classification settings; see LLM classifier.
`llm.endpoint_url` / `llm.model` / `llm.api_key_sealed` / `llm.egress_ack` / `llm.confidence_threshold` / `llm.disabled`	Live model configuration. `_sealed` is AEAD-encrypted with the settings key.
`ocr.languages`	JSON array form of `OCR_LANGUAGES`.

Filing mode, Inbox and last-import author ID/version/hash/snapshot are stored on jd_systems, not global settings.preset or taxonomy setting aliases. Migration 0003 converts a retained old date opt-out into the shared application mode and preserves a custom local automatic threshold.

Secrets convention

Every secret env var has a _FILE variant. The file’s contents (trimmed of trailing newlines) becomes the value. Matches docker + k8s secret mounts. Secrets are never logged. Confirmed _FILE variants today:

OIDC_CLIENT_SECRET_FILE
LLM_API_KEY_FILE

If both variants are set in the same source, _FILE wins. Either environment variant overrides either config-file variant.

Egress surface

A stock install makes zero outbound connections (principle 8). At boot, suchi logs main.egress.surface listing every effective outbound path — OIDC discovery, database-backed IMAP polling, and cloud LLM endpoints, including the fixed provider destination for Account subscription (https://chatgpt.com for OpenAI ChatGPT). Destinations are redacted to safe origins. outbound: none is the safe default; suchi doctor reads the same inventory from the current database.

See privacy for the full posture.

Overview

Getting started

Reference

Concepts

Operations

Guides

Development

Alternatives

Configuration

Precedence

Config file (optional)

Search paths

File shape

Environment variables — boot configuration

Required

Storage & runtime

Ingest pipeline timeouts

Ingest pipeline max-sizes

TLS

Local auth

Dev mode

OIDC

Filesystem-watch ingest

Email ingest (IMAP polling)

Model assistance (optional; egress on)

MCP client env (for `suchi mcp` / `suchi-mcp` symlink)

Config file loader itself

Live database settings

Secrets convention

Egress surface

​Precedence

​Config file (optional)

​Search paths

​File shape

​Environment variables — boot configuration

​Required

​Storage & runtime

​Ingest pipeline timeouts

​Ingest pipeline max-sizes

​TLS

​Local auth

​Dev mode

​OIDC

​Filesystem-watch ingest

​Email ingest (IMAP polling)

​Model assistance (optional; egress on)

​MCP client env (for suchi mcp / suchi-mcp symlink)

​Config file loader itself

​Live database settings

​Secrets convention

​Egress surface

Precedence

Config file (optional)

Search paths

File shape

Environment variables — boot configuration

Required

Storage & runtime

Ingest pipeline timeouts

Ingest pipeline max-sizes

TLS

Local auth

Dev mode

OIDC

Filesystem-watch ingest

Email ingest (IMAP polling)

Model assistance (optional; egress on)

MCP client env (for `suchi mcp` / `suchi-mcp` symlink)

Config file loader itself

Live database settings

Secrets convention

Egress surface