Use

Agents & MCP

External agents are AI tools outside Omnesis, such as Claude, ChatGPT, Codex, OpenClaw and Hermes, that read your data over MCP. This page is for anyone connecting one, or their own code: the access levels that decide what an agent may do, the privacy policy that reviews its answers, the audit trail, the answer API, and the setup for each client. The built-in chat agent is covered on The agent.

Access levels

Omnesis serves one MCP endpoint, /mcp, and external agents sign in to it with OAuth. Each sign-in you approve becomes a connection: a named entry that acts with the authority you delegated to it. A connection is not a device; it cannot push data or manage the gateway.

Every connection uses one access level, a named set of permissions that one connection or many can share. An access level turns on any combination of three permissions:

An Answer permission normally names the privacy policy that reviews each answer. You can instead choose Release answers automatically, which the portal marks as high risk: source boundaries and the audit still apply, but no reviewer checks the answer, including the built-in check that blocks credentials. When an access level reaches only selected sources, a question about a source outside them is answered plainly as out of reach, rather than with evidence from a permitted source passed off as coming from the excluded one.

Neither Answer nor Direct browses or searches the live internet: both answer only from data Omnesis has already captured. An agent that needs current outside facts, such as weather or transport delays, should combine the Omnesis result with its own search tools.

Source boundaries

A source here is one account or stream, such as gmail:maya.reeves@example.com, not the whole provider or the collector that hosts it. Checked sources are always allowed. You also choose whether sources connected later stay blocked or are allowed automatically; a boundary that keeps future sources blocked must allow at least one current source. When Answer and Direct are both enabled, they share one source selection by default, and an advanced choice gives each its own.

A source-restricted Direct permission gets search, document fetch, URL lookup, analytics schema discovery, and SQL only. Call list_tables before run_sql to discover permitted tables and their columns. Follow the returned nextOffset with another call using that offset until it is null; each page defaults to 20 tables, with an optional limit from 1 to 100. Discovery returns only the current grant’s permitted schema, without row data. Analytics tables that several source accounts write to stay outside a source-restricted access level, even when every contributing account is selected.

Notes

add_note saves to the same notes source as Tell Omnesis in the portal and mobile apps. The gateway records the connection's name with the capture time and any context, and the day's note document names that connection as the entry's author, with you as its recipient. A note you capture yourself stays yours, and an agent never becomes a person in the people graph. A client can include a known capture time, time zone, or location. It must supply a UUID id and reuse it on retries, including after reconnecting to the same connection. The receipt echoes that UUID as captureId; its id identifies the saved note and is a different value. Captures from separate connections remain independent.

Managing access levels and connections

Settings → Access in the portal lists each access level followed by the connections and integrations that use it. A level shows its permissions, the sources it reaches, and its privacy policy. A connection shows its name, ID, the app it signed in from, when it was last used, and its sign-ins. Permissions and connection details are always visible within each access level card. omnesis access levels prints the same list from the CLI.

• Edit a level: the change applies to every connection and integration that uses it, and the editor names them before you save. Old access tokens stop working at once, and each client picks up the new rules on its next refresh without signing in again.
• Create a level with New access level, before any agent connects if you like. Rename a level at any time, and delete it once nothing uses it.
• Rename, move, or remove a connection. Moving it to a new level starts that level from the connection's current permissions. Removing one connection leaves every other connection working.

Privacy policy

A privacy policy is a named Markdown document that tells the privacy reviewer what an Answer may release. Policies are listed in the portal under Settings → Policies, and each opens on its own page for editing. Every access level that uses a policy links to it from Settings → Access, and one policy can serve several access levels. A new policy starts from a built-in template or as a copy of an existing one.

The built-in templates, from most to least protective, are Guarded, Balanced, Open and Unfiltered; a fresh install starts from Guarded. Every template holds for your approval anything that identifies or reaches another person (their phone numbers, email addresses, postal addresses, financial account or card numbers, and health details) even when it comes from your own contacts, messages, or files. A person's name alone, and your own contact details, follow the template's decision table.

