Operate

Operating

Running Omnesis once it is installed: the background services, checking health, the configuration file, model assignment, and what to do when something goes wrong. It is written for whoever looks after the gateway machine. Security and encryption live on Security; backups and updates on Backup & updates.

Services

The installer registers the gateway and collector as user services: launchd LaunchAgents on macOS, systemd user units on Linux. Both start at login and restart on failure. omnesis service install sets them up on a machine where the installer did not. Name a component to install just one, for example omnesis service install collector on a machine that only syncs.

The other verbs are start, stop, restart, status, logs (-f to follow, -n for the number of lines) and uninstall; a bare omnesis service shows status. stop returns only once the daemon has exited and released its stores, and the service stays down until start or the next login on macOS, so offline maintenance such as omnesis restore can rely on it.

Every verb accepts --config-dir, which points the unit at another configuration directory, and --instance <name>, which manages a named instance: a second, parallel gateway or collector whose unit names carry that suffix. install also takes --env KEY=VALUE (repeatable) to add environment variables to the unit. Re-running install rewrites the unit from the flags you pass, so pass the same ones the service was installed with, then omnesis service restart it.

COMPONENT    UNIT                                     STATE          PID
gateway      omnesis-gateway.service                  running        41250
collector    omnesis-collector.service                running        41283

A configuration directory belongs to one gateway at a time. The gateway records its ownership in gateway.lock before it opens any store. A second gateway pointed at the same directory, such as a manual omnesis gateway serve beside the service, waits about a minute for a predecessor that is still shutting down, then refuses to start and names the process that owns the directory. Run a second gateway only against its own configuration directory.

During shutdown the gateway refuses new requests and disconnects WebSocket clients; requests already in flight get a short window to finish. Clients reconnect once it is back.

A collector whose event loop stops turning for five minutes (alive, but stuck and syncing nothing) ends itself so its service restarts it. It first writes Event loop stalled and the stack it was stuck in to its error log, which is the line to include when you report the problem.

The generated services create files owner-only (umask 077). On Linux the systemd units also get a private temporary directory, a read-only view of the system and home directories apart from Omnesis's own paths, no new privileges and restricted address families, and loginctl lingering is enabled so the daemons survive logout and reboot. On macOS the logs go to ~/Library/Logs/Omnesis/. To run the daemons against encryption at rest, or to run the gateway under a dedicated account, see Security.

Full Disk Access (macOS)

On macOS the collector reads Apple data (Contacts, Messages, Notes, Calendar, Safari) that the system gates behind Full Disk Access. There is no prompt for it and no installer can grant it. omnesis service install collector prints the procedure with the exact node binary that runs the daemon. From a terminal it also opens System Settings at the Full Disk Access pane and reveals that binary in Finder, so you can drag it into the list (--no-open skips this). Grant it, then restart the collector.

Until access is granted, each affected source reports the same procedure as its error instead of syncing nothing: on the portal's Sources page as one card per collector naming the binary and the sources waiting on it, under omnesis status as an “Access Required” section, and in omnesis doctor. A Node upgrade changes the binary's path and signature, so grant access again after one.

Monitoring

Three tools answer “is it working”: omnesis status for sources, omnesis doctor for everything else, and the service logs for detail. On the portal's Sources page and in the mobile apps, anything worth knowing about a source appears as a small icon beside the device it concerns: an information mark for a standing note, a warning mark for something partly broken, an error mark for a source that has stopped. Select the icon to read what it means and what to do.

Status

omnesis status prints one row per source: sync state, document count, index coverage, last sync, and the ingested and indexed date ranges. It ends with the gateway's version and a count of how the paired devices compare to it (see Version compatibility). Pass -w to keep it open as a live view.

Omnesis Status (on disk: 2.4 GB)

  Source                    State    Count             Idx      Size  Synced   Int  Ingested Range     Indexed Range
