Skip to main content

Settings and Admin

The Settings page is the administrative control area for OpenKeep. It has three sections in its left navigation: General (language preferences, watch folder, archive import/export, processing activity, system health), Tags & taxonomy, and AI providers.

Account management — your profile, two-factor authentication and API tokens — moved to the Profile page, opened from the avatar menu in the top bar.

For operator-focused guidance outside the UI, see Operations Overview.

User Profile​

The User Profile section shows the current account information, including:

  • display name
  • email address
  • role

API Tokens​

Use API tokens when you need programmatic access to OpenKeep.

You can:

  • create tokens
  • set an optional expiry date
  • copy the token at creation time
  • revoke tokens later

Important:

  • a newly created token is only shown once
  • store it securely when it is generated

The Desktop App uses one of these tokens to connect to an existing archive. Revoking that token causes the desktop app to remove its stored connection the next time the server verifies it.

An owner can also manage two-factor authentication and API tokens from a connected desktop app. The desktop runtime keeps its connection token outside the shared UI; the page receives only token names, prefixes, dates, and a newly created token's one-time value. If you revoke the same token the active desktop profile is using, the profile disconnects on its next authenticated request and needs a replacement token.

Tags and Taxonomy​

Settings -> Tags & taxonomy curates the labels used across the archive. One list serves all three kinds — switch between Tags, Correspondents and Types at the top.

The list is built for large archives: it filters as you type, virtualises the rows, and shows how many documents use each entry. Sort by name or by document count.

Quick Filters​

  • All — everything
  • Unused — entries no document uses. Only available once document counts have loaded; if the count request fails, the filter is disabled and the counts show as — rather than pretending every entry is unused.
  • Duplicates — entries OpenKeep believes are the same thing, such as a case-only difference, a singular and its plural, or a name that is a prefix of another. Each carries a one-click merge into <name> suggestion.

Acting on Entries​

Type a name and press Add to create an entry.

Tick one or more rows to open the action bar, which offers:

  • merge the selection into another entry — the target picker filters as you type, so it reaches every entry, not only the first page
  • rename, when exactly one row is selected
  • delete the selection

Deleting an entry removes the label, not the documents.

If an action fails, the reason is shown above the list.

Use this to keep the archive consistent when AI-generated labels drift or duplicate.

Categories​

Categories are the fourth kind in the same list. The twelve builtin life domains carry a Builtin badge: they can be renamed (the internal identifier stays, so automatic assignment keeps working) but not deleted — the action bar explains this when a builtin is selected. Custom categories support the full add/rename/delete cycle; deleting one clears it from its correspondents, and the next automatic pass reassigns them deterministically. Categories have no merge — reassignments are one click each in the correspondent dossier.

Counts in this list are correspondents, not documents. Each correspondent row also shows its current category inline, so misclassifications are visible in bulk; fix one in the correspondent dossier, where the picker shows whether the category was assigned automatically or set by you.

Mobile Offline Copy​

On the phone app, Settings -> Offline shows how many documents are cached, how much file storage they use, what is kept per document, and a Delete the offline copy action. Cache clearing lives there rather than in the main settings list. Deleting the local copy never changes the server archive.

There is nothing to enable: the app caches each document you open while connected and reads from those copies when the archive is unreachable. See Mobile App.

Deadline Reminders​

The server records every deadline that enters a warning window — approaching (default seven days ahead), due today, and overdue — exactly once, and completing a task or moving its date clears pending reminders. Two delivery channels exist, both opt-in:

  • Email digest: one email per day listing overdue, due-today, and upcoming deadlines with links into the archive. Enable it with the checkbox in the language-preferences card; it requires the server to have SMTP configured (the AI-providers page shows whether it is).
  • Desktop notifications: the desktop app can relay the same reminders as native notifications — see the desktop guide's Notifications section.

Archive Portability​

The archive portability section supports export, import, and watch-folder scans.

Export Snapshot​

Use Export Snapshot to create a JSON snapshot of the archive state.

Import Snapshot​

You can paste snapshot JSON back into the app and import it in one of two modes:

  • Replace
  • Merge

Use replace only when you fully understand the consequences for the current archive state.

Scan Watch Folder​

Use Scan Watch Folder to trigger ingestion from the configured watch folder. The status panel shows whether the archive server has configured the folder, its server-side path, and the last scan and import. In the desktop app this is still a folder on the remote archive server, not a folder on the desktop machine.

The page can show:

  • imported items
  • duplicates
  • unsupported files
  • failures
  • planned items in dry-run mode
  • recent scan history

Dry-run mode is useful when you want to inspect what would happen without importing anything yet.

Email Inbox​

The email inbox is the third ingestion channel, distinct from the other two:

  • Upload — you hand the app a file.
  • Watch folders — the server (or the desktop app) reads a directory.
  • Email inbox — the server polls a dedicated mailbox over IMAP and imports supported attachments (PDF, JPEG, PNG, TIFF, HEIC) as documents.

Configure it with the IMAP_* environment variables on the server. Use a dedicated mailbox (or a dedicated folder within one) and point your real mail account's forwarding rules at it — the poller flags handled messages as read, so a human reading the same mailbox by hand would hide messages from it.

EMAIL_INGEST_ALLOWED_SENDERS restricts which senders may feed the archive (addresses or whole domains, comma-separated). Leaving it empty accepts every sender, which is reasonable only while the mailbox address is private. Rejected messages stay in the mailbox and appear in the card's rejection log with the sender and reason; attachments whose bytes do not match a supported format are rejected even when their name and declared type look right.

The settings card shows the configured mailbox (redacted), the last poll, the imported/skipped/rejected counts, and the recent rejections. Poll now queues one immediate poll on the worker. Each imported document records where it came from — sender, date, and subject appear on the document's Details tab.

AI Providers​

Settings -> AI providers is the detailed place to see both what is configured and what the pipeline is doing. General settings also carries a compact processing activity section with queue depths, document status counts, pending review, and recent jobs.

At a Glance​

Four numbers across the top:

  • processing queue depth
  • embedding queue depth
  • failures among the recent jobs
  • average time per document

Note that the failure count and the average cover the recent-jobs window the server returns, not the whole archive.

The Three Stages​

One row each for Parsing, Embeddings and Chat, listing every provider OpenKeep knows about and marking:

  • Active — the one in use
  • Fallback — used when the active one cannot handle a document
  • Available — configured and ready, but not selected
  • No model set — credentials present, but no model configured
  • Not configured — no credentials

Each row also says whether the provider runs on this machine or is a cloud service that documents leave the machine for.

These states describe your configuration, not a live connection test. OpenKeep does not currently probe providers, so a provider whose credentials are valid but whose service is down still shows as available.

Recent Jobs​

The list below shows the newest jobs across both queues with their status — queued, running, done or failed — and how long each took.

Use this page when uploads appear delayed, when you want to confirm a reprocess or embed job was queued, or to check whether a missing AI feature is a configuration problem rather than a document problem.

System Health​

The system health section shows:

  • overall server status
  • readiness checks for key dependencies

Current readiness checks include:

  • database
  • object storage
  • queue

If the system is unhealthy or degraded, this is one of the first places to inspect.

When to Use Settings Most Often​

Common admin scenarios include:

  • checking whether providers are configured correctly
  • cleaning up tags or correspondents
  • exporting the archive before a migration or maintenance task
  • checking why processing seems slow
  • triggering a watch-folder scan
  • creating a token for scripts or integrations

Final User Guide Step​

Continue with FAQ for quick answers to common questions and edge cases.

If you are administering a real deployment, continue into Deployment Guide and Runbooks.