Identity-document contents are never released automatically, and Guarded, Balanced and Open also never release exact health or financial details automatically.

Credentials depend on the template. Guarded, Balanced and Open block credentials outright: they cannot be released even with your approval. Unfiltered holds them for your approval, one request at a time.

The editor shows a line and character diff before saving. Each policy keeps its own history, and restoring an older version adds a new current entry without deleting later ones. A policy you adopted keeps its text; a change to a built-in template reaches your installation only when you adopt that template again.

Use the row’s ⋯ menu in Settings → Policies to rename a policy, including one that is in use. Renaming preserves its rules, version history and access assignments. The table’s Used by column lists the integration devices and MCP connections using each policy; click a name to open its settings. An access level with no callers is linked there instead. Delete an unused policy from the same menu. Deletion removes it from the library; version history and audit records are retained. The Delete action is disabled while the policy is the default or is referenced by access levels, connections, or other saved settings; hover over Delete for the reason. Reassign those references before deleting the policy.

You approve or deny each held answer on its own. Editing a policy requires a signed-in portal session; the mobile apps list the policies and show each one's text under their own Settings, but do not edit them.

Audit

The Audit page in the portal shows what external agents asked and what left your machine, and names the connection behind each request.

The Answer tab lists every exchange, newest first and grouped by day, with its outcome: shared, shared with details removed, not shared, failed, or still in progress. An exchange reviewed under a named policy says so and links to it. Anything waiting for your decision is pinned above the list with the held answer and both choices. While decisions are waiting, the Audit entry in the portal's sidebar and in the mobile apps' menu shows their count. A status filter narrows the list to one outcome; it applies to the activity already loaded, so load older activity to look further back.

The Direct tab lists the raw reads made with Direct tools, grouped into sessions: one per conversation or workflow ID the caller supplied, or per stretch of activity with no gap longer than an hour. Opening a session lists each tool call with its outcome, arguments, and results. These transcripts record what left your machine; nothing in them passed the privacy reviewer.

Every approval, denial, permission change, removal, and tool call by a connection is also written to the access ledger. omnesis access audit prints it newest first and pages through it with the cursor it prints. --connection <id> narrows it to one connection, using the ID shown on that connection's row on the Access page. The same data is served at GET /admin/access/audit.

The answer API

Scripts and integrations can ask Omnesis a question without MCP. The answer goes through the same Omnesis agent and the same privacy review as an Answer over MCP. From the CLI:

Each call returns one of four outcomes: the answer, the answer with details removed, a refusal, or approval required. By default an answer that the policy would hold for approval is refused instead, because a script usually cannot wait for you. --allow-approval holds it instead: the command prints a task ID, you decide under Audit, and omnesis answer --task TASK_ID --wait collects the result, waiting 60 seconds by default (--wait-timeout up to an hour).

--workflow and --conversation continue an earlier thread, --purpose tells the privacy reviewer what the answer is for, and --json prints the full response.

Over HTTP, the same call is POST /answer with a JSON body carrying question, and optionally workflowId, conversationId, workflowName, workflowPurpose, clientRequestId (an idempotency key for retries), and approval ("never", the default, or "allow"). Poll a held answer at GET /answer/tasks/<id>. The request carries no time zone, so dates are read in the gateway's own zone.

The token needs the answer scope, or admin; the scope table lists which devices hold it. An integration answers under its access level's sources and privacy policy, and is refused until you give it one. Inside an OpenClaw or Hermes shell, omnesis answer refuses to ask and points the agent to its native omnesis_answer tool, which waits for slow answers properly.

Bring your own agent

