Give your AI your whole life. Keep your private things private. Olympus runs on your Mac or Omarchy computer and works with ChatGPT, Claude, Grok, Codex, Claude Code and any app that speaks MCP.
See the code
Your whole digital life, searchable by your AI — on your privacy terms.
A private knowledge engine on your Mac for ChatGPT, and a sovereignty-aware source brain for OpenClaw agents.
Olympus for ChatGPT · OpenClaw quickstart · Release status · Source capabilities · How it works · Sources · Security model · Commands
🤖 Installing this as an AI agent for OpenClaw? Stop and read INSTALL_FOR_AGENTS.md before running any command — it is the step-by-step runbook you must follow, including exactly what to tell your operator after each step (your install report must end with the Step 1→2 invitation, never a bare status line). Managed
git:,clawhub:, andnpm-pack:installs intentionally hide their internal package path; use the installedolympusCLI and this packaged runbook rather than searching OpenClaw's managed storage. Setting up Olympus for ChatGPT instead? Follow Olympus for ChatGPT and the plugin's own setup skill, not this runbook.
Personal AI becomes genuinely useful when it can reason across your whole life — email, messages, files, notes, reading. It becomes trustworthy when you decide which models are allowed to see which parts of it.
Olympus is both. It ingests your sources into local, trust-tiered indexes, then lets your frontier agent answer questions across all of them — with sensitive material handled only by lanes you approved: your own local models, privacy-approved private cloud inference, or not at all.
you › "What did I commit to this week, across email and Telegram?"
agent › Three commitments: the tax documents to Maria by Friday
(email, Tue), reviewing the lease amendment (email, Mon),
and the Saturday ride logistics (Telegram, Wed). [3 citations]
Your agent saw a bounded, cited, policy-gated answer. It never saw your mailbox.
Olympus 1.0 is a ChatGPT plugin. The Olympus engine runs on your Mac and keeps your index there; ChatGPT asks it questions through one secure connection that you approve on the Mac. You need ChatGPT and a Mac with Apple silicon (M1 or later) on macOS 13 Ventura or later; Intel Macs are not supported. You do not need OpenClaw, Tailscale, an API key or a new account.
Open Terminal and run:
curl -fsSL https://olympusplugin.ai/install.sh | sh
It installs Olympus for your macOS user only (no administrator password),
checks every download against a pinned SHA-256 before using it, runs
Olympus in the background as a login item (a LaunchAgent), adds the
olympus command, and waits until the engine proves it is running. Then
Olympus downloads its built-in models once. Running it again updates or
repairs the install; a failed update puts the previous version back.
Details, folders and uninstall: https://olympusplugin.ai/install/.
In the ChatGPT desktop app, add Olympus from the plugin directory and ask "Connect Olympus". ChatGPT's setup skill shows the same install command if Olympus is not on the Mac yet; it never runs commands itself.
The first time ChatGPT connects to Olympus, an Olympus page opens in your
Mac's browser asking Connect ChatGPT to Olympus? Click Connect. (If a
page saying Approve ChatGPT on your Mac comes first, click Continue on
this Mac.) Clicking Connect on your own Mac is how Olympus knows the Mac is
yours: there is no code to copy and no account to create. To check on it later, run olympus engine status in Terminal.
Open the Olympus dashboard in ChatGPT's sidebar (or ask "Show my Olympus dashboard"). Choose Connect next to Dropbox and sign in with your own Dropbox account; the sign-in link works once, for 10 minutes, from any device. Gmail and Google Drive connect the same way.
Then pick folders. For each folder choose:
A folder follows its parent's choice unless you change it; Mixed means some folders inside it are set differently. Choose Save and start, and indexing begins on your Mac.
Olympus sorts every item, one by one, into one of three tiers:
Olympus decides on your Mac. Once its built-in private model is ready, it checks every item it reads before treating it as Personal. In the dashboard, Privacy asks "What's private for you?": answer in your own words. You can also mark folders, Gmail labels or senders as always Private.
Ask in ChatGPT the way you normally would: "What did Sam say about the lease?" ChatGPT searches Olympus and answers from your Personal items, with citations.
When some of the items that match your question are Private, a small Olympus panel appears on its own under ChatGPT's reply: Private answer from your Mac, marked Not sent to ChatGPT.
Your Mac needs to be awake and online. The panel runs inside ChatGPT's page, so it relies on the panel code ChatGPT loads; the design states that limit plainly.
ChatGPT can see:
ChatGPT can't see:
The relay at mcp.olympusplugin.ai passes ChatGPT's requests to your Mac. It
stores and logs no questions, answers or tokens, but like any HTTPS service
it handles them in transit. Full details: the
ChatGPT design and the
trust model.
To uninstall, run curl -fsSL https://olympusplugin.ai/uninstall.sh | sh:
it stops Olympus and removes the app, the runtime and the olympus command,
and keeps your settings and data. To delete those too, first run
olympus engine stop and olympus data delete --all. To only stop Olympus
and remove its login item, run olympus engine uninstall.
The rest of this README covers Olympus with OpenClaw, which stays supported and optional.
Every item you ingest is judged on its own as Personal, Private, or Secrets (plus Public where the posture keeps it; internally S0-S5): its names are Personal unless something raises them, and its content is raised to Private or Secrets on evidence. Each tier has its own index and routes only to the model lanes your sovereignty policy allows:
flowchart LR
subgraph sources["Your sources"]
direction TB
SRC1[Gmail · Drive · Dropbox]
SRC2[Telegram · WhatsApp · X]
end
subgraph olympus["Olympus (local)"]
direction TB
ING[Ingest & classify<br/>every item, locally]
IDX[(Trust-tiered<br/>local indexes)]
POL{{Sovereignty policy<br/>your rules, enforced}}
ING --> IDX --> POL
end
subgraph lanes["Model lanes you approved"]
direction TB
CLOUD[Frontier cloud<br/>everyday content]
PRIVATE[Venice<br/>Private content when routed]
LOCAL[Your local models<br/>Private content]
end
AGENT[Your agent<br/>cited, bounded answers]
sources --> ING
POL --> CLOUD & PRIVATE & LOCAL
CLOUD & PRIVATE & LOCAL --> AGENT
Olympus uses Personal (ordinary personal and work content), Private
(sensitive material), and Secrets (never model input). A ChatGPT
install, and any install on the no-sensitive posture, has no Public tier:
anything that would have been Public is Personal. The other OpenClaw
postures, and installs made before 1.0, keep a Public tier too. See the
tier mapping for the unchanged
storage identifiers.
Four postures, chosen (and changeable) in setup — a config file, not a code fork:
| Preset | Public/Personal content | Private content: health, finance, legal, therapy, family |
|---|---|---|
Local models and private cloud (local-first) | frontier cloud | approved secure pool with explicit local → Venice Private order |
Local models only (local-only) | frontier cloud | your own local models only |
Private cloud only (private-cloud-only) | frontier cloud | Venice Private model (kimi-k3) |
Do not add secure data to Olympus (no-sensitive) | frontier cloud | not ingested — reported as an honest gap |
“Private cloud only” describes Private-data handling: Venice answers Private questions. Search indexing for every tier uses EmbeddingGemma 2, Google's small embedding model, built into Olympus: it downloads once, runs on your computer, needs no account or key, and sends nothing anywhere. On a Mac it also reads pictures, so photos are searchable by what is in them. Gemini, local, or Venice Private embeddings stay an opt-in choice, and Private content never goes to Gemini. Public and Personal questions use OpenClaw's own configured default model.
One question searches every tier. When it finds Private evidence, the private lane your posture approved answers it and your agent receives only the checked, cited answer. Secrets are never searched by content: Olympus can tell you where one lives, never what it says.
Some rules are not configurable, by design: secure content never routes to ordinary cloud models, secrets are denied to every lane, and an exhausted policy chain refuses rather than silently downgrading.
Using ChatGPT? See Olympus for ChatGPT instead; none of this section is needed.
You need OpenClaw 2026.7.1+ on a Node release OpenClaw itself supports
(>=24.16.0 <25 or >=26.1.0 for OpenClaw 2026.9.5; check
npm view openclaw engines — its installer refuses any other), plus
Bun 1.2+. macOS or Linux.
Paste this into OpenClaw, or another agent with a terminal:
Install Olympus by reading https://raw.githubusercontent.com/jamiezigelbaum/Olympus/main/INSTALL_FOR_AGENTS.md and following it step by step. Walk me through setup and ask me about my data and privacy preferences.
Your agent downloads the designated pilot package, checks it automatically, and guides you through setup. You do not need to download files, find a checksum receipt, or have a GitHub account. The agent checks the SHA-256 and byte count against the designated candidate and GitHub's release metadata.
openclaw plugins install clawhub:olympus becomes the one-line public path
once Olympus is published to ClawHub, which happens after the pilot. The
pilot and release qualification both use the managed npm-pack: path — see
docs/V0_4_RELEASE.md. A Git checkout or rebuilt package
does not qualify the supplied candidate.
--accept-capabilities is required by OpenClaw 2026.8.1+: an agent-driven
install is non-TTY, and without the flag the host exits 1 asking for capability
consent it cannot prompt for. Omit the flag on 2026.7.1, which does not
define it.
The agent checks prerequisites, installs the plugin, talks through what is private for you (you save it later in the dashboard's Privacy section), asks for your privacy posture and your approval of the private classifier, verifies the worker, restarts the gateway, and hands you the dashboard. You paste your model keys into its Models section yourself; the agent never collects them. That completes base installation. Then you can choose a source in the dashboard or leave Olympus ready for later; no source is selected for you. Once your chosen source is ready, the agent checks a first answer and its citations.
Prefer to drive it yourself? Follow docs/QUICKSTART.md, starting with the automatic download and existing-install checks. Its install command for a clean machine is:
openclaw plugins install npm-pack:/absolute/path/to/olympus-1.0.0-rc.6.tgz --force --accept-capabilities
# On OpenClaw 2026.7.1, omit both flags for a clean install.
# On newer hosts, --force also overwrites an existing plugin: check first.
openclaw plugins enable olympus
OLYMPUS_ROOT="$(openclaw plugins inspect olympus --json | jq -r .plugin.rootDir)"
OLYMPUS_BIN="$OLYMPUS_ROOT/bin/olympus"
"$OLYMPUS_BIN" doctor
Continue the quickstart to describe your data, choose a privacy posture, connect model credentials, and verify base activation before choosing your sources in the dashboard and checking the first cited answer. The CLI lives inside the managed plugin; use the resolved executable rather than assuming it is on PATH.
This candidate artifact includes native Control UI support. On OpenClaw
2026.9.2, use Olympus in the Control UI sidebar to connect
sources, choose scope, and follow ingestion. Enable Settings → Labs → Custom
plugin UI (the Gateway restarts itself to apply it on OpenClaw 2026.9.5; run
no second restart), then reload the browser. OpenClaw currently makes this integration experimental
and requires its own Gateway's Control UI over HTTPS or localhost. Olympus uses
your signed-in OpenClaw permissions; its worker token stays on the server.
The standalone olympus dashboard command remains available for older hosts,
when custom plugin UI is off, and for direct access when needed. See the
dashboard guide.
For Gemini embeddings, Venice accounts/API credit, or local models, use the
agent-led model setup guide.
It explains the separate Private and Public/Personal routes, registered embedding
defaults, and custom-model requirements before you connect keys or restart.
In the dashboard you paste each key into its Models card. For a headless
setup, choose how to supply each key: paste it yourself from your password
manager's website into the silent terminal input, or authorize an
exact named-item read through an already authenticated manager CLI. The manual
route needs no password-manager desktop app or CLI; a 1Password op://
reference needs authenticated op access for an agent fetch.
On OpenClaw 2026.9.2, use Olympus in the Control UI sidebar when the installed
Olympus artifact includes native Control UI support and Custom plugin UI is
enabled. Host version alone is not proof of support. Otherwise the quickstart
uses the retained standalone dashboard; it explains the different authentication
requirements for each route.
| Source | Connect flow | Notes |
|---|---|---|
| Gmail | browser OAuth | one account |
| Google Drive | browser OAuth | docs + files |
| Dropbox | browser OAuth | full file spine: metadata, extraction, OCR, audio transcribed on your machine |
| Telegram | guided phone login | forward sync of active chats |
| QR pairing | live bridge | |
| X bookmarks | browser OAuth with a user-owned developer app | folder provenance and provider cost ceilings |
| Readwise | API key | optional |
Model-lane credentials such as Venice are security-preset prerequisites, not source connectors. Domain-agent imports and other source families are outside the 1.0 public roster.
Tokens live in an encrypted local secret store by default, or in an explicitly
configured OS secret store when supported, never in plain text.
Ingestion, classification, and indexing all run in one supervised local
worker — olympus worker install makes it start on login. All seven declared
sources sync through the canonical connector-store runtime; Olympus supports one
connected account per provider. After base activation, dashboard onboarding
guides the source you choose from credentials and scope through initial sync
and cited-answer readiness, with the next supported action on blocked or
degraded sources. The seven-source roster is not an installation checklist.
Clean-install and real-provider qualification remain Slice 4 work, not alternate ingestion
paths.
On an existing live OpenClaw install, treat plugin install/enable, gateway
restart, worker service changes, and plugin refresh as live-system changes:
validate with openclaw config validate and openclaw doctor --lint, then
restart only through openclaw gateway restart or the documented ops refresh
script. The repo docs and commands should never require raw edits to
OpenClaw runtime config.
Olympus is built on the assumption that the boundary is the product:
raw_source_exposed: false, re-validated
client-side. Raw documents, embeddings, cursors, and tokens never cross.olympus data export gives you your data;
olympus data delete --all verifiably removes indexes, embeddings,
configs, tokens, and service units.The onboarding flow, end to end:
flowchart LR
A[Install<br/>plugin] --> B[olympus setup<br/>pick your posture]
B --> C[olympus connect<br/>OAuth IDs · session paths · API-key stdin]
C --> D[Dashboard<br/>watch it ingest]
D --> E[Ask your agent<br/>cited answers]
| Command | What it does |
|---|---|
olympus setup --preset <preset> --yes | writes sovereignty policy and worker auth for the chosen posture |
olympus connect <source> ... | records OAuth, session, or API-key credentials with source-specific flags |
olympus worker foreground|install|start|stop|restart|status|upgrade|uninstall | one versioned lifecycle for the local engine, foreground or supervised |
olympus dashboard | opens the standalone dashboard with a short-lived authorization link; no worker-token copying |
olympus dashboard --no-open | generates an unused opening link for an agent to hand to you |
olympus dashboard token | advanced compatibility access to the worker bearer; never share it in chat |
olympus source answer "…" | ask across your sources from the terminal |
olympus ask "…" [--level strict|standard] | one question to a frontier model anonymously through zkAPI (paid from your zkAPI balance; the question only) |
olympus tier explain|set|rules|classifier … | why an item has its tier, owner overrides and rules, and the private classifier's approval |
olympus tier migrate plan|approve|run|rollback|purge|status | moves an existing install's items into per-item tiers, each step owner-approved after a dry-run plan |
olympus doctor | diagnoses problems, each with a fix-it hint |
olympus data export|delete | your data, out — or gone |
olympus serve | MCP stdio server for non-OpenClaw agents |
olympus worker install and upgrade atomically reconcile the generated
service unit and owner-only worker environment before activation. Interrupted
install or upgrade transactions recover the previous managed files when the
same command is rerun. status reports the observed service and transaction
state; it never guesses that an unreadable manager or non-regular managed path
is healthy. uninstall removes only the supervised service and intentionally
retains credentials, source configuration, and indexed data. Use the separate
data lifecycle when those bytes should also be removed.
Credential, scope, pairing, Disconnect, partial-sync, and source-dependency
repairs do not normally require a worker restart. Follow the source card or
olympus doctor recovery action instead.
Dashboard Disconnect stops new scheduled and manual reads, removes the
selected local account grant, and keeps indexed data and reusable developer-app
registration. It does not revoke provider-side access; the card links the
provider revocation page. Local data deletion remains the deliberate CLI-only
flow: preview olympus data delete --source <id> --dry-run, Disconnect the
source, then run the command without --dry-run.
Telegram and WhatsApp are paired sessions rather than broker grants, so their cards carry Unpair instead: it stops new reads and deletes this computer's pairing session, keeping indexed messages and captured media, and leaves the linked device in place at the provider for you to remove there.
Open the dashboard on this computer (olympus dashboard). Under On this
computer, choose Open next to Agents, then press Connect an
agent. Pick the agent you use and follow its steps; every address and
snippet has a copy button.
olympus serve command) into the agent. This works without remote access.Agents in the cloud reach Olympus only when remote access is on; the Agents
page says whether it is. To turn it on, press Turn on remote access
there. Olympus then connects through the Olympus relay
(mcp.olympusplugin.ai): you create no account and run no tunnel. The relay
passes requests between your agents and this computer; it stores and logs no
questions, answers or tokens, but like any HTTPS endpoint it handles them in
transit. The relay connects ChatGPT, Claude, Grok (grok.com) and Grok Bot,
and approving one happens on this computer only, with one click on a page
Olympus serves locally; there is no pairing code. A Claude connector
approved on this computer then works in Claude on your phone too.
Turn off remote access turns it off again. If the
relay cannot be reached, the page says Olympus relay unavailable and
Olympus keeps retrying on its own; agents on this computer are unaffected.
Advanced: to use a tunnel you run yourself instead of the relay, set
plugins.entries.olympus.config.remote.publicBaseUrl to its https origin
(openclaw config set …) and turn remote access on. Through your own tunnel,
Claude, ChatGPT and Grok approve Olympus on its approval page with a one-time
pairing code from the Agents page, and the Grok API takes an address plus a
key from Create key (shown once).
Every connected agent gets the same privacy rules
as your OpenClaw agent. It never sees Private source text or Secrets. For
Private items it receives only answers that Venice or a local model reasoned
out, with each item's title, path, source and author. The Agents page
lists connected agents with when each was added and last used, and
Revoke removes one. olympus connections list|revoke|pair|add does the
same from a terminal.
Each agent's steps end with a short instruction that tells it when to ask
Olympus. Paste it into Claude project instructions, Grok's custom
instructions or Grok Bot's skills, or
load the packaged Agent Skills folder
integrations/agent-skills/ask-olympus/.
olympus serve exposes the same sanitized read operations — source_answer,
source_answer_result, source_index_status, capability-gated
source_index_search, and ask_anonymously — to any MCP-capable agent. The
supported Hermes configuration narrows that server to exactly source_answer,
source_answer_result, source_index_status and ask_anonymously through its
per-server tool allowlist.
ask_anonymously sends one typed question to a frontier model through zkAPI
(paid per question from the user's own balance; nothing identifies them). The
first call with no level returns needs_choice: the agent asks the user once
for Strict (their own model rewrites the question into general questions before
it leaves) or Standard (their words, prepared as written, lightly cleaned up or
by their saved instruction), then calls again with level and remember: true.
Only the question goes out, never documents, and never to the provider that
hosts the agent asking: a question from ChatGPT goes to Claude Sonnet by
default, one from Claude Code or Claude Desktop to an OpenAI model, and a
one-off model from the agent's own provider is refused. Setup (the zkAPI
route, the writer model, the zkAPI models for questions from ChatGPT and from
Claude, the spend limit) lives on the dashboard's Anonymous answers card, which
is for setup only: questions are asked through an agent (or olympus ask); see
docs/design/private-answers.md.
MCP clients cap how long one tool call may run, and an answer can take several
minutes. So over MCP (local olympus serve and remote /mcp alike) and the
OpenAPI tool paths, a source_answer that is not done by a hand-off threshold
returns {"status": "working", "job_id": …} and keeps running. The threshold
is 200 seconds for remote agents (OLYMPUS_SOURCE_ANSWER_HANDOFF_MS) and 45
seconds for local olympus serve (OLYMPUS_SOURCE_ANSWER_STDIO_HANDOFF_MS,
under Codex's 60-second default tool timeout); both are capped at 230000.
source_answer_result with that job_id returns the answer, the same error
the call would have raised, or working again after waiting up to a minute
(never longer than the threshold). A slow ask_anonymously (a Tor route can
take minutes) hands off the same way and is collected with the same tool. A job that runs past 20 minutes is stopped
with source_answer_deadline, and revoking a connection drops its jobs.
Remote answers share the analyst with your own assistant's answers; there is
no priority lane. So the worker runs at most two remote answers at once (the
analyst's lane count; OLYMPUS_SOURCE_ANSWER_MAX_RUNNING raises it for a
multi-lane analyst) and refuses more with source_answer_busy, which bounds
how much remote work can ever queue ahead of your own question. A caller that
disconnects, or a job that reaches its deadline, stops the analyst call
itself and frees the lane. A job id is readable
only by the connection (or olympus serve process) that asked, lives in
memory, and expires 15 minutes after its answer is ready.
For Hermes Agent, resolve the installed plugin first:
openclaw plugins inspect olympus --json
Copy plugin.rootDir from that content-free response, append /bin/olympus,
and pass the resulting absolute executable path to Hermes:
hermes mcp add olympus --command /absolute/managed/olympus/bin/olympus --args serve
hermes mcp test olympus
Make the olympus server entry in ~/.hermes/config.yaml match the packaged
config/hermes/olympus.mcp.yaml:
mcp_servers:
olympus:
command: <absolute-managed-plugin-root>/bin/olympus
args: [serve]
tools:
include: [source_answer, source_answer_result, source_index_status, ask_anonymously]
prompts: false
resources: false
Restart Hermes or run /reload-mcp, then verify that the discovered registered
names are exactly mcp_olympus_source_answer,
mcp_olympus_source_answer_result, mcp_olympus_source_index_status and
mcp_olympus_ask_anonymously. Invoke the discovered names rather than
hard-coding them. A cited-answer round trip uses the discovered
mcp_olympus_source_answer; source_watch_* remains OpenClaw-only.
The optional packaged Hermes skill is
integrations/hermes/ask-sources/SKILL.md.
Copy its directory to ~/.hermes/skills/ask-sources/ or expose the parent with
skills.external_dirs; it declares the same four tools and no fallback access.
No hermes://mcp/install link is published: current Hermes upstream documents
custom MCP installation through hermes mcp add but does not document that URI
handler. No Nous catalog submission has been made; that remains a later,
separately reviewed external action.
There are no operator agent tools. Index maintenance — sync, extraction,
embedding, retries — is the worker's own scheduler, and what a person drives by
hand goes through the olympus CLI. The whole agent tool surface is twelve tools —
argus_ping, argus_list_models, argus_complete, source_answer,
source_answer_result (MCP and remote only), source_index_status, source_index_search, source_watch_create,
source_watches, source_watch_cancel, olympus_doctor, ask_anonymously — declared in
src/core/public-surface.ts; Hermes over MCP sees
the subset above, and worker bearer auth is enforced throughout.
Operational note for connector-store corpora: run the matching sync script
first, then mount the same SQLite store in the source worker with
OLYMPUS_SOURCE_INDEX_CONNECTOR_STORES_JSON. The worker env entry must use
the same corpus id, family, trustDomain, and dbPath the sync script
writes, and that corpus id must be in the corpus registry — a store mounted
for an unregistered corpus fills but is never read.
Chat-family mounts must also declare their exact principal identity with
principalProvider and principalAccountScope (for example, whatsapp and
personal). Structured scopes use the stored account scope as their prefix, so
the shipped WhatsApp identity is personal:chat:<id> while Telegram remains
telegram.personal:chat:<id>. A chat mount without both fields remains
available for non-chat_scope reads, but chat_scope filtering fails closed
as not configured; mounted rows never establish account authority.
The migration-era indexes, replay/import utilities, read-authority switches, and retired store writers were removed in Slice 2. Canonical connector stores are now the only source read/write authority. Compatibility aliases that remain at input boundaries do not select another runtime or store.
Olympus is TypeScript on Bun: one plugin package, stable versioned architecture
contracts (SourceConnector / EvidencePack / Analyst — only the
connector is per-source), and 1,400+ tests including an architecture guard
that keeps per-source answer logic out of the shared spine.
bun install
bun run test:focus -- test/example.test.ts
Use focused local proof while editing; GitHub requires each substantive CI lane and runs the complete suite in parallel before merge. See the canonical engineering process.
Deep-dive docs: contracts and architecture · trust model · sovereignty config · uninstall
MIT — free for any use, including commercial.
Want to suggest a change? See CONTRIBUTING.md: fork, branch, open a PR. Read access doesn't include direct pushes — everything lands through review.
Give your AI your whole life. Keep your private things private. Olympus runs on your Mac or Omarchy computer and works with ChatGPT, Claude, Grok, Codex, Claude Code and any app that speaks MCP.
See the code
Your whole digital life, searchable by your AI — on your privacy terms.
A private knowledge engine on your Mac for ChatGPT, and a sovereignty-aware source brain for OpenClaw agents.
Olympus for ChatGPT · OpenClaw quickstart · Release status · Source capabilities · How it works · Sources · Security model · Commands
🤖 Installing this as an AI agent for OpenClaw? Stop and read INSTALL_FOR_AGENTS.md before running any command — it is the step-by-step runbook you must follow, including exactly what to tell your operator after each step (your install report must end with the Step 1→2 invitation, never a bare status line). Managed
git:,clawhub:, andnpm-pack:installs intentionally hide their internal package path; use the installedolympusCLI and this packaged runbook rather than searching OpenClaw's managed storage. Setting up Olympus for ChatGPT instead? Follow Olympus for ChatGPT and the plugin's own setup skill, not this runbook.
Personal AI becomes genuinely useful when it can reason across your whole life — email, messages, files, notes, reading. It becomes trustworthy when you decide which models are allowed to see which parts of it.
Olympus is both. It ingests your sources into local, trust-tiered indexes, then lets your frontier agent answer questions across all of them — with sensitive material handled only by lanes you approved: your own local models, privacy-approved private cloud inference, or not at all.
you › "What did I commit to this week, across email and Telegram?"
agent › Three commitments: the tax documents to Maria by Friday
(email, Tue), reviewing the lease amendment (email, Mon),
and the Saturday ride logistics (Telegram, Wed). [3 citations]
Your agent saw a bounded, cited, policy-gated answer. It never saw your mailbox.
Olympus 1.0 is a ChatGPT plugin. The Olympus engine runs on your Mac and keeps your index there; ChatGPT asks it questions through one secure connection that you approve on the Mac. You need ChatGPT and a Mac with Apple silicon (M1 or later) on macOS 13 Ventura or later; Intel Macs are not supported. You do not need OpenClaw, Tailscale, an API key or a new account.
Open Terminal and run:
curl -fsSL https://olympusplugin.ai/install.sh | sh
It installs Olympus for your macOS user only (no administrator password),
checks every download against a pinned SHA-256 before using it, runs
Olympus in the background as a login item (a LaunchAgent), adds the
olympus command, and waits until the engine proves it is running. Then
Olympus downloads its built-in models once. Running it again updates or
repairs the install; a failed update puts the previous version back.
Details, folders and uninstall: https://olympusplugin.ai/install/.
In the ChatGPT desktop app, add Olympus from the plugin directory and ask "Connect Olympus". ChatGPT's setup skill shows the same install command if Olympus is not on the Mac yet; it never runs commands itself.
The first time ChatGPT connects to Olympus, an Olympus page opens in your
Mac's browser asking Connect ChatGPT to Olympus? Click Connect. (If a
page saying Approve ChatGPT on your Mac comes first, click Continue on
this Mac.) Clicking Connect on your own Mac is how Olympus knows the Mac is
yours: there is no code to copy and no account to create. To check on it later, run olympus engine status in Terminal.
Open the Olympus dashboard in ChatGPT's sidebar (or ask "Show my Olympus dashboard"). Choose Connect next to Dropbox and sign in with your own Dropbox account; the sign-in link works once, for 10 minutes, from any device. Gmail and Google Drive connect the same way.
Then pick folders. For each folder choose:
A folder follows its parent's choice unless you change it; Mixed means some folders inside it are set differently. Choose Save and start, and indexing begins on your Mac.
Olympus sorts every item, one by one, into one of three tiers:
Olympus decides on your Mac. Once its built-in private model is ready, it checks every item it reads before treating it as Personal. In the dashboard, Privacy asks "What's private for you?": answer in your own words. You can also mark folders, Gmail labels or senders as always Private.
Ask in ChatGPT the way you normally would: "What did Sam say about the lease?" ChatGPT searches Olympus and answers from your Personal items, with citations.
When some of the items that match your question are Private, a small Olympus panel appears on its own under ChatGPT's reply: Private answer from your Mac, marked Not sent to ChatGPT.
Your Mac needs to be awake and online. The panel runs inside ChatGPT's page, so it relies on the panel code ChatGPT loads; the design states that limit plainly.
ChatGPT can see:
ChatGPT can't see:
The relay at mcp.olympusplugin.ai passes ChatGPT's requests to your Mac. It
stores and logs no questions, answers or tokens, but like any HTTPS service
it handles them in transit. Full details: the
ChatGPT design and the
trust model.
To uninstall, run curl -fsSL https://olympusplugin.ai/uninstall.sh | sh:
it stops Olympus and removes the app, the runtime and the olympus command,
and keeps your settings and data. To delete those too, first run
olympus engine stop and olympus data delete --all. To only stop Olympus
and remove its login item, run olympus engine uninstall.
The rest of this README covers Olympus with OpenClaw, which stays supported and optional.
Every item you ingest is judged on its own as Personal, Private, or Secrets (plus Public where the posture keeps it; internally S0-S5): its names are Personal unless something raises them, and its content is raised to Private or Secrets on evidence. Each tier has its own index and routes only to the model lanes your sovereignty policy allows:
flowchart LR
subgraph sources["Your sources"]
direction TB
SRC1[Gmail · Drive · Dropbox]
SRC2[Telegram · WhatsApp · X]
end
subgraph olympus["Olympus (local)"]
direction TB
ING[Ingest & classify<br/>every item, locally]
IDX[(Trust-tiered<br/>local indexes)]
POL{{Sovereignty policy<br/>your rules, enforced}}
ING --> IDX --> POL
end
subgraph lanes["Model lanes you approved"]
direction TB
CLOUD[Frontier cloud<br/>everyday content]
PRIVATE[Venice<br/>Private content when routed]
LOCAL[Your local models<br/>Private content]
end
AGENT[Your agent<br/>cited, bounded answers]
sources --> ING
POL --> CLOUD & PRIVATE & LOCAL
CLOUD & PRIVATE & LOCAL --> AGENT
Olympus uses Personal (ordinary personal and work content), Private
(sensitive material), and Secrets (never model input). A ChatGPT
install, and any install on the no-sensitive posture, has no Public tier:
anything that would have been Public is Personal. The other OpenClaw
postures, and installs made before 1.0, keep a Public tier too. See the
tier mapping for the unchanged
storage identifiers.
Four postures, chosen (and changeable) in setup — a config file, not a code fork:
| Preset | Public/Personal content | Private content: health, finance, legal, therapy, family |
|---|---|---|
Local models and private cloud (local-first) | frontier cloud | approved secure pool with explicit local → Venice Private order |
Local models only (local-only) | frontier cloud | your own local models only |
Private cloud only (private-cloud-only) | frontier cloud | Venice Private model (kimi-k3) |
Do not add secure data to Olympus (no-sensitive) | frontier cloud | not ingested — reported as an honest gap |
“Private cloud only” describes Private-data handling: Venice answers Private questions. Search indexing for every tier uses EmbeddingGemma 2, Google's small embedding model, built into Olympus: it downloads once, runs on your computer, needs no account or key, and sends nothing anywhere. On a Mac it also reads pictures, so photos are searchable by what is in them. Gemini, local, or Venice Private embeddings stay an opt-in choice, and Private content never goes to Gemini. Public and Personal questions use OpenClaw's own configured default model.
One question searches every tier. When it finds Private evidence, the private lane your posture approved answers it and your agent receives only the checked, cited answer. Secrets are never searched by content: Olympus can tell you where one lives, never what it says.
Some rules are not configurable, by design: secure content never routes to ordinary cloud models, secrets are denied to every lane, and an exhausted policy chain refuses rather than silently downgrading.
Using ChatGPT? See Olympus for ChatGPT instead; none of this section is needed.
You need OpenClaw 2026.7.1+ on a Node release OpenClaw itself supports
(>=24.16.0 <25 or >=26.1.0 for OpenClaw 2026.9.5; check
npm view openclaw engines — its installer refuses any other), plus
Bun 1.2+. macOS or Linux.
Paste this into OpenClaw, or another agent with a terminal:
Install Olympus by reading https://raw.githubusercontent.com/jamiezigelbaum/Olympus/main/INSTALL_FOR_AGENTS.md and following it step by step. Walk me through setup and ask me about my data and privacy preferences.
Your agent downloads the designated pilot package, checks it automatically, and guides you through setup. You do not need to download files, find a checksum receipt, or have a GitHub account. The agent checks the SHA-256 and byte count against the designated candidate and GitHub's release metadata.
openclaw plugins install clawhub:olympus becomes the one-line public path
once Olympus is published to ClawHub, which happens after the pilot. The
pilot and release qualification both use the managed npm-pack: path — see
docs/V0_4_RELEASE.md. A Git checkout or rebuilt package
does not qualify the supplied candidate.
--accept-capabilities is required by OpenClaw 2026.8.1+: an agent-driven
install is non-TTY, and without the flag the host exits 1 asking for capability
consent it cannot prompt for. Omit the flag on 2026.7.1, which does not
define it.
The agent checks prerequisites, installs the plugin, talks through what is private for you (you save it later in the dashboard's Privacy section), asks for your privacy posture and your approval of the private classifier, verifies the worker, restarts the gateway, and hands you the dashboard. You paste your model keys into its Models section yourself; the agent never collects them. That completes base installation. Then you can choose a source in the dashboard or leave Olympus ready for later; no source is selected for you. Once your chosen source is ready, the agent checks a first answer and its citations.
Prefer to drive it yourself? Follow docs/QUICKSTART.md, starting with the automatic download and existing-install checks. Its install command for a clean machine is:
openclaw plugins install npm-pack:/absolute/path/to/olympus-1.0.0-rc.6.tgz --force --accept-capabilities
# On OpenClaw 2026.7.1, omit both flags for a clean install.
# On newer hosts, --force also overwrites an existing plugin: check first.
openclaw plugins enable olympus
OLYMPUS_ROOT="$(openclaw plugins inspect olympus --json | jq -r .plugin.rootDir)"
OLYMPUS_BIN="$OLYMPUS_ROOT/bin/olympus"
"$OLYMPUS_BIN" doctor
Continue the quickstart to describe your data, choose a privacy posture, connect model credentials, and verify base activation before choosing your sources in the dashboard and checking the first cited answer. The CLI lives inside the managed plugin; use the resolved executable rather than assuming it is on PATH.
This candidate artifact includes native Control UI support. On OpenClaw
2026.9.2, use Olympus in the Control UI sidebar to connect
sources, choose scope, and follow ingestion. Enable Settings → Labs → Custom
plugin UI (the Gateway restarts itself to apply it on OpenClaw 2026.9.5; run
no second restart), then reload the browser. OpenClaw currently makes this integration experimental
and requires its own Gateway's Control UI over HTTPS or localhost. Olympus uses
your signed-in OpenClaw permissions; its worker token stays on the server.
The standalone olympus dashboard command remains available for older hosts,
when custom plugin UI is off, and for direct access when needed. See the
dashboard guide.
For Gemini embeddings, Venice accounts/API credit, or local models, use the
agent-led model setup guide.
It explains the separate Private and Public/Personal routes, registered embedding
defaults, and custom-model requirements before you connect keys or restart.
In the dashboard you paste each key into its Models card. For a headless
setup, choose how to supply each key: paste it yourself from your password
manager's website into the silent terminal input, or authorize an
exact named-item read through an already authenticated manager CLI. The manual
route needs no password-manager desktop app or CLI; a 1Password op://
reference needs authenticated op access for an agent fetch.
On OpenClaw 2026.9.2, use Olympus in the Control UI sidebar when the installed
Olympus artifact includes native Control UI support and Custom plugin UI is
enabled. Host version alone is not proof of support. Otherwise the quickstart
uses the retained standalone dashboard; it explains the different authentication
requirements for each route.
| Source | Connect flow | Notes |
|---|---|---|
| Gmail | browser OAuth | one account |
| Google Drive | browser OAuth | docs + files |
| Dropbox | browser OAuth | full file spine: metadata, extraction, OCR, audio transcribed on your machine |
| Telegram | guided phone login | forward sync of active chats |
| QR pairing | live bridge | |
| X bookmarks | browser OAuth with a user-owned developer app | folder provenance and provider cost ceilings |
| Readwise | API key | optional |
Model-lane credentials such as Venice are security-preset prerequisites, not source connectors. Domain-agent imports and other source families are outside the 1.0 public roster.
Tokens live in an encrypted local secret store by default, or in an explicitly
configured OS secret store when supported, never in plain text.
Ingestion, classification, and indexing all run in one supervised local
worker — olympus worker install makes it start on login. All seven declared
sources sync through the canonical connector-store runtime; Olympus supports one
connected account per provider. After base activation, dashboard onboarding
guides the source you choose from credentials and scope through initial sync
and cited-answer readiness, with the next supported action on blocked or
degraded sources. The seven-source roster is not an installation checklist.
Clean-install and real-provider qualification remain Slice 4 work, not alternate ingestion
paths.
On an existing live OpenClaw install, treat plugin install/enable, gateway
restart, worker service changes, and plugin refresh as live-system changes:
validate with openclaw config validate and openclaw doctor --lint, then
restart only through openclaw gateway restart or the documented ops refresh
script. The repo docs and commands should never require raw edits to
OpenClaw runtime config.
Olympus is built on the assumption that the boundary is the product:
raw_source_exposed: false, re-validated
client-side. Raw documents, embeddings, cursors, and tokens never cross.olympus data export gives you your data;
olympus data delete --all verifiably removes indexes, embeddings,
configs, tokens, and service units.The onboarding flow, end to end:
flowchart LR
A[Install<br/>plugin] --> B[olympus setup<br/>pick your posture]
B --> C[olympus connect<br/>OAuth IDs · session paths · API-key stdin]
C --> D[Dashboard<br/>watch it ingest]
D --> E[Ask your agent<br/>cited answers]
| Command | What it does |
|---|---|
olympus setup --preset <preset> --yes | writes sovereignty policy and worker auth for the chosen posture |
olympus connect <source> ... | records OAuth, session, or API-key credentials with source-specific flags |
olympus worker foreground|install|start|stop|restart|status|upgrade|uninstall | one versioned lifecycle for the local engine, foreground or supervised |
olympus dashboard | opens the standalone dashboard with a short-lived authorization link; no worker-token copying |
olympus dashboard --no-open | generates an unused opening link for an agent to hand to you |
olympus dashboard token | advanced compatibility access to the worker bearer; never share it in chat |
olympus source answer "…" | ask across your sources from the terminal |
olympus ask "…" [--level strict|standard] | one question to a frontier model anonymously through zkAPI (paid from your zkAPI balance; the question only) |
olympus tier explain|set|rules|classifier … | why an item has its tier, owner overrides and rules, and the private classifier's approval |
olympus tier migrate plan|approve|run|rollback|purge|status | moves an existing install's items into per-item tiers, each step owner-approved after a dry-run plan |
olympus doctor | diagnoses problems, each with a fix-it hint |
olympus data export|delete | your data, out — or gone |
olympus serve | MCP stdio server for non-OpenClaw agents |
olympus worker install and upgrade atomically reconcile the generated
service unit and owner-only worker environment before activation. Interrupted
install or upgrade transactions recover the previous managed files when the
same command is rerun. status reports the observed service and transaction
state; it never guesses that an unreadable manager or non-regular managed path
is healthy. uninstall removes only the supervised service and intentionally
retains credentials, source configuration, and indexed data. Use the separate
data lifecycle when those bytes should also be removed.
Credential, scope, pairing, Disconnect, partial-sync, and source-dependency
repairs do not normally require a worker restart. Follow the source card or
olympus doctor recovery action instead.
Dashboard Disconnect stops new scheduled and manual reads, removes the
selected local account grant, and keeps indexed data and reusable developer-app
registration. It does not revoke provider-side access; the card links the
provider revocation page. Local data deletion remains the deliberate CLI-only
flow: preview olympus data delete --source <id> --dry-run, Disconnect the
source, then run the command without --dry-run.
Telegram and WhatsApp are paired sessions rather than broker grants, so their cards carry Unpair instead: it stops new reads and deletes this computer's pairing session, keeping indexed messages and captured media, and leaves the linked device in place at the provider for you to remove there.
Open the dashboard on this computer (olympus dashboard). Under On this
computer, choose Open next to Agents, then press Connect an
agent. Pick the agent you use and follow its steps; every address and
snippet has a copy button.
olympus serve command) into the agent. This works without remote access.Agents in the cloud reach Olympus only when remote access is on; the Agents
page says whether it is. To turn it on, press Turn on remote access
there. Olympus then connects through the Olympus relay
(mcp.olympusplugin.ai): you create no account and run no tunnel. The relay
passes requests between your agents and this computer; it stores and logs no
questions, answers or tokens, but like any HTTPS endpoint it handles them in
transit. The relay connects ChatGPT, Claude, Grok (grok.com) and Grok Bot,
and approving one happens on this computer only, with one click on a page
Olympus serves locally; there is no pairing code. A Claude connector
approved on this computer then works in Claude on your phone too.
Turn off remote access turns it off again. If the
relay cannot be reached, the page says Olympus relay unavailable and
Olympus keeps retrying on its own; agents on this computer are unaffected.
Advanced: to use a tunnel you run yourself instead of the relay, set
plugins.entries.olympus.config.remote.publicBaseUrl to its https origin
(openclaw config set …) and turn remote access on. Through your own tunnel,
Claude, ChatGPT and Grok approve Olympus on its approval page with a one-time
pairing code from the Agents page, and the Grok API takes an address plus a
key from Create key (shown once).
Every connected agent gets the same privacy rules
as your OpenClaw agent. It never sees Private source text or Secrets. For
Private items it receives only answers that Venice or a local model reasoned
out, with each item's title, path, source and author. The Agents page
lists connected agents with when each was added and last used, and
Revoke removes one. olympus connections list|revoke|pair|add does the
same from a terminal.
Each agent's steps end with a short instruction that tells it when to ask
Olympus. Paste it into Claude project instructions, Grok's custom
instructions or Grok Bot's skills, or
load the packaged Agent Skills folder
integrations/agent-skills/ask-olympus/.
olympus serve exposes the same sanitized read operations — source_answer,
source_answer_result, source_index_status, capability-gated
source_index_search, and ask_anonymously — to any MCP-capable agent. The
supported Hermes configuration narrows that server to exactly source_answer,
source_answer_result, source_index_status and ask_anonymously through its
per-server tool allowlist.
ask_anonymously sends one typed question to a frontier model through zkAPI
(paid per question from the user's own balance; nothing identifies them). The
first call with no level returns needs_choice: the agent asks the user once
for Strict (their own model rewrites the question into general questions before
it leaves) or Standard (their words, prepared as written, lightly cleaned up or
by their saved instruction), then calls again with level and remember: true.
Only the question goes out, never documents, and never to the provider that
hosts the agent asking: a question from ChatGPT goes to Claude Sonnet by
default, one from Claude Code or Claude Desktop to an OpenAI model, and a
one-off model from the agent's own provider is refused. Setup (the zkAPI
route, the writer model, the zkAPI models for questions from ChatGPT and from
Claude, the spend limit) lives on the dashboard's Anonymous answers card, which
is for setup only: questions are asked through an agent (or olympus ask); see
docs/design/private-answers.md.
MCP clients cap how long one tool call may run, and an answer can take several
minutes. So over MCP (local olympus serve and remote /mcp alike) and the
OpenAPI tool paths, a source_answer that is not done by a hand-off threshold
returns {"status": "working", "job_id": …} and keeps running. The threshold
is 200 seconds for remote agents (OLYMPUS_SOURCE_ANSWER_HANDOFF_MS) and 45
seconds for local olympus serve (OLYMPUS_SOURCE_ANSWER_STDIO_HANDOFF_MS,
under Codex's 60-second default tool timeout); both are capped at 230000.
source_answer_result with that job_id returns the answer, the same error
the call would have raised, or working again after waiting up to a minute
(never longer than the threshold). A slow ask_anonymously (a Tor route can
take minutes) hands off the same way and is collected with the same tool. A job that runs past 20 minutes is stopped
with source_answer_deadline, and revoking a connection drops its jobs.
Remote answers share the analyst with your own assistant's answers; there is
no priority lane. So the worker runs at most two remote answers at once (the
analyst's lane count; OLYMPUS_SOURCE_ANSWER_MAX_RUNNING raises it for a
multi-lane analyst) and refuses more with source_answer_busy, which bounds
how much remote work can ever queue ahead of your own question. A caller that
disconnects, or a job that reaches its deadline, stops the analyst call
itself and frees the lane. A job id is readable
only by the connection (or olympus serve process) that asked, lives in
memory, and expires 15 minutes after its answer is ready.
For Hermes Agent, resolve the installed plugin first:
openclaw plugins inspect olympus --json
Copy plugin.rootDir from that content-free response, append /bin/olympus,
and pass the resulting absolute executable path to Hermes:
hermes mcp add olympus --command /absolute/managed/olympus/bin/olympus --args serve
hermes mcp test olympus
Make the olympus server entry in ~/.hermes/config.yaml match the packaged
config/hermes/olympus.mcp.yaml:
mcp_servers:
olympus:
command: <absolute-managed-plugin-root>/bin/olympus
args: [serve]
tools:
include: [source_answer, source_answer_result, source_index_status, ask_anonymously]
prompts: false
resources: false
Restart Hermes or run /reload-mcp, then verify that the discovered registered
names are exactly mcp_olympus_source_answer,
mcp_olympus_source_answer_result, mcp_olympus_source_index_status and
mcp_olympus_ask_anonymously. Invoke the discovered names rather than
hard-coding them. A cited-answer round trip uses the discovered
mcp_olympus_source_answer; source_watch_* remains OpenClaw-only.
The optional packaged Hermes skill is
integrations/hermes/ask-sources/SKILL.md.
Copy its directory to ~/.hermes/skills/ask-sources/ or expose the parent with
skills.external_dirs; it declares the same four tools and no fallback access.
No hermes://mcp/install link is published: current Hermes upstream documents
custom MCP installation through hermes mcp add but does not document that URI
handler. No Nous catalog submission has been made; that remains a later,
separately reviewed external action.
There are no operator agent tools. Index maintenance — sync, extraction,
embedding, retries — is the worker's own scheduler, and what a person drives by
hand goes through the olympus CLI. The whole agent tool surface is twelve tools —
argus_ping, argus_list_models, argus_complete, source_answer,
source_answer_result (MCP and remote only), source_index_status, source_index_search, source_watch_create,
source_watches, source_watch_cancel, olympus_doctor, ask_anonymously — declared in
src/core/public-surface.ts; Hermes over MCP sees
the subset above, and worker bearer auth is enforced throughout.
Operational note for connector-store corpora: run the matching sync script
first, then mount the same SQLite store in the source worker with
OLYMPUS_SOURCE_INDEX_CONNECTOR_STORES_JSON. The worker env entry must use
the same corpus id, family, trustDomain, and dbPath the sync script
writes, and that corpus id must be in the corpus registry — a store mounted
for an unregistered corpus fills but is never read.
Chat-family mounts must also declare their exact principal identity with
principalProvider and principalAccountScope (for example, whatsapp and
personal). Structured scopes use the stored account scope as their prefix, so
the shipped WhatsApp identity is personal:chat:<id> while Telegram remains
telegram.personal:chat:<id>. A chat mount without both fields remains
available for non-chat_scope reads, but chat_scope filtering fails closed
as not configured; mounted rows never establish account authority.
The migration-era indexes, replay/import utilities, read-authority switches, and retired store writers were removed in Slice 2. Canonical connector stores are now the only source read/write authority. Compatibility aliases that remain at input boundaries do not select another runtime or store.
Olympus is TypeScript on Bun: one plugin package, stable versioned architecture
contracts (SourceConnector / EvidencePack / Analyst — only the
connector is per-source), and 1,400+ tests including an architecture guard
that keeps per-source answer logic out of the shared spine.
bun install
bun run test:focus -- test/example.test.ts
Use focused local proof while editing; GitHub requires each substantive CI lane and runs the complete suite in parallel before merge. See the canonical engineering process.
Deep-dive docs: contracts and architecture · trust model · sovereignty config · uninstall
MIT — free for any use, including commercial.
Want to suggest a change? See CONTRIBUTING.md: fork, branch, open a PR. Read access doesn't include direct pushes — everything lands through review.