# 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: ```text 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](setup-hybrid.md) and the [/connect wizard](connecting-agents.md) 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://: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](#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. **Ask about the trial first.** Unless a server is already running, the install needs the command from the person's trial e-mail; nothing on the public site replaces it. Ask for it before you check prerequisites or search the web. If there is no trial yet, send the person to and stop until the e-mail arrives. **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 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. - **Your sandbox is not the machine.** The install needs the container engine (its sockets under `/run/user/`), writes outside the repository (`~/codenavi`, your own config such as `~/.codex`) and network access. If your sandbox blocks one of these, ask the person to approve the command or rerun you with that access. Never report a sandbox error (`read-only file system`, `permission denied` under `/run/user/`) as a missing prerequisite. - **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. **This includes WSL** when no container engine runs inside it (step 1). **Prerequisites** (`install` only) — check, and report anything missing before running the installer: - Linux x86-64 with `docker` and `docker compose` (v2) or `podman` ([Podman](podman.md)), 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). In WSL, `nvidia-smi` is off `PATH` at `/usr/lib/wsl/lib/nvidia-smi`: check there before reporting no GPU (the installer finds it). CPU-only installs work but reindexing is slow. - With rootless `podman`: lingering on for the account that will own the install (`loginctl show-user "$USER" --property=Linger` prints `Linger=yes`). Without it the container cannot start once no login session is open, and an agent's detached shell often has none. Ask the person to run `sudo loginctl enable-linger "$USER"`, then check again ([Podman](podman.md#prerequisites)). - 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`. `Linux` can also mean WSL on a Windows PC: if `/proc/version` contains `microsoft`, you are in WSL. In WSL, use the Linux installer only if `docker info` or `podman info` succeeds there (a sandbox error is not a failure; see *Constraints*). Otherwise the server machine is the Windows host. Use the Windows hand-off in *Constraints*: Docker Desktop plus the PowerShell installer, with no Linux shell. Do not steer the person into installing a container engine inside WSL; [Windows](windows.md) explains why Docker Desktop is the supported path. 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: ```bash cd ~ curl -fsSL "" -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: ```bash CODEBASE_PATH=/abs/path/to/repo CODEBASE_NAME=myrepo \ setsid nohup sh codenavi-install.sh > codenavi-install.log 2>&1 < /dev/null & ``` `setsid` matters: many agent shells kill the whole process group when the command returns, and a plain `nohup … &` dies with it, leaving an empty log. 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 ```bash curl -s http://: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: ```bash 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://: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: ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H "Authorization: Bearer $TOKEN" http://: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](remote-access.md); 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: ```bash claude plugin marketplace add http://: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): ```json { "env": { "CODENAVI_AUTH_TOKEN": "", "CODENAVI_HOST": "" } } ``` Details and the statusline option: [Claude Code](claude-integration.md). **Codex CLI** — fetch the bundled plugin and run its connect script, which writes `~/.codex/config.toml` **and** the usage rules into `AGENTS.md`: ```bash git clone http://:8765/plugins/codex.git ~/codenavi-codex-plugin cd ~/codenavi-codex-plugin ./connect-codenavi.sh --host --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](connecting-codex.md). **Antigravity** — same shape: ```bash git clone http://:8765/plugins/antigravity.git ~/codenavi-antigravity-plugin cd ~/codenavi-antigravity-plugin ./connect-codenavi.sh --host --env-file ~/codenavi/.env ``` Details: [Antigravity](connecting-antigravity.md). **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: ```json { "mcpServers": { "codenavi": { "type": "http", "url": "http://:8765/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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](connecting-agents.md) 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: ```bash curl -fsSL http://: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: ```text …contents of AGENTS.customer.md… ``` 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: 1. `list_codebases` — the configured names. 2. `codebase_overview` for the target codebase. 3. `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://:8765/ui`; updates > are `./update.sh` in `~/codenavi`. --- ## Troubleshooting | Step | Symptom | Cause | Resolution | |---|---|---|---| | 1, 2 | in WSL, `docker` or `podman` not found | no container engine inside the distro | Windows hand-off: Docker Desktop, then the PowerShell command from the trial e-mail ([Windows](windows.md)); resume at step 3 | | 1, 2 | `podman info`: `read-only file system` on `/run/user/` | your agent's sandbox, not the machine | rootless podman cannot run inside a sandbox that blocks user namespaces (Codex's does, even with `/run/user` writable): ask the person to approve running the command outside the sandbox (interactive Codex prompts for this; headless `codex exec` needs `--sandbox danger-full-access`). Do not hand off to Windows | | 2 | install finishes but the container stays `Created`; podman: no systemd user manager at `/run/user//systemd` | rootless podman with lingering off and no login session | ask the person to run `sudo loginctl enable-linger "$USER"`, then start it with the command the installer printed (`podman compose up -d` in `~/codenavi`) | | 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](gpu-matrix.md) | | 3 | connection refused | container not running or bound elsewhere | `docker compose ps` in `~/codenavi`; [Troubleshooting → Install & server](troubleshooting.md#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](claude-integration.md#4-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](troubleshooting.md), or e-mail `support@cellpex.com` with the `/health` output and the failing step.