Start

Setup

The installer leaves you with a gateway and a collector on one machine. This page connects everything else: the portal, a collector on another machine, the phone apps, the browser extension and your own tokens. It also covers the gateway's certificate and reaching the gateway when you are away from home.

How pairing works

Every client except an external AI agent joins the gateway the same way: you mint a pairing code on the gateway, and the new device redeems it for a token of its own. The token's scopes depend on the kind of device, as listed in Devices and connections.

The kinds are portal, cli, collector, ios, android, browser, agent (an OpenClaw or Hermes machine) and integration. A code is spent only when it is redeemed, so a command typed on the wrong machine, or refused before pairing, costs nothing.

Portal

The portal is the gateway's built-in web interface, at https://<gateway-host>:7600/portal/. It always asks you to log in and never reads tokens from disk. Mint a pairing code on the gateway host and paste it into the login card:

The portal redeems the code itself, so there is nothing to run on the browser's machine. Each browser becomes its own device and keeps that identity across logins, so you can revoke one browser without affecting the others. With the gateway's default self-signed certificate the browser warns once; the next section explains how to avoid that.

Certificates

The gateway serves HTTPS only, on port 7600 (set OMNESIS_GATEWAY_PORT to change it). The certificate it serves decides which clients trust it without a warning. Omnesis can set up three kinds itself, best first; a certificate of your own is the fourth. Each row says what Omnesis does and what you do first.

The self-signed certificate is fine for the CLI and the phone apps. Browsers are the reason to replace it: the portal shows a warning, and the browser extension cannot pair through it at all.

Agents are the other reason. OpenClaw and Hermes pin the gateway's fingerprint and connect with any of these certificates. Claude Code cannot connect to the self-signed one, and needs a one-time trust setting for a mkcert one; Codex needs that setting for either. See Trust the gateway's certificate. ChatGPT and the Claude apps connect from their providers' servers, so they need a public address whatever the certificate: Tailscale Funnel or a domain of your own.

A certificate controls whether a client trusts the gateway, not whether it can reach it. It must cover the exact name or address the client uses. Reaching the gateway is a network question: the same LAN, the same tailnet, or a port you open (see Remote access).

A Tailscale certificate covers the full MagicDNS name, studio.tail-example.ts.net in the examples on this site, and nothing else: not the machine's tailnet IP, a LAN address or a .local name. That name resolves and connects only for members of your tailnet, so the gateway stays as private as before. The certificate comes from a public certificate authority, which records it in public Certificate Transparency logs: your gateway's host name becomes public, nothing behind it does. If a renewal fails because the operator permission is missing, omnesis tls status and omnesis doctor report it.

A browser trusts a mkcert certificate only through the authority that issued it. To use a browser on another machine, copy rootCA.pem from the directory mkcert -CAROOT prints on the gateway host, and import it on that machine as a trusted certificate authority. Running mkcert -install there does not help: it creates a different authority. Never copy rootCA-key.pem, which can issue a certificate for any name.

A local certificate covers the network addresses present when it was created. After they change, run omnesis tls refresh --mkcert for a mkcert certificate, or omnesis tls renew --force for the self-signed one. A phone paired by fingerprint, and a CLI or collector on another machine, pinned the certificate it first saw and refuses a new one until you pair it again or trust the new fingerprint; see Clients that pinned the old certificate.

Remote access

Each client keeps one gateway address, the one it was paired or configured with, and always dials it. No client switches between a LAN address and a Tailscale name by itself, so give each one an address that works everywhere it goes: a Tailscale name reaches the gateway from home and away, a LAN address from home only. A phone changes address by pairing again; a collector or the CLI by changing its configured gateway URL, and its token stays valid.

Phones away from home

A phone paired to a LAN or .local address cannot reach the gateway once it leaves that network. A notification can still wake it, but the notification's text, Ask and uploads all need a connection back to the gateway. Tailscale gives the phone that connection without putting the gateway on the Internet:

1. Install Tailscale on the gateway machine and the phone, sign both into the same tailnet, and keep it connected on the phone. Follow Tailscale's installation guide for each device.
2. Enable MagicDNS and HTTPS certificates for the tailnet, then run omnesis tls provision on the gateway machine (see Certificates).
3. Pair the phone from Settings → Devices → Pair device in the portal, or with omnesis devices pair --kind ios (or --kind android). With the certificate in place, the QR code carries the gateway's Tailscale name, and the portal and the CLI say that it works at home and away. An iPhone is never given the Tailscale IP: iOS refuses the gateway's certificate there.
4. Turn off Wi-Fi on the phone and open Omnesis to check that it reaches the gateway over mobile data. omnesis doctor on the gateway cannot test the phone's connection.