Any client that speaks Streamable HTTP MCP and completes OAuth can connect to /mcp; clients that cannot do both are not supported. The client discovers the gateway's OAuth metadata, signs in, and stores and refreshes its own tokens. Sign-in needs gateway.publicBaseUrl set, as described below; only a client on the gateway's own machine that connects over a loopback address can sign in without it. Where each client runs decides which address it can use:

Choose the address

gateway.publicBaseUrl (or the OMNESIS_PUBLIC_BASE_URL environment variable) is the gateway's HTTPS address for MCP sign-in: the OAuth issuer every client remembers, so pick it once and keep it. Until it is set, Connect an agent offers a loopback address for agents running on the gateway’s own machine; hosted clients and clients on other machines need a configured address. This address can be private for local clients. A client on your machine, such as Claude Code, Codex, OpenClaw or Hermes, can use this address or one listed in gateway.mcpResourceUrls, as long as its machine can reach it.

Hosted connectors run on their provider's servers, so they can reach your gateway only at an Internet-reachable HTTPS address, and that address must be gateway.publicBaseUrl or one of the listed extras. A name that resolves only inside your tailnet or your home network cannot serve them, and the request may fail before the gateway sees it. Tailscale Funnel publishes the gateway's tailnet name without a domain of your own; a domain you own goes through From the Internet.

To accept sign-ins at more than one address, list each extra address as an exact /mcp URL in gateway.mcpResourceUrls, each on its own origin. The addresses share connections, but a token issued for one address is not valid at another. Once gateway.publicBaseUrl is set, loopback is no longer accepted implicitly; list it in gateway.mcpResourceUrls if a local client uses it. Keeping an old address listed lets clients refresh while they move to the new one, though some clients ask you to sign in again.

