Quickstart

`cortex setup`, and an agent can call the vault.

One command takes a fresh machine from nothing to an agent calling context_map. It installs the engine, creates a starter vault, registers the MCP server with the agents it finds on the box, and then proves the server answers from the new vault. It is a dry run until you pass --apply.

Merged on the engine, built from main. cortex setup and the offline bundle landed on the engine’s main branch (#284), so the commands on this page are the behaviour that merged, not a plan. There is no tagged release yet: an engine installed before that merge will not have them, which is why the bundle below is built from origin/main.

The changelog carries the state of every change named on this site, and says which ones are shipped and which are still in review.

Install from the offline bundle

The target box needs python3, python3-venv and git. Nothing else, and no network at install time.

On a box that can reach the engine and the package index

cortex engine bundle origin/main --fetch --out ~/cortex-bundles --json

On the target box

sudo apt-get install -y python3 python3-venv git
sha256sum -c cortex-bundle-<sha>.tar.gz.sha256
tar -xzf cortex-bundle-<sha>.tar.gz
sh cortex-bundle-<sha>/install-bundle.sh --link --setup

--setup writes a config whose vault is ~/cortex, installs the release, links cortex onto your path, and runs cortex setup --apply.

What it does, step by step

The last thing it prints is the table. Each row is a step, and the step either holds or it does not.

STEP             STATUS  DETAIL
config           OK      wrote the config (serving=release)
release          OK      installed the engine release
vault            PASS    created ~/cortex
validate         PASS    the vault's notes are valid
register:claude  PASS    registered the cortex MCP server
register:codex   PASS    registered the cortex MCP server
serve            PASS    the server answered tools/list
context_map      PASS    the starter vault's notes served
receipt          PASS    wrote the boot receipt
RESULT: PASS

vault: Copies the starter vault, renders its config, makes the first commit and builds the indexes. An existing vault is left alone, and a directory with something else in it is refused.
register: Agents are detected, never assumed: your Claude Code and Codex configs are written if they are there, and each Hermes profile gets its own entry. None found is a skip, not a failure.
context_map: One real call against the new vault, so the pass means the server answered from the notes on disk and not from a test double.

Check it from the agent

claude mcp list     # cortex ... Connected
codex mcp list      # cortex ... enabled

Then ask the agent to call context_map. The starter vault answers with 10 notes, about 2.1k tokens: the rules an agent pays for at boot, before it has read anything else.

That figure is our own measurement of the starter template that merged, not an estimate: the vault was created the way cortex setup --apply creates it, then composed and counted, and one real context_map call returned the same notes. Your vault’s boot set will be the size of the rules you write.

After the first run

Running cortex setup again is safe. A step that already holds reports OK and changes nothing.
--vault PATH puts the vault somewhere else; --reindex rebuilds the indexes after you add notes by hand.
--runtime claude,codex names the agents to register instead of letting setup detect them.
The capability record is not packaged yet, so --with-capabilities reports a skip. What it will do is proven in our own estate and is phase two of the beta.

Request a beta place · See the console

cortex setup, and an agent can call the vault.