Set up CodeNavi with your coding agent¶

This page is written for an AI coding agent to execute, not for a human to read top to bottom. Paste one line into Claude Code, Codex CLI, Antigravity, or any agent that can run shell commands and fetch URLs:

Set up CodeNavi by following the instructions at https://codenavi.com/docs/setup-agent.md

The agent installs the server (or connects to one you already run), verifies it, wires itself to it, and hands back a working first search. Two moments need a human: the trial sign-up e-mail, and any step the agent's shell cannot do interactively. The agent will tell you when.

Prefer doing it by hand? Use the connected setup and the /connect wizard instead. Both paths end in the same place.

The raw Markdown of this page is served at https://codenavi.com/docs/setup-agent.md and, on any running CodeNavi server, at http://<host>:8765/connect/docs/setup-agent.md. Give the agent whichever it can reach.

Instructions for the agent¶

You are setting up CodeNavi, a self-hosted code search MCP server, for the person you are working with. Follow the steps in order. Every step names its success condition; do not continue past a step that has not met it. When a step fails, apply the matching row in Troubleshooting once, then report the full error and stop.

Before you start¶

Gather all of the following in a single message, then proceed without further questions unless a step below says otherwise.

Required inputs

entry point — one of:
- connect: a CodeNavi server is already running. Ask for its address (default http://localhost:8765) and, if it runs on another machine, whether you have shell access to that machine.
- install: install a new server from a trial. Ask for the install command from the trial e-mail (a line starting curl -fsSL https://codenavi.com/trial/install/). If the person has no trial yet, point them to https://codenavi.com/trial and wait; the e-mail arrives after the operator issues the license.
codebase (install only) — the absolute path of the repository to index on the server machine, and an optional short display name (defaults to the folder name).
client — which agent to wire. Detect it from your own context first (you are that client); ask only if you cannot tell. Supported directly: Claude Code, Codex CLI, Antigravity. Any other MCP client uses the generic config in step 6.

Constraints

Never ask the person to paste the auth token into chat. Read it from the server's .env file (step 4) or have them open the /connect wizard, which fills it in for them.
Do not pipe a download into a shell. Save the installer to a file, read it, then run it. The installer is served over HTTPS and is designed to be read first.
Never overwrite CLAUDE.md, AGENTS.md, or any existing agent instruction file. Only append between the markers given in step 7.
Time budget. The install downloads a multi-gigabyte image. Run it detached with its output logged and poll the log; do not let a shell timeout kill it. The download resumes if interrupted.
Windows is a hand-off. The Windows installer is an interactive PowerShell wizard. If the server machine is Windows, download codenavi-install.ps1 as the trial e-mail shows, tell the person to run it in PowerShell, and resume at step 3 when they say it finished.

Prerequisites (install only) — check, and report anything missing before running the installer:

Linux x86-64 with docker and docker compose (v2) or podman, and the current user able to run containers without sudo.
An NVIDIA GPU visible to nvidia-smi (or an AMD GPU with ROCm; the trial form chose which build to ship). CPU-only installs work but reindexing is slow.
About 45 GB free disk in the home directory (image, layer cache and index).
curl present and https://codenavi.com reachable.

If something is missing, say exactly what and ask whether to proceed anyway. Respect a decision to stop.

Step 1 — Determine the server machine¶

Detect the operating system with uname -s. Confirm whether you are running on the machine that will host the server (install) or that already hosts it (connect). If the server is elsewhere and you have no shell there, every server-side command below must be relayed to the person, and step 4 changes.

Success: you know the OS and whether server-side commands run locally.

Step 2 — Install the server (`install` entry point only)¶

From the person's home directory, not inside an existing CodeNavi install:

cd ~
curl -fsSL "<install URL from the trial e-mail>" -o codenavi-install.sh

Read codenavi-install.sh before running it. Then run it detached with the codebase pre-set so it configures and starts the server in one pass:

CODEBASE_PATH=/abs/path/to/repo CODEBASE_NAME=myrepo \
  nohup sh codenavi-install.sh > codenavi-install.log 2>&1 &

Poll codenavi-install.log until the process exits. The installer detects the GPU, downloads the matching image (resumable), verifies checksums and the image signature, fetches the license with the trial token, writes .env, and starts the container. The install directory is ~/codenavi.

If the log shows the installer waiting for a license file or asking a question it cannot receive, stop polling and tell the person exactly what it is waiting for; those prompts come from an older trial flow and need a terminal.

Success: the installer exits 0 and the log ends with the address to open.

Step 3 — Verify the server¶

curl -s http://<server>:8765/health

"status": "ok" is the goal. "warming_up" or "degraded" right after install means the model is still loading: wait 30 s and retry, for up to five minutes. The response also reports auth_required; it is true on every packaged install.

Success: status is ok.

Step 4 — Obtain and check the auth token¶

On the server machine:

grep '^CODENAVI_AUTH_TOKEN=' ~/codenavi/.env | cut -d= -f2-

If the server was installed by hand elsewhere, the file is deploy/.env inside that install. Keep the value in a shell variable; never print it into the conversation.

If you have no shell on the server machine, do not ask for the token. Tell the person to open http://<server>:8765/connect in a browser from their own machine; the wizard renders the finished config for their client with the token filled in and a Verify button, and steps 5 and 6 become a paste. Continue at step 7.

Check the token before wiring anything:

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $TOKEN" http://<server>:8765/connect/api/verify

Success: 200. A 401 means the token is wrong or stale.

Step 5 — Wire a supported client¶

Use the server's address as seen from the client machine: localhost when both are the same machine, otherwise the LAN or tunnel address. Remote setups are covered in Remote access; an SSH tunnel (ssh -N -L 8765:localhost:8765 user@server) makes any remote server look local without opening a port.

Claude Code — the server hands out its own plugin over a read-only git endpoint, no token needed for the fetch:

claude plugin marketplace add http://<server>:8765/plugins/claude.git
claude plugin install codenavi@codenavi

The plugin's MCP entry reads the token, host and port from the environment. Merge this into ~/.claude/settings.json (create the file if absent, keep every existing key; drop CODENAVI_HOST when the server is local):

{ "env": { "CODENAVI_AUTH_TOKEN": "<token>", "CODENAVI_HOST": "<server>" } }

Details and the statusline option: Claude Code.

Codex CLI — fetch the bundled plugin and run its connect script, which writes ~/.codex/config.toml and the usage rules into AGENTS.md:

git clone http://<server>:8765/plugins/codex.git ~/codenavi-codex-plugin
cd ~/codenavi-codex-plugin
./connect-codenavi.sh --host <server> --env-file ~/codenavi/.env

Codex reads the token from the environment at start, so it must be exported in the shell Codex runs from. The script prints the exact idempotent line to append to ~/.bashrc; run it. Add --project to write the rules to the repository's own AGENTS.md instead of the global one. Details: Codex CLI.

Antigravity — same shape:

git clone http://<server>:8765/plugins/antigravity.git ~/codenavi-antigravity-plugin
cd ~/codenavi-antigravity-plugin
./connect-codenavi.sh --host <server> --env-file ~/codenavi/.env

Details: Antigravity.

Success: the client's config names the codenavi server with the URL and token above. Skip step 6.

Step 6 — Wire any other MCP client¶

Write the generic streamable-HTTP entry into the client's MCP configuration file, merging with what is there:

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://<server>:8765/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Per-client key names differ slightly (Windsurf uses serverUrl; Claude Desktop needs the mcp-remote bridge; Pi needs an adapter). The exact shape for sixteen clients is in the connect wizard on the running server and in the per-client guides.

Success: the client lists CodeNavi's tools after a restart.

Step 7 — Install the usage rules¶

CodeNavi's searches serialize on the GPU and its results carry redaction markers; agents that do not know this fire bursts that queue, and misread output. The rules live in one file:

curl -fsSL http://<server>:8765/connect/docs/AGENTS.customer.md -o /tmp/codenavi-agents.md

(Also at https://codenavi.com/docs/AGENTS.customer.md.)

Claude Code: the plugin already ships these rules as a skill. Do nothing.
Codex CLI and Antigravity: the connect script already wrote them. Do nothing.
Any other client: append the file's contents to the repository's AGENTS.md (or the client's equivalent instruction file) between these exact markers, creating the file if absent:

<!-- BEGIN CodeNavi agent rules -->
…contents of AGENTS.customer.md…
<!-- END CodeNavi agent rules -->

If the marked block already exists, replace only what is between the markers. Never touch content outside them.

Success: the rules are present exactly once in the right file.

Step 8 — First search¶

Restart the client so it loads the new MCP server, then run, in order, one call at a time:

list_codebases — the configured names.
codebase_overview for the target codebase.
semantic_search with a real question about that code, for example "where is authentication handled?", limit=5.

An empty result on a plausible question right after install usually means the index is still building: call reindex_status, wait, retry once.

Success: semantic_search returns ranked chunks with file:line references.

Then tell the person:

CodeNavi is installed and connected. Start a new session so the rules and tools load. Try: "Using CodeNavi, explain how <a feature you know> works in this repo." The web UI is at http://<server>:8765/ui; updates are ./update.sh in ~/codenavi.

Troubleshooting¶

Step	Symptom	Cause	Resolution
2	`docker: permission denied`	user not in the `docker` group	`sudo usermod -aG docker $USER`, re-login, rerun the installer
2	installer stops at a GPU question	two GPU vendors detected, no terminal	rerun in the person's terminal, or pass the vendor's build by rerunning from a terminal and answering
2	download restarts from zero	cache dir removed	the image cache is named in the log's last lines; leave it in place between reruns
3	`degraded` for more than five minutes	model failed to load, usually VRAM	`docker compose logs -f` in `~/codenavi`; see GPU matrix
3	connection refused	container not running or bound elsewhere	`docker compose ps` in `~/codenavi`; Troubleshooting → Install & server
4	`401` from `/connect/api/verify`	wrong token, or an exported `CODENAVI_AUTH_TOKEN` in the shell shadowing `.env`	`unset CODENAVI_AUTH_TOKEN`, reread `.env`
5	`claude plugin marketplace add` fails with a name collision	marketplace added earlier from a local path	`claude plugin marketplace remove codenavi`, then add again
5, 6	tools never appear	token missing from the client config	Claude Code → Troubleshooting
8	every call times out	a burst of searches issued at once	one or two searches in flight, see the rules file
8	results look stale	index behind the working tree	`reindex_incremental`, then retry

Anything else: Troubleshooting, or e-mail [email protected] with the /health output and the failing step.