From your license email to your first search.

Run the install command from your license email

Your license email contains a one-line install command, personal to your trial. Open a terminal on the machine you're installing on (SSH into your Linux server, or a PowerShell window on Windows — Docker Desktop, no WSL shell), paste it, press Enter. The installer narrates as it goes:

• It checks your machine first — Docker, GPU, memory, disk. If something's missing, it prints the exact fix and stops; run the fix, then paste the install command again. It's always safe to re-run.
• It loads CodeNavi — the server and its AI search models in one package. This is the slow part (a few minutes).
• It asks one question — Absolute path to the repo: — type the full path of the code you want to search (e.g. /home/you/projects/my-app), then press Enter to accept the suggested name.
• It starts the server and waits until it reports healthy.

Have an NVIDIA GPU that Docker isn't wired to yet? The installer sets that up too (it may ask for your sudo password). It will never silently fall back to slow CPU indexing — if the GPU can't be reached, it tells you and stops.

Copy your access token

At the end, the installer prints your access token — shown once in your terminal, never written to any log. It's CodeNavi's only credential: no accounts, no passwords. Your browser and your coding agent both use this one token.

Copy it into your password manager now. Misplaced it later? It lives on the server, in the install folder:

grep CODENAVI_AUTH_TOKEN .env

Open the Connect page & build the index

The installer's final message shows a URL like http://<server-ip>:<port>/connect. Open it in the browser on your everyday machine and paste your token when asked (once per browser).

The page notices your code isn't indexed yet and points you to "Build it first →" — one click, and CodeNavi reads your repo and builds its search index, showing progress as it goes. A few minutes for most repos; large monorepos can take 15–20 minutes on a mid-range GPU.

URL doesn't load? You're probably on a different network than the server (or on a CPU-mode install, which only listens locally). Forward the port over SSH from your laptop — ssh -L <port>:localhost:<port> you@your-server, leave it running — then open http://localhost:<port>/connect instead. The port is in the installer's final message (usually 8765).

Locking down exposure. A GPU install is reachable on your LAN (always token-gated). To restrict it to the machine itself, set CODENAVI_BIND=127.0.0.1 in .env and run docker compose up -d --force-recreate — then the SSH tunnel above is the only way in.

Connect your coding agent

Back on the same Connect page, pick your client — Claude Code, Codex, Antigravity, VS Code (Cline / Roo Code / Continue), Zed, Windsurf, Antigravity and more. It writes the exact configuration for you, server address and token already filled in, and a Verify button confirms the connection works.

Claude Code and Codex users: your package also bundles plugins that add slash commands and built-in guidance — the nicest way to use CodeNavi from those two. Details in Connecting specific clients below.

Only want the browser? Skip this step — the web UI at http://<server-ip>:<port>/ui covers search and chat on its own.

Ask your first question

In the web UI, the Search screen turns a plain-English question into ranked code, and Chat gives grounded answers with file:line citations. From your coding agent, just ask:

# in Claude Code, Codex, Antigravity, …
"Use semantic_search to find where requests are authenticated."
"Who calls chargeCard()? What breaks if I change User::save?"

The second kind — who calls this, what breaks if I change it — uses CodeNavi's call-graph tools (find_callers, impact_analysis, diff_impact); your agent picks them automatically. Chat in the web UI needs an LLM backend — local Ollama or a cloud provider (Claude, OpenAI, OpenRouter); search works without one.

Find your install folder

Everything uses files in the unpacked package folder (the one that holds .env), so start there:

# jump into your unpacked package folder (the one that holds .env):
cd "$(ls -d ~/codenavi-*trial-base 2>/dev/null | head -1)" && pwd
# nothing printed, or it's the wrong folder? list what you have and cd in by hand:
ls -d ~/codenavi-*

Your container is named after this folder (e.g. codenavi-<version>-trial-base), not codenavi. So always drive Docker with docker compose … from this directory (e.g. docker compose logs -f, docker compose ps) — that works regardless of the name.

Point it at your code & start it yourself

Only needed if you skipped the installer's codebase question (headless installs skip it automatically). In that case .env holds a CODEBASE_PATH=CHANGE_IT_TO_ABSOLUTE_PATH_OF_REPO placeholder; set it to the absolute path of the repo you want to search — the server refuses to start until you do — then bring it up:

# 1) set the repo to index (the sed replaces whatever placeholder is there):
sed -i 's#^CODEBASE_PATH=.*#CODEBASE_PATH=/abs/path/to/your/repo#' .env
#    (or: nano .env  → change the CODEBASE_PATH line by hand)

# 2) start the server:
docker compose up -d

# 3) read your token + port out of .env (the port is usually 8765 but the installer
#    picks the next free one if 8765 was taken):
TOKEN=$(grep -E '^CODENAVI_AUTH_TOKEN=' .env | head -1 | cut -d= -f2-)
PORT=$(grep -E '^CODENAVI_PORT=' .env | head -1 | cut -d= -f2-); PORT=${PORT:-8765}

# 4) wait for the models to warm (~2 min on first start):
curl -s "http://localhost:$PORT/health"

Reading /health: a JSON body with "status":"ok" means ready; any other status means it's still warming — wait and poll again. But Connection refused or an empty reply means the container isn't running — check docker compose ps and docker compose logs --tail=50. The most common cause is a wrong CODEBASE_PATH: if it doesn't point at an existing directory, docker compose up -d fails with bind source path does not exist and nothing starts. Fix the path, then docker compose up -d --force-recreate.

Don't export a different CODENAVI_AUTH_TOKEN in your shell: Docker Compose would use that instead of .env and you'd get 401s. If that happens: unset CODENAVI_AUTH_TOKEN && docker compose up -d --force-recreate.