A phone already paired with a LAN address pairs again with the Tailscale name. So does a phone paired by the self-signed certificate's fingerprint: the Tailscale certificate replaces it, and omnesis tls provision lists the paired phones when it does.

From the Internet

A gateway on a domain of yours is supported on two routes, and neither weakens how clients check the name. Omnesis obtains no certificates for public names: there is no ACME client (the protocol Let's Encrypt uses) in the gateway or the installer. Both routes assume you have made the host reachable yourself, with a DNS record and a port opened on whatever sits between the Internet and the machine.

Both also put the pairing endpoint on the Internet. It is rate-limited per client address, and a pairing code is single-use and expires in ten minutes, but a gateway only you need to reach is better served by Tailscale. External agents that run on their provider's servers, such as Claude Desktop, Claude Cowork and ChatGPT, can only use a public address. For them alone, without a domain, Tailscale Funnel publishes the gateway's tailnet name; the two routes below are for a domain you own.

Serve a certificate you obtain. Get a certificate for the name with the tool you already use (certbot, lego, acme.sh or a commercial authority) and name the files in ~/.config/omnesis/.env. The gateway serves them and picks up a replacement, but never renews them: renew with the same tool into the same paths, and run omnesis tls reload from its deploy hook or let the gateway's hourly check find the new files.

The certificate must cover every name the gateway is dialled by, including by the host's own collector and CLI, so the gateway URL names the domain too, and the domain must resolve to the gateway from the host itself. Phones pair using their system's trust only against an address the gateway knows is trusted. It recognizes its own Tailscale certificate; add any other address to gateway.pairingSystemTrustOrigins, because a later installer run removes other addresses from .env.

# the gateway's user must be able to read both files
OMNESIS_TLS_CERT=/etc/letsencrypt/live/omnesis.example.com/fullchain.pem
OMNESIS_TLS_KEY=/etc/letsencrypt/live/omnesis.example.com/privkey.pem
OMNESIS_GATEWAY_URL=https://omnesis.example.com:7600

Put a reverse proxy in front. A proxy such as Caddy or nginx holds the public certificate (Caddy obtains and renews one itself) and forwards to the gateway on the same host. The gateway then listens on loopback only, so nothing reaches it except through the proxy. It is also told to trust the proxy's report of each client's address, so its rate limits apply to the real clients rather than to the proxy.

On the loopback hop, the proxy verifies the gateway's own self-signed certificate by pinning the file the gateway serves. The proxy must also forward WebSocket upgrades, leave streaming responses unbuffered, and set X-Forwarded-For itself by appending the client's address, never passing a client's own header through. Caddy does all of this by default; nginx needs each one configured.

The proxy's address becomes gateway.publicBaseUrl: the address phones pair against with system trust, and the one external agents are given. Agents discover the gateway through documents under /.well-known/, so forward the whole origin, not just a path. The host's own collector and CLI keep dialling the gateway directly, so the gateway URL in .env names localhost, which the self-signed certificate covers.

OMNESIS_BIND=127.0.0.1
OMNESIS_TRUST_PROXY=true
OMNESIS_GATEWAY_URL=https://localhost:7600

omnesis.example.com {
    reverse_proxy https://127.0.0.1:7600 {
        transport http {
            tls_trusted_ca_certs /home/maya/.config/omnesis/tls/cert.pem
            tls_server_name localhost
        }
    }
}

The pinned file is the gateway's own certificate, so reload the proxy after omnesis tls renew --force replaces it. For nginx, the equivalents are proxy_ssl_trusted_certificate with proxy_ssl_verify on and proxy_ssl_name localhost; the Upgrade and Connection headers passed through for WebSockets; proxy_buffering off for the event streams; and proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for.

omnesis tls status lists the public name as served through the proxy, and omnesis doctor does not expect the gateway's own certificate to cover it. Once the public address is a trusted origin, omnesis devices pair --kind ios and the portal offer it first, and a phone paired with it verifies the proxy's certificate through its operating system. A collector on another machine needs no --trust-fingerprint, since the certificate chains to a public authority.