A reverse proxy in front of the gateway must forward the root-level /.well-known/oauth-protected-resource/* and /.well-known/oauth-authorization-server/* discovery paths, plus the issuer's .well-known/openid-configuration path.

Clients register either with a Client ID Metadata Document, a small JSON file published at the client's HTTPS identifier, or through Dynamic Client Registration. Omnesis fetches a metadata document directly, refuses redirects and private-network destinations, and validates its redirect URLs before showing the approval screen. A metadata document may name a JSON Web Key Set and ask to authenticate with private_key_jwt; the client then signs a short-lived assertion for each token and revocation request, and Omnesis verifies it against that key set, fetched under the same rules. Clients that use Dynamic Client Registration authenticate as public clients or with a client secret.

Publish the gateway with Tailscale Funnel

If the gateway already serves a Tailscale certificate, Tailscale Funnel gives it the public address hosted connectors need, with no domain, router port or reverse proxy. Tailscale's relays accept connections for the machine's MagicDNS name on port 443 and pass them to the Tailscale daemon on the gateway machine, which terminates TLS and forwards each request to the gateway on localhost. Funnel listens only on ports 443, 8443 and 10000, so the public address has no :7600; your own devices keep dialling port 7600 as before. Publish on 443: ChatGPT connects only on that port.

1. Allow Funnel for the tailnet. It needs MagicDNS and HTTPS certificates, as the Tailscale certificate does, and the funnel node attribute in the tailnet policy file. The first tailscale funnel run prints a link that adds it.
2. On the gateway machine, publish port 443 and forward it to the gateway (on Linux, as root or the machine's Tailscale operator). https+insecure is needed because the gateway's certificate names the MagicDNS name, not localhost; that hop never leaves the machine. --bg keeps Funnel running across restarts.
3. Add OMNESIS_TRUST_PROXY=true to ~/.config/omnesis/.env. Every Funnel request reaches the gateway from the Tailscale daemon on the same machine, and the gateway exempts same-machine callers from its rate limits. With this setting it takes the client's address from the X-Forwarded-For header Tailscale sets, so its limits apply to each Internet client.
4. Set the public address, without a port, and restart the gateway. The portal's Connect an agent dialog then shows https://studio.tail-example.ts.net/mcp.
5. From a device outside the tailnet, such as a phone on mobile data, open https://studio.tail-example.ts.net/.well-known/oauth-protected-resource/mcp. It returns a short JSON document naming that /mcp address. Then add the connector: ChatGPT or Claude Desktop and Cowork.

The gateway keeps listening on its tailnet and home-network addresses for your devices, so with OMNESIS_TRUST_PROXY set it logs a warning at start: a client that reaches port 7600 directly could name its own address in that header and choose which rate limit it counts against. It can never pass as the gateway machine itself. Keep port 7600 closed to the Internet.

Funnel publishes the whole gateway, not only /mcp. A connector needs the discovery documents under /.well-known/, the sign-in endpoints under /oauth/, and the approval page, which loads the portal's styles and scripts; the portal's login page and the pairing endpoint become reachable from the Internet too. Every route that returns your data still requires a device token, a portal session or an approved OAuth token. Portal login and pairing are rate-limited per client address, and a pairing code is single-use and expires in ten minutes. A connector's sign-in grants nothing until you approve it in a signed-in portal or a paired phone; the approval page alone shows only a code.

The public address is also where the Notion, Outlook and Strava sources send their sign-in back once gateway.publicBaseUrl is set: https://studio.tail-example.ts.net/oauth/callback. Add that redirect address to the app you registered with the provider before you next sign one of them in. tailscale funnel reset takes the gateway off the Internet again, along with any other Tailscale Serve configuration on the machine; hosted connectors stop working until it is published again.

Approve the connection

When an agent signs in, its browser opens an approval page. If that browser is signed in to the portal, approve there. Otherwise the page shows a short code and a QR code. Enter the code in the portal under Settings → Access → Connect an agent or in either mobile app, or scan the QR code with the phone's camera to open the installed Omnesis app with the code filled in. Paired phones also receive a generic notification that opens the code-entry screen.

The QR code holds only the short-lived code, and entering it shows the request without approving it; you still review and confirm the permissions, sources, and privacy policy. The approval page itself is never paired as a device.

Approval starts at the Connection step. The name is filled in from the name the client reports, numbered if that name is taken, and you can change it. Then choose the access level:

• An existing level goes straight to review. Connections on the same level share its permissions.
• New access level asks for a name, then Answer, Direct and Notes, the sources and privacy policy, and a review of the resulting access. Answer and Direct must be able to read at least one source. The review says when the chosen level is already used by other connections.
• Replace a connection, for an agent signing in again, takes over that connection's name and access level. Once the new sign-in completes, the old one stops working; if it never completes, nothing is revoked.

Omnesis never adds a request to an existing connection or access level because a name or client matches; it only suggests. When the same app is already connected, the step preselects that connection's access level, and a new level starts from a copy of its permissions. When the request comes from a managed integration already connected on the same device, the step opens on replacing that connection. A request that needs Answer, such as a managed integration's, can only use an access level that includes Answer.

Trust the gateway's certificate

Claude Code and Codex trust the public certificate authorities, not the local authority mkcert installs on the machine. A Tailscale certificate, or one for a domain of your own, needs nothing more. For a mkcert certificate, and for Codex also the gateway's self-signed certificate, set one environment variable to a file that vouches for the gateway's certificate, in the shell you start the agent from:

Settings → Access → Connect an agent in the portal shows the line with the file's real path on the gateway's machine above each agent's commands, for example:

Put the line in your shell profile, such as ~/.zshrc or ~/.bashrc, then open a new shell and start the agent. For Codex the line is an alias, so the setting applies to Codex alone: many other programs, such as curl and Python, trust only the file SSL_CERT_FILE names, and exporting it everywhere would break their connections. For the agents themselves both settings add to the authorities they already trust, so their own connections keep working. An agent on another machine needs a copy of the file there, with the same variable set to the copy's path. Copy only rootCA.pem, never rootCA-key.pem. The portal does not offer the setting for a certificate of your own that no public authority issued; set the variable to the authority that issued it.

Claude Code

Choose one setup path: install the Claude plugin, which is recommended, or only add the server. Do not do both, because the plugin declares the same connection.

Claude Code accepts only a certificate issued by an authority it trusts. With a Tailscale certificate or one for a domain of your own it connects as is; with a mkcert certificate it needs the one-time trust setting first. It cannot connect to a gateway that serves its self-signed certificate at all: give the gateway a Tailscale, domain or mkcert certificate first. OpenClaw and Hermes pin the gateway's fingerprint instead, so they connect either way.

The Claude plugin declares the HTTP connection and adds skills that teach Claude how to use Answer, Direct, and Notes and how to set up or repair the connection. It asks for your gateway's MCP URL (the HTTPS URL ending in /mcp), and it neither launches an Omnesis process nor stores a gateway credential. --sparse checks out only the plugin instead of the whole repository:

To only add the server, without the skills:

Either way, open Claude Code, run /mcp, select Omnesis, and complete the sign-in in your browser. On a machine without a browser, see Sign in without a browser.

Installing the plugin from inside Claude Code asks for the URL instead, and /plugin configure omnesis@omnesis changes it later. Claude Code does not update plugins from other marketplaces on its own: turn on auto-update for the omnesis marketplace under /plugin, or run claude plugin marketplace update omnesis and claude plugin update omnesis@omnesis after updating Omnesis. Claude Code in VS Code and in the Claude desktop app cannot ask for the plugin's URL; set it from a terminal as above, or add the server by hand.

Claude Desktop and Cowork

A custom connector is brokered through your Claude account: Claude connects to it from Anthropic's servers, not from your computer, even in Claude Desktop and Cowork. A local or Tailscale-only address therefore does not work here, even though your own machine can reach it. Claude Code runs on your machine and can use a local address; see Claude Code.

Publish the gateway first, with Tailscale Funnel or a domain of your own. Then, on claude.ai or in Claude Desktop, open Customize → Connectors, add a custom connector, and enter your gateway's public HTTPS URL ending in /mcp. Connect it, approve the connection in Omnesis, then enable the connector in a conversation. On Team or Enterprise plans, an organization owner must add the custom connector before members can connect it.

ChatGPT

ChatGPT adds a custom MCP server as a developer-mode app. Developer mode is a feature of ChatGPT on the web, and whether your account can use it depends on your plan and, for a workspace, its administrators. ChatGPT connects from OpenAI's servers and only on the standard HTTPS port, 443, so publish the gateway there first, with Tailscale Funnel or a domain of your own, then:

1. In ChatGPT on the web, turn on developer mode.
2. Create an app for a remote MCP server. Enter the MCP URL shown under Settings → Access → Connect an agent in the portal, the public HTTPS address ending in /mcp, and choose OAuth as its authentication.
3. Complete the sign-in ChatGPT opens and approve the connection in Omnesis.
4. Enable the app in a new conversation.

Keep one sign-in attempt open at a time; if several authorization windows appear, close them all and start once more.

Codex

With a Tailscale certificate or one for a domain of your own, Codex connects as is. With a mkcert certificate or the gateway's self-signed one, set SSL_CERT_FILE first; see Trust the gateway's certificate.

Install the guidance, then register your gateway separately:

Omnesis needs Codex 0.147 or later; earlier versions stop at the end of the sign-in with Authorization server response missing required issuer. Check with codex --version and, if it is older, run codex update, which updates Codex however it was installed. codex mcp add finds the gateway's sign-in and opens it straight away; approve the connection in Omnesis, then start a new conversation. On a machine without a browser, see Sign in without a browser. To sign in again later, run codex mcp login omnesis. Refresh the guidance after updating Omnesis with codex plugin marketplace upgrade omnesis.

Sign in without a browser

On a machine with no browser, such as a server you reach over SSH, finish the sign-in from another device. The agent prints a sign-in link; open it on a device with a browser and approve the connection there. The browser then lands on a local address such as http://localhost:53682/callback?code=…, which fails to load because the agent is on the other machine. Copy that address from the address bar and paste it where the agent asks for it.

• Claude Code asks for the address by itself when it cannot open a browser.
• Antigravity always asks for an authorization code instead, which an Antigravity page shows after you approve; see Antigravity.
• Codex asks for it only when signing in with --no-browser. codex mcp add starts a sign-in it cannot finish there: once it says the server is added, press Ctrl+C, then run codex mcp login omnesis --no-browser.

Antigravity

Add the server to Antigravity CLI:

Then run /mcp inside Antigravity CLI, select omnesis and choose Authenticate. Antigravity opens the sign-in in your browser and also prints its link, so it works the same on a machine without a browser: open the link on any device and approve the connection in Omnesis. After you approve, the browser opens an Antigravity page with an authorization code, which is not the short code Omnesis may show while signing in: copy it and paste it into Antigravity.

Other clients

Any other MCP client that supports remote HTTP servers with OAuth connects the same way: give it the MCP URL and approve the sign-in in Omnesis. The portal's Connect an agent dialog shows the setup for each common agent with your address filled in: pick the agent under Setup for common agents.

OpenClaw and Hermes

The managed OpenClaw and Hermes integrations index the agent's conversations in Omnesis, send its questions to /mcp, and deliver finished answers back to the conversation that asked. Their inboxes and conversation routing survive restarts. The gateway states which tools it offers, and omnesis connect installs only those.

What the agent can use

The agent asks questions with omnesis_answer, whatever its connection's access level. When the level grants Direct or Notes, the plugin also offers those tools, named omnesis_ followed by the gateway's tool name: omnesis_list_tables, omnesis_run_sql, omnesis_add_note and the rest. It offers exactly the tools the gateway lists for the connection, with the gateway's descriptions, and forwards each call to the same tool on /mcp, so a source-restricted Direct permission gets its restricted set. They are available in conversations, scheduled runs and watch runs alike. omnesis_add_note takes the same UUID id as any other client, and a retry reuses it.

OpenClaw re-reads the connection's tools every few minutes, so a change to its access level reaches new runs without a restart. Hermes reads them when it starts: after granting Direct or Notes to a Hermes connection, restart it with hermes gateway restart. A tool the level no longer grants is refused by the gateway either way. Each plugin keeps the last list it read, so a restart while the gateway is unreachable keeps the tools it had.

Install

Make the gateway reachable from the machine that runs the agent at an address it accepts for sign-in (see Choose the address), then run one line on that machine. The installer's --openclaw and --hermes roles install the CLI and connect the agent in a single step; the gateway's own install printed this line with its URL and certificate fingerprint. Mint the pairing code it asks for with omnesis devices pair --kind agent, or in the portal under Settings → Devices. The role refuses a machine that does not already have OpenClaw or Hermes; it never installs them for you. The portal writes this line for you: under Settings → Access, open Connect an agent, choose OpenClaw or Hermes, and create a pairing code there. The command it shows carries the gateway's address, the code and, where the gateway serves that address itself, its certificate fingerprint.

On a machine that already runs Omnesis, such as one with a collector, the role installs nothing: it connects with the omnesis command already there and leaves the checkout, its services and the keyring as they are. When that command is too old to run this connect, the role offers to run omnesis update first, which restarts the services and rolls back on failure; without a terminal to ask on, it stops and says to run it. The role never touches the keyring: the agent keeps its credentials in its own home.

On a machine that already has the Omnesis CLI, the same work is one command. The role runs it for you; run it yourself to see each step:

The command finds the agent's installation, installs its Omnesis plugin and skill, establishes TLS trust, pairs the machine as an agent device, and starts the OAuth sign-in. Pass --gateway-url and --code to answer its questions up front, and --trust-fingerprint sha256:… to check the gateway's certificate against a fingerprint you were given instead of trusting whatever answers. It then waits up to ten minutes for you to approve the connection, so leave it running until it finishes.

The agent reads its plugins when it starts, so once the plugin is installed connect restarts it with openclaw gateway restart or hermes gateway restart. On a terminal it asks first, because the restart interrupts any run the agent is in the middle of; --yes restarts without asking, and --no-restart prints the command instead. Without a terminal and without --yes, it prints the command; the installer roles, which run it for you, pass --yes when they have no terminal to ask on. It then asks the agent whether the Omnesis skill is ready and says so, naming what to run when it is not. A new session picks the skill up.

OpenClaw releases that ask for consent before installing a plugin that declares capabilities get it from connect: running the command is the request to install the Omnesis plugin, so it accepts that plugin's declared capabilities and prints a line saying so. A refresh and omnesis update do the same. Older OpenClaw releases have no such step.

connect warns when the plugin it is about to install differs in version from the gateway. Omnesis versions all its parts together, so the usual cause is an agent machine that updates on its own schedule.

Refresh after an update

After updating Omnesis, refresh the installed plugin and skill in place; the refresh restarts OpenClaw or Hermes the way a first connect does. Re-running the installer role with neither --gateway-url nor --code does the same.

A refresh keeps the paired device, repairs the sign-in when needed, and uses no pairing code. It also re-establishes TLS trust, so a renewed gateway certificate needs a refresh, not a new pairing. When a refresh does need a new approval, the approval screen suggests replacing the integration's existing connection, which keeps its name and access level.

omnesis update refreshes the plugin for you, and a fleet update restarts the agent's gateway too; Fleet update covers the restart order. A refresh that failed shows in omnesis devices list and omnesis doctor with the command that fixes it, and as a chip on the portal's Devices page.

Reconnect or reinstall

A machine that is connected and only needs a newer plugin uses a refresh, which spends no pairing code. To pair it again, for example after reinstalling the harness over its existing Omnesis files, run the command from the Connect an agent card with a new pairing code. The machine proves it is the same installation with the credentials it already holds, so the gateway keeps the same agent device: its watches, conversations, and access stay bound to it. The device gets new credentials and its old ones stop working. The command offers those credentials only to the gateway that issued them, recognized by the certificate the machine pinned, or by its address when this run verified the certificate against --trust-fingerprint, as the card's commands do.

When OpenClaw or Hermes is already connected, the card asks what the code is for. Reconnect binds the code to that device and replaces its credentials on whichever machine runs the command. Use it when the machine's saved Omnesis files are gone, when the device was revoked, or to move the device to a replacement machine. A code bound to a device that is still connected is refused unless the machine running it holds that device's credentials; otherwise stop the harness where it runs, or revoke the device, first. Connect another machine pairs a separate device. A bound code comes from the command line as well: omnesis devices pair --kind agent --repair-device <device-id>.

An unbound code never takes over an existing device without those credentials. A machine that kept its Omnesis identity but lost its credentials is refused, and the command names the card's Reconnect choice. A machine with no Omnesis files left pairs as a new device; to keep the old one, create the code with Reconnect instead.

Pairing and corpus access

The installed plugin renews its sign-in on its own, on start and on a timer. Renewal re-keys the connection you approved and cannot widen it, so removing that connection ends reads at once. When the integration does need you, omnesis devices list and the portal's Devices page mark it needs re-authorization and print the command to run on that machine.

Custom agents

An agent that does not speak MCP can use the answer API above, or call the gateway's HTTPS read API directly. The read endpoints cover search, documents, people, event trails, recent records, and bounded SQL, and enforce the scopes of the token presented. This is lower-level than an MCP connection: nothing reviews the results, and your agent owns its request flow, its citations, and any data it sends to a model. The commands on Search are thin clients over these endpoints and a good place to start. Mint a token with only the scopes it needs, as described under Tokens.