✓ gmail:maya@example.com    synced   48,213 emails     100%  610.2 MB  2m ago   15m  03/04/19-06/07/26  03/04/19-06/07/26
⟳ whatsapp:+15550100123     syncing  12,940 messages    98%  128.7 MB  30s ago  5m   11/01/21-06/07/26  11/01/21-05/07/26
✓ apple-notes               synced   1,082 notes       100%   14.1 MB  8m ago   30m  02/06/15-04/07/26  02/06/15-04/07/26

Gateway 1.4.0  ·  devices: 3 current, 1 behind

A source can sync successfully while its deletion detection is incomplete, so Omnesis may miss items removed upstream. The portal, omnesis status and omnesis doctor show such a warning with when it was first seen and how to recover. It survives gateway restarts and clears only when the affected collector confirms recovery.

Doctor

omnesis doctor is a read-only health check across the gateway, pairing, models, source authentication, the versions of paired devices, the index, disk space, configuration and the running process, with a fix next to each finding. It exits non-zero only when something is actually blocking, so it is safe to script. Once the gateway has checked for releases, it also says whether a newer stable release exists. By default it includes this host's security checks (--no-security skips them).

The same report is in the portal under Debug → Doctor. A collector's own report covers its configuration, source access, disk, process, keyring and service; run it from Settings → Devices by expanding the collector and choosing Run under Health, or Run health checks for every collector at once.

From a terminal, omnesis doctor --device <name> prints one collector's report and omnesis doctor --fleet prints every collector's (--json for the raw entries). A request to an offline collector waits until it reconnects. Gateway-only checks show as N/A in a collector's report, and every fix in it names the collector it runs on.

A collector's source-access check opens each local source's inputs read-only, without reading their contents or running a sync. Missing inputs, incomplete scans and timeouts are reported as unverified rather than healthy, and sources with nothing local to check show N/A. On macOS the permission belongs to the collector's executable, so a file your terminal can read may still be refused to the collector. The portal's checks only read; omnesis doctor --fix-permissions, run on the affected host, is what restores owner-only file modes under its configuration directory.

Logs

omnesis service logs gateway -f follows the gateway's log: the journal on Linux, files under ~/Library/Logs/Omnesis/ on macOS. Two environment variables control logging: OMNESIS_LOG_LEVEL (debug, info, warn or error; default info) and OMNESIS_LOG_FILE, which also writes a rotated copy to that file. Set them on a service with omnesis service install --env.

Configuration

Everything you can edit lives in one file, ~/.config/omnesis/omnesis.json, owned by the gateway; collectors fetch their configuration from it. Edit it with omnesis config get / set / edit, in the portal's Settings → Config tab, or directly in an editor: the gateway watches the file, and every path goes through the same schema validation. An invalid edit while the gateway runs leaves the last good configuration in effect, and omnesis doctor reports the failed load. An invalid file at boot stops the gateway; it is never silently replaced with defaults.

While the gateway on this machine is stopped, including one that fails on start, omnesis config get / set / edit / ls work on the file directly under the same validation, and the changes apply at the next start. OMNESIS.md in the same directory is yours rather than the gateway's: the agent's standing instructions, in plain Markdown (see The agent → Standing instructions).

omnesis self set --name <name> --email <address> --phone <number> records who you are (--email and --phone repeat) under self in the file. The gateway uses it at start to build the person that represents you in the people graph; omnesis self shows the current values.

In the portal every field says whether it is set in the file or falls back to a default, an inherited value or unset behaviour. Edits in the Structured and Raw JSON views are staged: Save shows a diff, and only confirming it writes omnesis.json; leaving the page discards them. Clearing a field or choosing Reset to default removes that override. List settings also offer Set an explicit empty list where an empty list differs from the default, and Set in config filters the view to your own overrides.

{
  "dataRetention": { "maxAge": "2y" },
  "activityRetention": { "maxAge": "90d" },
  "sources": {
    "default": { "syncInterval": "15m" },
    "gmail:maya@example.com": { "syncInterval": "5m" }
  },
  "search": {
    "params": { "resultLimit": 10 },
    "boosts": { "typeBoosts": { "note": 1.2 } }
  }
}