Build or refresh the index from the terminal

The Connect page's "Build it first →" button does this for you — but you can trigger the same in-server reindex with curl. It reuses the server's own model copy (no second copy to exhaust GPU memory):

curl -s -X POST "http://localhost:$PORT/reindex" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"full": true}'

# watch progress until "running": false  (full build ≈ 6–20 min, depending on repo size + GPU).
# NOTE: near the end the server reloads its models into clean VRAM (~30s) but STAYS UP — the
# status may briefly show "reloading": true; just keep polling until "running": false:
curl -s "http://localhost:$PORT/reindex-status" -H "Authorization: Bearer $TOKEN"

Use the in-server reindex above, not docker exec … --reindex — that loads a second model copy and runs out of memory on GPUs ≤ 12 GB.

Sign in to the web UI

Open http://<server-ip>:<port>/ui (or the tunneled http://localhost:<port>/ui). The page loads immediately — you do not put the token in the URL. Within a second it pops an "Authentication required" dialog; paste your token into the Auth token field and Save & continue. The browser remembers it (in local storage) — you paste it once per browser.

If the dialog reappears saying "your saved token was rejected," the token changed in .env — print the current one on the server (grep CODENAVI_AUTH_TOKEN .env) and paste that.

Claude Code (bundled plugin — recommended)

Requires Claude Code. Install it first if you don't have it — claude.com/code (or npm i -g @anthropic-ai/claude-code), then confirm with claude --version.

The bundled plugin adds twelve slash commands, two skills, and a session hook, and installs fully offline. Run from your install directory; restart Claude Code twice on first setup (it's a terminal app — "restart" means quit with /exit and run claude again):

# 1) FROM your CodeNavi package dir (has setup.sh + plugins/claude/) — ./plugins/claude
#    is relative to THIS dir, not your project. Then quit (/exit) and relaunch `claude`:
cd ~/codenavi-<version>-trial-base && claude plugin marketplace add ./plugins/claude
claude plugin install codenavi@codenavi

# 2) in the new session, wire the project config, approve the .mcp.json write,
#    then quit and relaunch once more:
/codenavi:doctor

# 3) now it's connected — use it:
/codenavi:status                                # health, version, chunk/file counts
/codenavi:overview                              # entry points, key modules, frameworks
/codenavi:search how does payment processing work
/codenavi:chat where is the user login validated?
/codenavi:compliance asvs-core                  # OWASP gap report, file:line evidence
/codenavi:compliance cra-annex1                 # EU Cyber Resilience Act Annex I gap report

Give Claude Code the token and port by deriving them from .env (never paste the token) so they can't drift from the server. Run this once, from your install directory — it's idempotent and self-verifying:

ENV="$(pwd)/.env"
grep -q 'export CODENAVI_AUTH_TOKEN=' ~/.bashrc 2>/dev/null || \
  echo "export CODENAVI_AUTH_TOKEN=\$(grep -E '^CODENAVI_AUTH_TOKEN=' '$ENV' | head -1 | cut -d= -f2-)" >> ~/.bashrc
grep -q 'export CODENAVI_PORT=' ~/.bashrc 2>/dev/null || \
  echo "export CODENAVI_PORT=\$(grep -E '^CODENAVI_PORT=' '$ENV' | head -1 | cut -d= -f2-)" >> ~/.bashrc
source ~/.bashrc
[ -n "$CODENAVI_AUTH_TOKEN" ] && echo "token OK, port $CODENAVI_PORT" || echo "EMPTY — check the path: $ENV"

Running Claude Code on your laptop against a remote server? It talks to http://localhost:<port>/mcp — the same server, port, and token as the UI — so either point it at the server's IP, or keep the same ssh -L <port>:localhost:<port> tunnel from step 3 open, and run the export above on the laptop too. Running claude on the server over SSH needs no tunnel. No plugin? Drop a project .mcp.json pointing at http://localhost:<port>/mcp with header Authorization: Bearer <token>.

Optional — statusline badge. Show how much of the current repo is indexed and whether CodeNavi was used this turn, right in your Claude Code prompt — /codenavi:status-line enable (and disable to restore). Needs python3 on PATH; purely cosmetic.

OpenAI Codex CLI (bundled connect script)

Only if you use OpenAI's Codex CLI (confirm with codex --version). Codex reads ~/.codex/config.toml (not Claude's .mcp.json) — the bundled connect script wires it and verifies the endpoint:

PORT=$(grep -E '^CODENAVI_PORT=' .env | head -1 | cut -d= -f2-); PORT=${PORT:-8765}
cd plugins/codex                                           # bundled in your package (two levels below .env)
./connect-codenavi.sh --env-file ../../.env --port "$PORT" # writes config.toml + verifies; never prints your token
codex plugin marketplace add .                             # then, inside Codex: /plugins install codenavi@codenavi

Three Codex gotchas the script handles: bearer_token_env_var is a variable name not the token; use the unscoped /mcp (a single-repo install is named default); config goes in config.toml, not .mcp.json.

Everything else — the Connect wizard

For every other editor or agent, the running server's Connect wizard (http://<server-ip>:<port>/connect, step 4 above) writes copy-paste MCP config for your exact client — the right config shape and the per-client gotcha handled for you, plus a paste-ready CLAUDE.md / AGENTS.md guidance block so your agent reaches for semantic_search instead of blind grep. It always matches your installed version, so it's the source of truth for client setup.

No server running yet? Preview the config for any client (plus the plugin fast-paths) at codenavi.com/connect-preview — the same picker, with placeholders you fill in your browser. Once yours is up, the in-product /connect is better: it fills your real token and can verify the connection live.