Collector on another machine

The installer runs a collector on the gateway machine, and it sets itself up: on first start it pairs using the bootstrap admin token and saves its own token to ~/.config/omnesis/collector-token.

A collector on a second machine, such as a Mac that has your Apple Notes while the gateway runs on a home server, is one installer command with the --collector role. That machine gets the CLI and a collector service, and no gateway, embedding model or index. The gateway's own install printed the exact command, with its URL and the fingerprint of its certificate. For a self-signed gateway, that URL is the address you chose after the first start, or omnesis.local if the gateway was installed without a terminal.

The role checks the gateway's certificate against the fingerprint, pairs, registers the collector service with the gateway URL, waits for the gateway to accept the device, and prints its name. The fingerprint is checked before the pairing code is spent, and a mismatch stops the install. Without --trust-fingerprint, a self-signed certificate is shown to you for confirmation and a publicly trusted one is accepted silently, so pass it whenever you have it.

Leave out --gateway-url and the role searches the local network instead (the gateway announces itself over mDNS with its fingerprint), then asks before pairing with what it found. If nothing answers, or there is no terminal to confirm with, it stops and asks you to name the gateway. omnesis devices discover runs the same search (--json for a script). --code <code> supplies the pairing code for an unattended install; by default you are asked for it, which keeps the code out of shell history.

On macOS, run from a terminal, the install ends by opening the Full Disk Access settings and revealing the Node executable in Finder, ready to drag into the list; the Apple sources need it. See Full Disk Access.

The role runs three commands, which you can also run yourself:

Instead of redeeming a code, you can set OMNESIS_TOKEN to an admin token: the collector uses it to pair on first start and saves its own collector-token, which it prefers on later runs. If OMNESIS_GATEWAY_URL is unset, the collector searches the local network over mDNS, then falls back to https://localhost:7600.

Several collectors can serve one gateway, each hosting the sources on its own machine. With more than one online, omnesis sources add --device <collector> chooses which one hosts a new source; without the flag you get a picker. Some source types can be hosted by several machines at once, others by one at a time; Sources on several devices covers joining, detaching and moving them.

If you sign in to Google in a browser on a different machine from the collector, the browser may show a “can’t reach this page” error after you approve access. Google has sent it to a loopback address on the browser's machine. Copy the full address from the address bar, including everything after ?, and paste it into the portal's Or paste the redirect URL / code box or the CLI's Paste the full redirect URL or code prompt. The collector completes the sign-in and keeps the credentials on its own machine.

Phones

Pair each phone and tablet separately, by scanning a QR code in the app. The QR code carries everything the app needs, including how to trust the gateway's certificate; see Mobile apps → Pairing. The portal and the CLI offer only addresses that phone can use and say where each works. If you want the phone to work away from home, set up Tailscale before pairing. How to install the apps is on Getting the apps.

Each app hosts sources that read data on the phone. Right after pairing, the app's setup lets you pick them, shows what each one sends, and then the phone asks for the matching permission; the same choices are in the app's Settings. Apple Health is shared across your Apple devices, so two iPhones contribute to one library. The other phone sources, Photos included, are kept per device: each phone adds its own data. The app asks about this when you enable a source; see Sources on several devices.

iOS app

The app hosts Apple Health, Photos & Screenshots, Activity Segments and Location Visits, each off until you turn it on. To build and sign the app yourself, follow the iOS contributor guide; an app signed with your own Apple team needs your own push credentials, set up with omnesis push setup (see Notifications → Direct setup).

Android app

The app hosts Health Connect, App Usage, Photos & Screenshots, Activity Segments and Call Log. The play build omits Call Log and its permission; the full build, which you build yourself, keeps it.

To build the app yourself, run omnesis push setup first: it configures push delivery through Firebase and writes the ignored android/local.push.properties file that the build reads. The package id you choose there becomes the app's identity, so your build can be installed beside an official one; rebuild after changing it. Build steps are on Mobile apps, and the Firebase values on Notifications → Direct setup.

Browser extension

The extension captures the pages you actually read into the Web Pages source (type web): the rendered text, extracted in the browser after a few seconds with the page focused. Sites that a dedicated source already covers (Gmail, Drive, Notion and others) are skipped, so a page is not captured twice. A collector announces those sites when it starts, so until one has connected, none are skipped, and duplicates are removed at search time instead. The extension never captures:

• pages in incognito or private windows, and any page that is not HTTPS;
• Chrome's own pages, the extension's own pages, and the gateway's portal;
• pages on excluded domains, on sites a dedicated source covers, and pages deleted for good;
• sign-in, registration, password, single-sign-on, checkout, payment and billing pages, and any page with a password field.

Only the readable text as Markdown, the title, the URL, the visit time and how long the page was focused leave the browser. Form values, drafts in editable fields, raw HTML, scripts, images and screenshots never do. Credentials in the address (tokens, signatures, one-time codes, passwords, session ids, an OAuth callback's code and state) are removed before it is recorded.

The extension cannot read anything back: its token can add pages but never search or read. It loads no remote code and has no analytics or crash reporting.

Install it from the Chrome Web Store (Chrome 130 or newer). In the portal, the Sources page links to the listing until the Web Pages source exists. Then mint a code under Settings → Devices → Pair device → Browser extension, or from the CLI:

On the extension's Options page, enter the Chrome profile name shown in Chrome's profile menu, the gateway URL and the code. Chrome does not tell extensions its profile name, so this label marks every visit from this browser; you can change it later on the same page. Pairing asks Chrome for access to HTTPS pages, which the capture needs; if you decline, pairing stops and says why. The extension stores a token scoped to write:web only.

The extension refuses to pair with a gateway on an older minor release than its own, and names both versions; update the gateway and pair again. If pairing times out, submit the same code again: the gateway recognises the repeated request and returns the token it already issued. If pairing fails after you granted page access, Settings shows a button to remove that access.

To develop the extension itself, run npm --prefix extension run build from the repository root, open chrome://extensions, enable Developer mode, click Load unpacked and select extension/dist/. The store version and an unpacked build are separate extensions that pair separately, so both capture if both are installed; unpair the unpacked build before relying on the store one.

Popup and capture settings

The popup's summary line reads Ready, Syncing, Paused, Not syncing (with a warning that names what to fix) or Not paired. Last page synced moves only when a page has reached Omnesis; Gateway checked is the latest conclusive check of the connection and the token, and an inconclusive check shows as a warning. Current page says whether the open page is being watched:

Versions and access. The popup shows the gateway's version beside its address, and warns, without stopping capture, when the gateway is a minor release behind the extension (update the gateway to clear it) or on a different major release (update whichever is older). If Chrome's page access is later revoked, the popup says so: open Pairing settings, choose Grant HTTPS page access, then reload open pages. Unpairing removes both the extension's token and its page access.

When the gateway is unreachable. Pages waiting to upload survive browser restarts and are retried automatically, within a fixed amount of local storage. If a long outage fills it, the popup says what was discarded. A page the gateway refuses outright is dropped and the popup shows why; only temporary failures are retried.

When the source is paused or removed. While the Web Pages source is paused, the gateway turns new pages away and the extension retries one queued page every few minutes until the source resumes. If the source was removed, the popup says so and asks you to pair again. The browser extension privacy policy describes what is captured, what is kept locally, and the permissions.

Capture settings. The capture settings live on the gateway and apply to every browser paired with it. The Options page manages the excluded domains: a page on an excluded domain or any of its subdomains is never captured, and ticking Also delete the pages already captured from this domain deletes what it already contributed, for good. The popup's Exclude button adds the open page's domain the same way and stops watching that page at once. Its pause controls pause capture in every paired browser for one hour, one day, or until someone resumes it.

A browser rereads the settings when its copy is older than fifteen minutes, whenever the popup opens, and after each change it makes; if they changed, open pages are judged again without a reload. Deleting a captured page for good, from the portal, the CLI or a phone, adds it to these settings so no browser captures it again; deleting this copy lets it be captured again. See Deleting documents.

Agent harness

A machine running OpenClaw or Hermes joins with the installer's --openclaw or --hermes role, which pairs it as an agent device and installs the harness's Omnesis plugin. The commands, the approval step and refreshing the plugin are in OpenClaw and Hermes.

Devices, integrations and tokens

Every paired device is listed in the portal under Settings → Devices and by omnesis devices list. A device names itself when it pairs; the name is only a label, which you change with omnesis devices rename <device> <name>. A device that pairs again keeps its identity, sources and data. The list shows each device's version, as described in version compatibility. A device shows as live only while its connection is open, and otherwise shows when it was last active; not being live is not a fault by itself.

omnesis devices revoke <device> invalidates the device's tokens but keeps its identity, so it can be brought back. Revoking an OpenClaw or Hermes device also signs its agent out of its connection. omnesis devices revoke <device> --forget deletes the device for good, and is refused while it still hosts sources.

One device does not stay revoked: the collector on the gateway host. It registers itself with the bootstrap admin token in the same config directory, so it comes back on its next start with its sources intact, although the token it was using stays revoked. To stop it collecting, stop the service with omnesis service stop collector. The revoke command warns you when you revoke that device.

Creating tokens

Pairing gives each device the token it needs. For a script or a tool of your own, create an extra token for an existing device, with only the scopes it needs and, ideally, an expiry. The scopes are listed in Devices and connections.

Without flags, omnesis tokens create asks for the device, the scopes and a label. It never asks for an expiry: without --ttl the token never expires. The token and its id are printed once; keep the id, since omnesis tokens revoke takes it. omnesis tokens list shows each token's label, device, scopes and when it was last used, and revoking the device revokes all its tokens. An integration's tokens can carry only answer, push:claim and write scopes.

Integrations

An integration is someone else's code that asks Omnesis questions for you: a voice assistant's handler, a home-automation hook, a script. Pair it as its own kind: on the portal's Devices page choose Pair device → Integration, or run omnesis devices pair --kind integration --name "Kitchen display", naming it for what it does. It is not trusted with your data: its tokens carry the answer scope, plus push:claim or write scopes if you grant them, and no pairing, token or repair can give it more.

What its answers may use is set by the access level you put it on, the same kind of named permission set an agent connection uses: which sources answers draw on, and which privacy policy reviews them. You choose the level in the portal. A code minted from the CLI carries no level, so the integration waits on its Devices card until you pick one; until then its questions are refused. omnesis devices list and omnesis access levels show which integration uses which level.

Changing the level applies to the integration's next question; an answer in progress is discarded and the integration has to ask again. While an integration uses a level, you cannot delete that level or remove Answer from it. A revoked integration keeps its level, so repairing it restores the same access, but it does not stop you editing or deleting that level; if the level can no longer answer, the integration's questions are refused until you choose another. An integration that needs raw search or document reads connects over MCP with Direct on an access level instead.

The CLI on another machine

If you already have a token, OMNESIS_GATEWAY_URL and OMNESIS_TOKEN in the environment are all the CLI needs. On first contact with a self-signed gateway it records the certificate's fingerprint and trusts it from then on.

External agents

External AI agents such as Claude Code, Codex, Claude Desktop, Claude Cowork and ChatGPT don't pair as devices. They connect over MCP and are approved in the portal as connections; see Bring your own agent, including the gateway.publicBaseUrl setting that agents on other machines need.

Bringing a revoked device back

A revoked device that still hosts sources shows as needs-pairing in omnesis devices list (its portal card reads Needs re-pairing), beside devices that are simply paired or revoked. It means a machine is locked out while its sources, memberships and sync positions wait on the gateway. A revoked device with nothing left to bring back reads as revoked.

On the locked-out machine, the collector notices that its token is refused, stops reconnecting and records why. omnesis service status there names the device, the gateway and the commands below. It does not pair again by itself; stopping that is the point of revoking.

omnesis devices repair mints a pairing code bound to one existing device, so redeeming it restores that device rather than creating a new one. Its id, sources and sync positions survive, and syncing resumes where it stopped instead of starting over. Name the device by id or name.

The command refuses a device that is still connected, because a repair replaces the credentials it is using: stop or revoke it first. The same action is in the … menu beside an offline device in the portal and both phone apps. A portal session is not repaired: pair the browser again with omnesis devices pair --kind portal.

A repair code names its device, so redeeming it on the wrong machine cannot take over a different device. The collector on the gateway host needs no repair code: as described above, it registers itself again on its next start.

A collector's service keeps the gateway address it was installed with. When the gateway has moved to another host or port, redeem the repair code by re-running the installer on that machine instead, which registers the service on the new address: curl -fsSL https://omnesis.dev/install.sh | sh -s -- --collector --gateway-url <new-url> --code <code>. A re-run of the gateway's installer with --port prints this line for every collector it leaves behind.

With everything paired, continue with Search.