Nexus · installUpdateUninstallProblemsGetting started →RDRs →Research →Research in Nexus →From 7.6.1 to 8.1.2 →Tuple space →Coordination →How agents ship →

Installing Nexus

A brass-ribbed crystal dome on a hilltop at dusk

Nexus gives AI coding agents a shared, lasting memory of your project. It indexes your code and documents so agents find things by meaning, not keywords, and it keeps the decisions they reach as records you can read and review. Everything runs on your machine: no account, no API key, no database to install.

How do you use Claude?

You run claude in a terminal. You install the nx command and a plugin that adds tools, agents, and skills to Claude Code.

Operating system

Before you start

Nexus runs on Apple Silicon Macs with macOS 14 or later, on Linux with x86-64 or arm64, and on Windows 11 with x64. It ships its own PostgreSQL, built for those platforms only, so an Intel Mac or Windows on ARM stops at setup with an error. On macOS 13 or earlier the install fails while it resolves dependencies. It needs no GPU, because search runs on the CPU.

Tools to have

Install with one command

The command installs uv if it is missing and then the nx command. It asks one question before it downloads anything.

It also adds the plugin to Claude Code when claude is on your PATH.

curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh

The question

The script offers three choices and no Not now, because typing the command is your permission to install. Through the plugin, Claude offers all four.

ChoiceWhat happensDownload
LocalInstall the nx command and run a Nexus service on this machineabout 0.8 GB down (1.0 GB on Linux), 2.6 to 2.9 GB on disk
CloudInstall the nx command and connect it to a managed service you already have an address and token forabout 0.5 GB down (0.6 GB on Linux), 1.9 to 2.2 GB on disk
CLI onlyInstall the nx command and decide about a service laterabout 0.5 GB down (0.6 GB on Linux), 1.9 to 2.2 GB on disk
Not nowNothing is installednone

These sizes include PDF support. --slim leaves it out, and the first PDF you index then installs it. The sizes on disk are the install itself, and uv keeps a separate download cache that uv cache clean empties. Windows sizes have not been measured.

Pressing Enter at the question, or running the script without a terminal, picks CLI only. Local adds a second question, whether the service should start when you log in, and the answer is No unless you type y.

Cloud needs the service address and token. If your token is a mint credential, which is bound to one tenant, the script asks for that tenant too. The script asks for them in the terminal. Through the plugin a page opens in your browser instead, so Claude never sees the token.

Skip the question with a flag

Add a flag after sh -s --: --local, --cloud or --cli-only. With --local you can add --autostart or --no-autostart. The --slim flag leaves out PDF support. This example installs the service and does not start it at login:

curl -LsSf https://hellblazer.github.io/nexus/install.sh | sh -s -- --local --no-autostart

Add the plugin

Claude Code needs the plugin for its tools, agents, and skills. The one command already added it if claude was on your PATH. If not, start claude and type these two commands inside it, not in the terminal:

/plugin marketplace add Hellblazer/nexus
/plugin install conexus@nexus-plugins

If you add the plugin before the nx command exists, and uv is installed, Claude runs the install for you. Run /reload-plugins or start a new session, and Claude says that Nexus is not installed and asks the question above. If you choose Not now, each session shows one line that names /conexus:setup, so you can answer later.

Setup runs in the background, and you can ask Claude for progress. When Claude says it is done, reconnect the Nexus server: type /mcp, choose nexus, and choose Reconnect. A new session works too.

Check the install and index a repository

  1. Check the install

    nx doctor

    No line may show ✗. Read every ⚠ line. The ⚠ line "Orphan uv install" means a copy of conexus installed with uv is still on disk next to the one Nexus manages. Right after nx self install that is normal, and the next nx self install, nx self gc, or Claude Code session with the plugin removes the old copy.

  2. Index a repository and search it

    CLI only has no service yet. Run nx init first for a local service, or nx config init for a managed one. In Claude Code, /conexus:setup does the same.

    cd your-project
    nx index repo .
    nx search "how does retry work"

    If you index the same repository again, Nexus skips files that did not change. For a large repository, add --monitor to see the progress for each file.

Next: Getting started, the lessons for working inside Claude Code.

Update Nexus

Run both of these commands every time:

nx self install   # install the new version next to the current one
nx upgrade        # update the service, the data, and the plugins

Do not update with uv tool install conexus. A plain install builds a second copy that Nexus does not use. With --force it also takes the nx shims, so your terminal runs that copy without telling you. nx self install puts the shims back.

If nx upgrade stops and says to run nx backup, see Problems.

If you update the plugin with /plugin update in Claude Code, the next session runs both commands for you.

Remove Nexus completely

