Start

Install

Install Omnesis yourself with one command, or ask a local coding agent to guide you across the devices you choose. The gateway usually runs on an always-on computer. Its installer installs the CLI, sets up TLS, registers the gateway and a collector as services, and downloads an embedding model. A second machine that only collects, or one running an agent harness, uses the same installer with a role flag.

The installer can deliver Omnesis in two ways:

Requirements

• macOS, Apple silicon or Intel. Every source is available, and local embeddings use Metal acceleration on Apple silicon.
• Linux, amd64 or arm64. Source installs need glibc 2.35 or newer; Docker hosts do not. Cloud and cross-platform sources work; the Apple, Things and Screen Time sources need a Mac, which can run a collector for a Linux gateway. Local embeddings use a CUDA or Vulkan GPU when one is present and the CPU otherwise; OMNESIS_LLAMA_GPU=false forces the CPU.
• Windows is not supported.
• Node.js 24 or newer, which the installer installs if it is missing. A Docker host does not need it.
• git, for a source install only.
• About 3.5 GB of memory for a source install, which builds Omnesis on the machine. The installer refuses a smaller machine before it fetches or builds Omnesis, though it may already have installed Node 24. On a machine with swap to spare, OMNESIS_BUILD_MEMORY_MB=4096 builds anyway.

Guided install with an agent

If you have a coding agent with terminal access on the computer where you want to begin, copy this prompt into it. The full install prompt asks the agent to inspect the machine, help you choose a gateway and any additional collectors, then walk through Tailscale, phones, and browser capture one step at a time. It uses the same installer and checks each part before moving on. You choose which devices and sources to add.

Help me install Omnesis across the devices I choose. Read https://omnesis.dev/install-prompt.md and follow it.

You can also read the agent instructions before pasting the prompt. The agent will need you for account sign-ins, permissions, and steps on other devices.

One-command install

The script runs as your user. It uses sudo only for Linux prerequisites (Node, git and build tools) when they are missing, and on Linux to make you the machine's Tailscale operator when tailscale cert refuses your user. Before it changes anything, it prints the role, delivery method and release it is about to install; --dry-run stops there. Then it:

1. Checks the platform: macOS or Linux, amd64 or arm64. Anything else is refused.
2. Installs Node 24 if needed: Homebrew on macOS, NodeSource on Linux.
3. For a Linux source install, installs make, C/C++ compilers and Python 3 if they are missing.
4. Installs the newest stable release of the omnesis CLI (a checkout in ~/omnesis), with the command at ~/.local/bin/omnesis. If that directory is not on your PATH, it adds it once to the profile file your shell reads, marked as added by the installer, and tells you the command that makes it available in the current terminal.
5. Sets up TLS: a Tailscale certificate when Tailscale is running, a mkcert certificate with --mkcert, and otherwise the gateway's own self-signed certificate. Certificates explains what each one means for browsers and phones.
6. Sets up encryption at rest when the machine has a usable OS keyring, and asks what to do when it has none (see First run).
7. Registers the gateway and the collector as user services (launchd agents on macOS, systemd user units on Linux) and starts them.
8. Downloads the embedding model you chose, so semantic search works from the start.
9. If codex is installed, offers to set up the agent with a ChatGPT sign-in (see First run).
10. Prints the exact command another machine runs to join this gateway, as a collector or an agent-harness host, with the gateway's URL and certificate fingerprint, and how to mint the pairing code that command asks for.
11. Ends with a warning when the gateway has no Tailscale certificate, naming the AI agents that cannot connect to the certificate it serves.

Roles

With no role flag the installer sets up the gateway machine, as above. Each run installs one role.

The collector and harness roles take the gateway's address and ask for a pairing code, which you mint on the gateway host with omnesis devices pair --kind collector (or --kind agent for a harness), or in the portal under Settings → Devices:

Leave out --gateway-url and the installer looks for a gateway on the local network, shows you what answered and its certificate fingerprint, and asks before pairing. If nothing answers, or there is no terminal to confirm with, it stops and asks you to name the gateway. Setup → Collector on another machine explains each step and the commands underneath.

Installer flags

Pass flags after sh -s --, as in the examples above. The role flags are in Roles.

scripts/install.sh documents every flag in its header.

First run

The installer may ask up to five questions. It reads the answers from your terminal, not from standard input, because under curl … | sh standard input is the script itself. Each has a flag, so an unattended install can answer in advance.

Embedding model. The installer lists the models built into the CLI, marks a default (the model this machine already uses, or the recommended one), and takes a number. You answer before anything is downloaded, registered or started. --no-model leaves search keyword-only.