sources.default holds the settings every source falls back to. A key naming a source type, such as gmail, overrides them for every account of that type, and a key naming one source, such as gmail:maya@example.com, overrides both for that source alone. Resolution is per field, so a type-wide extractAttachments still applies to an account that only sets its own syncInterval. omnesis config set /sources/default/syncInterval 10m takes a JSON Pointer or a dot-path; omnesis config edit opens the file in $EDITOR and validates it on save.

search.params holds the ranking settings: how many candidates each search method contributes, how many results come back, and how keyword and semantic matches are weighed against each other. search.boosts.typeBoosts multiplies the score of a whole document type (above 1 promotes it, below demotes it). search.defaultFilters adds filters to every query; list filters combine with the query's own, and a date range in the query wins. The defaults suit most corpora.

dataRetention.maxAge limits how old ingested source data may be; maxAge under a sources entry overrides it for those sources, in the same order as every other source setting. activityRetention.maxAge is separate: it removes expired operational history and unpinned agent conversations in small background batches, never data ingested from sources, and never pinned, running or pending work. Without it, activity is kept forever. Deleted data frees space inside the databases for reuse, but a database file may not shrink on disk.

gateway.snapshotAbsence controls how cautiously Omnesis deletes items that a source stops listing. Some sources report what they still have rather than what was deleted, and a failed read (a locked database, a lapsed permission) looks the same as everything having been deleted. So a missing item is removed only after minObservations syncs (default 3) over at least minAge (default 24h) agree it is gone. Raise either for a flaky source; the cost is that real deletions take longer to show.

The collector reads the operating system's region to interpret phone numbers written without a country code. macOS uses your regional setting; Linux prefers LC_TELEPHONE. A headless or container collector can set OMNESIS_PHONE_REGION to a two-letter country code such as GB; restart the collector after changing it.

The portal's Settings → Config tab lists every other key with its current value and description. Two worth knowing: gateway.pushWakeRetry tunes how long the gateway keeps retrying a failed phone wake (about an hour by default), and gateway.analyticsStreamRekeyMaxRows (default 100000) caps how large an analytics table may be when a source switches to per-device mode while the gateway runs; a larger table waits until you raise the limit and restart the gateway.

Models

Every AI capability in Omnesis is a role that you assign a model to. Search and ingestion work with no role assigned: without an embedder, search ranks on keywords alone. A feature that needs a role says so when it is missing.

Each role can run its model in one of four places:

• Local GGUF models, downloaded with omnesis model install into the configuration directory's models/ folder and run by the gateway, fully offline.
• Any OpenAI-compatible HTTP server, with presets for OpenAI, Google, Mistral, Groq, Cerebras, Together, Fireworks, DeepSeek, NVIDIA, xAI, Meta, Moonshot AI and OpenRouter.
• Anthropic, assigned as anthropic/<model>. Add the API key in Settings → Models; the gateway then lists every model that key can use. The list refreshes at start, when the key changes, hourly, and on Refresh model list. Until a refresh succeeds a small built-in list is offered, and a failed refresh keeps the last good one.
• Codex, assigned as codex/<model>, which runs agent-class roles on a ChatGPT subscription through OpenAI's Codex runtime. Sign in with omnesis codex login; omnesis codex status shows the runtime and sign-in state. Codex serves the agent, privacy-reviewer and image-capable ocr roles from one login; it has no embedding or transcription models.

Turn off Allow cloud inference in the same place to disable it. Changes take effect without restarting the gateway. From the CLI, set inference.allowRemoteInference: true, or pass --allow-remote to backend add.

Active
  embedder             Nomic Embed Text v1.5 (Q8_0)  [ready]  (139.8 MB)
  transcriber          Whisper Small (multilingual)  [ready]
  …

Cognition
  agent                HTTP: gpt-4o  [ready]

System
  …