Follow these four steps in this order. None of them touches a managed cloud tenant, because they remove only what is on this computer.

  1. Optional: keep a copy of your data

    On a local install, nx backup writes the whole database, memory included, to one file in ~/nexus-backups/. On a managed service it writes your own tenant to a .nxtenant file in the same folder, and it needs a tenant or data token and engine 0.1.191 or later. Move that file somewhere you keep before you remove the data.

    nx backup

    For a cloud file, nx backup --check <FILE>.nxtenant verifies it on your computer without contacting the service.

    To keep only the knowledge store, in a form a new install can import one collection at a time, export it:

    nx store export --all -o <A-DIRECTORY-TO-KEEP>   # one .nxexp file per collection

    Later, nx store import <FILE>.nxexp restores a collection into a new install.

  2. Remove the Claude integration

    In Claude Code:

    /plugin uninstall conexus@nexus-plugins

    If you use both Claude Code and Claude Desktop, do both. If you installed the Desktop extension instead, the Desktop deployment guide shows how to remove it.

  3. Stop the service and delete the data

    nx uninstall                          # preview, changes nothing
    nx uninstall --yes --remove-data      # stop the service and its workers, remove autostart, delete notes, plans, catalog, the database and the search models

    Without --remove-data, the service stops and autostart is removed, but your data stays in ~/.config/nexus. Use that form if you plan to install again later.

  4. Remove the program

    nx uninstall does not remove nx itself or older versions kept side by side. Remove them by hand:

    uv tool uninstall conexus 2>/dev/null      # the uv install, if one exists
    rm -rf ~/.local/share/nexus                # program versions
    rm -f ~/.local/bin/nx ~/.local/bin/nx-mcp ~/.local/bin/nx-mcp-catalog ~/.local/bin/nx-session-end-launcher ~/.local/bin/nx-hook

Check

which nx                        # must print nothing
launchctl list | grep -i nexus  # must print nothing
ls ~/.config/nexus              # must not exist
ls ~/.cache/nexus               # must not exist

If ~/.cache/nexus still exists, an older release left it behind. Delete it with rm -rf ~/.cache/nexus.

Problems

The install fails with "No solution found when resolving dependencies"

The hint names torch and cp314 because you left --python 3.12 off the install command and your python3 is 3.14. Run the command again with the flag.

Crash on startup, or an import error mentioning voyageai or Pydantic v1

Your install runs on Python 3.14, which does not work yet. This is the one case where --force is right. Run these two commands: uv tool install conexus --force --python 3.12, then nx self install. The second command puts the nx shims back.

nx: command not found

Add ~/.local/bin to your PATH and open a new terminal. If PATH is already correct, run nx self install. If nx was never installed, run uv tool install conexus --python 3.12.

The service will not start and says to run nx backup

Your store holds old-format rows that the engine's first start would delete, so Nexus refuses to start the engine until a backup exists. Run nx backup now, because a backup taken before the refusal does not count. Then run nx daemon service start. Do not run nx upgrade again, because it can time out while it checks a large backup and the start command has no time limit. This applies only to the bundled local Postgres. The operator of a managed or self-hosted Postgres owns the backups.

nx search returns nothing

Run nx doctor. If you chose CLI only, no service runs yet, so run nx init for a local service or nx config init for a managed one. If the index was interrupted, run nx index repo . again and it continues where it stopped.

Plugin installed but its tools never appear

Usually the nx command is not installed, setup has not finished, or you chose Not now. Type /conexus:setup, which shows what is missing and asks before it installs anything. After setup is done, reconnect the nexus server with /mcp. /conexus:nx-preflight also lists what is missing.

Nothing above helps

Paste the recovery runbook as the first message of a Claude Code session. Claude checks the install step by step and asks you before it changes any data.

Appendix

Install by hand, step by step

These are the commands that the one command and the setup tool run for you. Run them in this order, and each is safe to run again.

  1. Install the nx command

    The first command installs nx, and the second moves it to the layout that Nexus manages.

    uv tool install conexus --python 3.12
    nx self install

    A fresh install needs no nx upgrade, even if nx self install suggests it.

    If the terminal cannot find nx after this, add ~/.local/bin to your PATH and open a new terminal.

  2. Set up the storage service

    This command first asks whether the service should start at login. It then downloads the service program, the database, and the search model, and starts the service.

    nx init

    Use nx init --yes to answer yes automatically, or nx init --no-autostart to skip starting at login.

  3. Check the install

    nx doctor

    The one ⚠ line to expect is explained under Check the install.

  4. Add the Claude Code plugin

    Start claude and type these two commands inside it, not in the terminal:

    /plugin marketplace add Hellblazer/nexus
    /plugin install conexus@nexus-plugins

    Then run /conexus:nx-preflight, which checks that everything the plugin needs is present.

Then index a repository.

What you installed and what it sends

Nexus is one service on your computer. It holds a database (Postgres 17 with pgvector) and three stores: scratch for one session, memory for project facts, and knowledge for everything you index. The search model also runs on your computer, so your data does not leave it unless you add a Voyage AI key. That key sends your text to an outside embedding service.

While Claude uses Nexus, it sends one short message a day, with no hostname, paths, or content. The privacy policy lists the fields, nx telemetry off stops it, and nx telemetry status shows the setting.

More: CLI reference. The code is AGPL-3.0-or-later, and everything you make with Nexus is yours. LICENSING.md covers commercial licenses.