No usable keyring. This happens on a headless Linux machine with no unlocked login keyring, or on a Mac whose login keychain is locked. Encryption at rest needs a key the machine can keep, so the installer offers three answers: continue without encryption at rest, protect the key with a generated passphrase file, or stop so you can unlock a keyring first.

The passphrase option creates an owner-only passphrase file, prints a recovery code once (write it down), and configures the services to use it. An install without encryption at rest can add it later with omnesis secure, which backs up, encrypts what is on disk and restarts the gateway. See Encryption at rest.

Codex. The offer appears once an ordinary gateway is healthy, when a codex command is on your PATH and the agent has no model. The installer never runs that command; it only takes it as a sign the offer is relevant. If you accept, Omnesis signs in to ChatGPT with a device code in its own private Codex home, never copying another installation's credentials. It assigns codex/gpt-5.6-luna to the agent only if your account's model list includes it. A failed sign-in or check leaves the agent unassigned and prints how to retry.

Accepting turns on remote inference for the whole gateway: conversation context, relevant Omnesis data and tool results are sent to OpenAI, and any other remote model you configure later is allowed too. Collector, harness, client-only, Docker and hardened installs, and installs with --no-service, never make this offer.

Address for other machines. The installer lists the names and network addresses in the gateway's certificate. Choose one the other machine can reach. It is saved as OMNESIS_GATEWAY_URL and used in the join commands it prints. The default is omnesis.local for a self-signed certificate and <hostname>.local for mkcert; an IP address works on a network without mDNS.

Without a terminal (a container build, a provisioning script, a systemd unit), the installer cannot ask the required questions and refuses rather than choosing for you. Pass their flags and it runs unattended.

Open the portal

Open the portal at the address the installer printed: https://<magicdns-name>:7600/portal/ after a Tailscale certificate, otherwise https://localhost:7600/portal/. With the self-signed certificate your browser warns once; accept it. The portal asks for a pairing code, which you mint on the gateway host:

The CLI on the gateway host needs no login: it uses the gateway's bootstrap admin token. On a Docker install the daemons are containers, so use the docker compose commands under Docker in place of omnesis service.

A phone and a browser are optional. Pair the iOS or Android app by scanning a code from omnesis devices pair --kind ios (or --kind android); see Setup → Phones. The Omnesis Browser Capture extension pairs with omnesis devices pair --kind browser and needs a certificate the browser trusts; see Setup → Browser extension.

Add your first source

For Google, a wizard walks you through creating your own OAuth client, which takes about five minutes once per install. There is no shared client: your credentials and tokens stay on your machines.

In the portal, use + Add source on the Sources page. Adding, pausing and removing sources is covered in Managing sources, and the full catalogue, with what each source needs, is on Available sources.

Docker

The Docker install is the same installer with a flag. The gateway and the collector run as containers from published images tagged by release. The host needs Docker with the Compose plugin, curl and a POSIX shell; no Node, checkout or compiler. The installer uses release images only, so it refuses --edge; --version X.Y.Z selects an exact release.

It writes ~/.config/omnesis/docker-compose.yml, pulls the images, starts the gateway, waits for it to answer /health, and starts the collector, which pairs itself. The config directory is mounted into the containers at the same absolute path, so the data, the token, the certificate and the compose file are all readable on the host, and a path means the same thing inside and outside the containers.

omnesis on this host is a wrapper that runs the CLI inside the container: the gateway's, or the collector's on a machine that only collects. The source, device, model, TLS, query and update commands on this site work unchanged. The daemons are containers rather than services, so manage them with docker compose instead of omnesis service:

With no version flag, the installer asks the image registry for its tags, picks the highest stable release available for every image the stack needs, and records that tag so updates and rollbacks are repeatable. OMNESIS_IMAGE_REPO changes the registry used for both the lookup and the pull. Updating is omnesis update, as on any other install.

Tag discovery works only on registries that allow anonymous reads. For a private registry, log Docker in first, then pin an exact release with --version. Paste the token only at Docker's password prompt, never on the installer's command line:

The account you log in with must itself have access to the image. If access is denied, the installer prints the docker login <registry> command to run; it never runs that command or reads the token itself.

A second machine that only collects can run its collector in a container too:

TLS in Docker

Under Docker the gateway serves its own self-signed certificate unless you give it one. That is enough for the CLI, the phone apps and collectors. It is not enough for browsers or the browser extension, which cannot connect through it at all. For those, issue a certificate on the host and hand it to the container, as below. The container cannot reach the host's Tailscale daemon or install a mkcert authority in your browser, so --mkcert and --no-tls are refused under --docker.