The local engine depends on the role. The embedder runs a GGUF model in the gateway through node-llama-cpp, on the GPU through Metal on Apple Silicon. The transcriber runs whisper.cpp in a separate process, so a crash in the native code cannot take the gateway down. The ocr role has three local runtimes: apple-vision (macOS, with the Swift toolchain installed), tesseract (with the tesseract binary installed), and gguf, a llama.cpp vision model you supply, run through llama-mtmd-cli with its model and projector paths set under inference.ocr.gguf. The agent role does not run a local GGUF model; to keep it on your machine, point it at a local OpenAI-compatible server such as Ollama, llama-server or vLLM.

omnesis model assign covers every role, so the terminal and the portal's Settings → Models tab configure the same set. Assigning ocr to a Codex model sends images and rasterised PDF pages to it, which needs remote inference enabled.

Changing the embedder re-embeds the corpus in the background while search keeps using the existing vectors. omnesis index rebuild does the same under the current model, for when existing vectors are known to be stale (--hard drops them at once and searches by keyword until it finishes).

Reasoning settings

Reasoning models accept settings that trade answer quality against latency and cost, and every provider spells them differently. Omnesis does not guess them from model names. Instead it looks up the exact provider and model a role is assigned to and offers only the settings that model publishes. There are three kinds:

For HTTP backends the list comes from Models.dev, an open catalog of models and their options per inference provider. The same model can offer different settings on different providers, so the lookup uses the backend's provider: a preset name, or a URL that matches a preset's default address. Omnesis then keeps only the settings it knows how to send to that provider's API. Reasoning settings are offered for OpenAI, Google, Mistral, Groq, Cerebras, Together, DeepSeek, NVIDIA, Moonshot AI and OpenRouter; which of the three kinds appear depends on the provider and the model. For Codex, the effort levels come from the installed Codex runtime's own model list.

Anthropic, local GGUF and other OpenAI-compatible servers show no reasoning settings, and neither does a model that is missing from the catalog. Such a model still works; it runs with its own defaults. Only the agent and privacy-reviewer roles take reasoning settings.

The gateway ships with a Models.dev snapshot, so the settings are available offline. When Settings → Models or a model picker opens, the gateway checks for a newer catalog if the one it has is more than a day old. It keeps the downloaded copy in the models-dev/ folder of the configuration directory, and keeps using its last good copy when the check fails or returns an incomplete catalog. Provider logos in the model pickers come from the same catalog, fetched once through the gateway.

Change them in the portal or the apps

Open a role's card in Settings → Models in the portal, or in Configure Models in the iOS and Android apps. The card shows the settings the assigned model offers, labelled in the provider's terms. Model default, the starting choice for every setting, sends nothing, so the provider's own default applies. A change saves on its own a moment after you make it, and the role's card summarises what is saved, for example Effort high.

Some settings exclude each other, and the card enforces that as you choose. Turning reasoning off clears any effort or budget. Google accepts only one of the three at a time, and OpenRouter either an effort or a budget. If another device saved the same role while you were choosing, your change is refused and the card reloads the saved values.

Change them from the CLI

There is no dedicated command. The settings live in the configuration under inference.modelSettings, one entry per role, naming the assignment they belong to. Set one with omnesis config set:

assignment must be exactly the value the role was given with omnesis model assign, for example openai/gpt-5. Unlike the portal, config set checks only the shape of the entry, not whether the model offers the setting. Check a value against the choices in Settings → Models before saving it this way.

Which model a setting applies to

Settings are saved per role and tied to the model that role had when they were saved. Two roles that use the same model keep separate settings. Assigning a different model to a role starts it from the model default; the previous model's settings are ignored, not carried over.

A saved setting is never dropped quietly. If a catalog update removes an effort level or narrows a budget range, the role's card says the saved choice is no longer offered: pick another value or Reset to model default. Until then, the role's requests to an HTTP backend fail with an error naming the setting, rather than running with different reasoning than you chose. A positive token budget also raises the reply ceiling to the budget plus 4,096 tokens; if the backend's declared maxOutputTokens (below) is lower, requests fail with an error saying how many tokens the budget needs.

Token limits and timeouts

OpenAI-compatible servers do not report token limits. If you know them, declare them under the backend's modelLimits, keyed by the exact model id it serves:

{
  "inference": {
    "backends": {
      "local-agent": {
        "type": "http",
        "url": "http://127.0.0.1:8080",
        "agentTimeoutMs": 600000,
        "modelLimits": {
          "example-model": {
            "maxInputTokens": 28672,
            "contextWindowTokens": 65536,
            "maxOutputTokens": 32768
          }
        }
      }
    }
  }
}

maxInputTokens limits the request, contextWindowTokens limits the request plus the reserved output, and maxOutputTokens caps the reply. Omnesis applies only an entry whose key matches the assigned model exactly and never guesses limits from model names. Without a limit it can report the tokens used but cannot reject an oversized request before sending it.

Without a declared maxOutputTokens, agent requests ask for a 4,096-token reply, or 16,384 once a model has shown it reasons at length. A reply cut off before any answer is retried once with up to 32,768 tokens when maxOutputTokens allows. Requests time out after two minutes, or ten for a model that reasons at length; agentTimeoutMs overrides both for an HTTP backend.

When an OpenAI-compatible backend answers HTTP 429 (rate limited), Omnesis retries up to twice, honouring Retry-After when the wait fits within 15 seconds and the request's deadline. Answer requests run unattended, so their agent and reviewer calls retry up to four times with up to three minutes of waiting, enough for a per-minute quota to reset. A lower maxOutputTokens can also reduce what a provider reserves per request.

Codex runtime and capacity

Omnesis manages a Codex runtime version tested with the installed release. In Settings → Models → Backends, Refresh model list asks the installed runtime for its models, and Update runtime installs the tested version on the gateway host. Updating keeps the gateway's ChatGPT sign-in and every assignment; new Codex work pauses while running turns finish, and a replacement that fails verification is never activated. Newly available models are listed, but no assignment changes on its own. omnesis update does not touch the Codex runtime.

When OMNESIS_CODEX_COMMAND points at your own Codex executable, Omnesis treats the runtime as externally managed: update it yourself, restart the gateway, then refresh the model list.

Codex runs three interactive turns at once by default and two other inference calls, and queues the rest. Tune this with inference.codex.interactivePoolSize and inference.codex.inferencePoolSize (or the OMNESIS_CODEX_INTERACTIVE_POOL_SIZE and OMNESIS_CODEX_INFERENCE_POOL_SIZE environment variables, which win) and restart the gateway. More slots use more memory, and every process shares the same ChatGPT allowance.

Troubleshooting

Start with omnesis doctor: it names most problems and the fix for each. Then check sources, the daemons and their logs.

A store will not open

A gateway that exits during start names the store it could not open in omnesis service logs gateway, quoting SQLite or DuckDB. For the analytics store the two common messages are a conflicting lock (another process holds it: a gateway still shutting down, a duplicate gateway, or a tool with the file open) and a damaged block, which DuckDB reports as a key mismatch. Neither is a reason to delete the file: the analytics store holds rows no other store can rebuild. Keep it and its .wal, and restore from a backup or recover the file.

A gateway that finds another process owning its configuration directory says so and exits the same way.

A collector has stopped

A collector that notices the gateway refusing a credential that used to work records why and stops, rather than retrying forever. omnesis service status on that host reports it and prints both halves of the recovery: the omnesis devices repair command to run on the gateway host, and the omnesis pair command to run on the collector. On the gateway it shows as needs-pairing in omnesis devices list.

Source errors and sign-in

The Sources page and omnesis status show each source's own fix for authentication, permission and collector problems. omnesis sources debug <id> shows a source's sync position and counts, omnesis sources reauth <provider>:<account> signs an account in again, and omnesis sources resync <id> rebuilds a source's data from the start; use resync only when that is needed. Pages captured by the browser extension cannot be resynced, because nothing holds their past copies to fetch again. See Managing sources for every source action.

Re-authentication must sign in to the same account; add another account as a separate source. A sign-in flow expires after 15 minutes without activity (gateway.timings.authFlowTtl), and an expired or cancelled flow must be started again.

CLI at a glance

The omnesis command groups below each have a home in these docs. omnesis --help and omnesis <command> --help are the complete, authoritative reference for every command and flag.