The self-signed certificate covers localhost, the gateway's mDNS names, the service name gateway that the collector container dials, and the host names and LAN addresses the installer passes in. The banner prints the join command for another machine with --trust-fingerprint. A certificate minted earlier is kept, because paired phones and collectors pin it. If it no longer covers the host's name or addresses, omnesis tls renew --force mints a new one, and every phone and collector paired with the old one must pair again.

With Tailscale on the host, issue the certificate for the machine's MagicDNS name. The host needs what a native install needs: it has joined the tailnet, with MagicDNS and HTTPS certificates enabled. On Linux, tailscale cert runs as root unless your user is the machine's Tailscale operator (tailscale set --operator=$USER); a key written under sudo belongs to root, so chown both files to your user before installing. A publicly chained certificate like this one needs no --tls-ca, and phones paired against it keep working when it renews.

With mkcert, issue the certificate for the names you will use and pass the authority's root with --tls-ca. Your browser needs that root installed once, and phones pair against the certificate by fingerprint.

The installer refuses a file outside the config directory or linked from elsewhere, the gateway's own tls/cert.pem and key.pem, a key that does not match, an expired certificate, one that chains to no trusted root (unless --tls-ca names its authority), and one that names no specific host. A host that only collects (--docker --collector) takes --tls-ca alone, to verify a gateway behind a private authority.

Renewing is up to you: re-issue into the same files with the tool that made them. The gateway picks the new certificate up within the hour, or at once after omnesis tls reload, without a restart. A later run of the installer without the flags keeps the certificate it recorded. What a renewal means for paired clients is in Clients that pinned the old certificate.

What a container cannot do

• The Apple sources need a Mac. Apple Notes, Messages, Calendar, Reminders, Contacts, Things and Screen Time read macOS databases that do not exist in a Linux container. The usual setup is a Docker gateway with a native collector on the Mac, installed with the --collector command the gateway's install prints. Sources that sync over the network work fully in the container.
• Discovery does not cross the Docker bridge. A container collector cannot search the LAN for a gateway, so --docker --collector requires --gateway-url, naming the gateway by a name its certificate covers.
• Certificates are issued on the host. The container cannot run tailscale cert or mkcert; it serves what you hand it, and renews only its own self-signed default.
• There is no OS keyring in a container. Encryption at rest uses a passphrase file instead: the installer offers to generate one, readable only by you, in the config directory, and the gateway reads it at start. Keep that file; without it the data cannot be opened.
• The OAuth callback ports stay published. A provider redirects your browser to http://localhost:3000–3003, so the collector container publishes those host ports; they cannot move without re-registering every OAuth client. If something else holds one, free it. A host that will never complete an OAuth sign-in can let the kernel pick the ports with OMNESIS_OAUTH_HOST_PORTS=ephemeral.

From source

For development, run the two daemons directly from a checkout:

npm run gateway and npm run collector are the checkout's equivalents of omnesis gateway serve and omnesis collector run. npm run collector and npm run cli trust the gateway's self-signed certificate for you. To run them as supervised services instead of in two terminals, use npm run cli -- service install.

To change Omnesis rather than only run it, read the contribution guide first. It covers the repository layout, the checks a pull request must pass, and the tests each kind of change needs.

Uninstall

Removing Omnesis reverses the install you made. Your data stays in the config directory until you delete it, so take a backup first if you may want it back.

1. On a second machine, remove its device from the gateway first. For a collector, move or detach the sources it hosts (see Managing sources), then on the gateway host run omnesis devices revoke <device> --forget, which deletes the device and is refused while it still hosts sources. Revoking a harness machine's device also signs its agent out of its connection.

2. Stop and remove the services and the software, by install shape:

The installer may also have added a PATH line to your shell profile, under the comment # Added by the Omnesis installer; delete both lines. On a harness machine, remove the Omnesis plugin from OpenClaw or Hermes the way that harness removes plugins.

3. Delete the data and keys, if you want them gone. rm -rf ~/.config/omnesis removes the data, tokens, credentials and, with a passphrase file, the key that opens them. With an OS keyring, the root key is stored there under the service name dev.omnesis: on macOS, run security delete-generic-password -s dev.omnesis until it reports that nothing was found; on Linux, run secret-tool clear service dev.omnesis. On a Mac, also remove the collector from Full Disk Access in System Settings.