CodeNavi — Setup Guide¶

Prerequisites¶

Docker 24+ with Docker Compose v2 — or Podman (rootless works): on a podman-only host (Fedora/RHEL) the installer detects podman automatically; see Podman
8 GB RAM minimum (16 GB recommended for GPU mode). On a 16 GB host, index headless: the embedder holds ~7–8 GB of host RAM while encoding, so a desktop session + browser on the same machine invites the kernel OOM-killer — it kills the server mid-index and the container restarts looking innocently idle (the UI will say "previous reindex was interrupted"). Close heavy applications before a full reindex, or run the host headless; 32 GB hosts don't need to care.
GPU acceleration for indexing — Tier A is an NVIDIA GPU on Linux or Windows 11 (Docker Desktop), RTX 20-series / compute ≥ 7.5 or newer, driver ≥ 570.65 — or an AMD GPU on Linux (RX 6000-series or newer / Instinct MI100+, in-tree amdgpu driver; needs the ROCm build of the image — pick AMD when requesting your package). CPU-only hosts can serve queries against a pre-built index (Tier B). See Hardware tiers below.
Supported platforms:
Linux (bare metal or WSL2) — NVIDIA GPU auto-detected, Tier A
Linux + AMD GPU (bare metal) — auto-detected with a ROCm build of the image, Tier A (no ROCm install needed on the host; AMD GPU acceleration is Linux-only)
macOS (Apple Silicon) — Tier A query (parity with GPU host) under Docker; native MPS install indexes 21× faster but currently regresses retrieval quality 16 pts¹, so reserve native for indexing-throughput experiments. Mac-specific install: see install-mac.md (colima vs. Apple Container, native MPS, common gotchas).
macOS (Intel) — Tier B only, ~3.5 GB image
Windows 11 + NVIDIA GPU — full Tier A via Docker Desktop (its hidden WSL2 backend is the only Windows path that reaches the GPU; no manual WSL, no port proxy). Install with setup.ps1, then drive it from your Windows IDE: see setup-windows-gpu.html.
Docker Desktop on Mac, or Windows without the WSL2 backend (legacy Hyper-V engine) — Tier B (the Linux VM has no GPU/Metal access)
NVIDIA Container Toolkit — required for Linux NVIDIA GPU mode; setup.sh installs it on Docker hosts. On podman install it yourself and generate the CDI spec before running the installer — see Podman. (AMD needs no toolkit — the GPU is passed through as plain device nodes.)

Hardware tiers¶

CodeNavi's embedder (a fine-tuned Buric-E4B) needs hardware acceleration for indexing. Three supported shapes:

Tier A — full host (index + serve): NVIDIA GPU on Linux (setup.sh Docker path). Runs reindex / crawl / queries on the same machine.
Tier B — query-only host (CPU OK): serves queries against an index produced on a Tier-A box. Apple Silicon Macs under Docker fit here — laravel benchmark scores 86 % (parity with GPU host) but indexing on the Mac is CPU-only (Linux VM has no Metal access), so build the index on a Tier-A box and ship it. Do not trigger reindex on a Tier-B host — incremental reindex on a 3.5k-file codebase took >11 minutes on Lunar Lake (vs ~5 s on GPU) and blocks all queries while running.

End-to-end CPU (Tier C — index + serve on CPU) is not supported with the local embedder. Two production-quality workarounds for non-GPU hosts: (1) pre-build the index on a cheap one-shot cloud GPU and ship the LanceDB tables — see cloud-reindex.md; (2) a vendor-assisted remote-embedder setup — the proprietary embedder served from a LAN/cloud GPU box you control; contact support to set it up. Both paths preserve the retrieval quality of the local embedder. Generic-embedder APIs (OpenAI/Cohere) work technically but lose ~30 quality points on code retrieval and are not recommended. Apple-native MPS install can index fast (~14 chunks/sec on M4) but currently loses 16 retrieval-quality points vs Docker¹; use Docker on Mac until that's fixed.

If you must run the full server stack on rented GPU infrastructure (vast.ai, RunPod, Hyperstack) rather than borrow it only for index build, follow the supported recipe in rented-gpu.md. That path accepts an elevated trust model — the host operator has root on your weights, your license, and any source you index there — governed by Addendum A of the commercial license. Works on ≥8 GiB cards: the VRAM autotune² indexes 11–12 GiB cards at batch 1, 16 GiB at batch 4, and ≥17 GiB at the full-speed batch 16 default, moving the reranker to CPU below 17 GiB so it doesn't fight the embedder for VRAM. Below ~10.5 GiB — the point where the fp16 weights stop fitting — the embedder's weights stay int8-resident³ (~4.1 GiB instead of ~7.5 GiB), which is what makes 8–10 GiB cards viable at ~23% less indexing throughput and identical search quality; those cards autotune to batch 2, since the freed 3.4 GiB pays for it. Pick ≥24 GiB if reindex throughput matters.

Quick Start¶

Get the package first. The fastest path is the one-command installer: it downloads the package, fetches your license key and runs the setup below for you. Trial: the command is in your license email. Paid plan: sign in at portal.codenavi.com and choose Install CodeNavi. The steps below are what that command does, for when you unpacked the package yourself.

Run setup (detects your platform automatically):

./setup.sh

This detects your OS, architecture, and GPU. On Linux with NVIDIA, GPU support is auto-enabled. On macOS, CPU mode is selected automatically. No flags needed.

First run — the embedder (Buric-E4B) is baked into the image; this downloads only the ~80 MB reranker (one-time). Run from your install directory (its container is named after that folder — the examples below use the compose service name codenavi, which works from any install folder without needing the actual container name):

TRANSFORMERS_OFFLINE=0 docker compose up -d
docker compose logs -f   # watch until "Listening on..."

Verify:

curl http://localhost:8765/health

Unauthenticated /health is deliberately minimal — no codebase names, counts, or models, so an unauthenticated caller can't inventory the deployment:

{
  "status": "ok",
  "version": "1.3.51",
  "service": "codenavi",
  "product": "CodeNavi — self-hosted code search & intelligence",
  "website": "https://www.codenavi.com",
  "license": "LicenseRef-CodeNavi-Eval",
  "auth_required": true
}

For the full diagnostic body (embedding models, GPU, per-codebase chunk counts, tier), send the bearer token — see Health Check below.

Trigger initial index:

Connect an MCP client and call reindex_incremental() (or reindex_full() for a full rebuild), or run:

docker compose exec codenavi python server.py --reindex --full

(Optional) Index external documentation:

If you have PDF or DOCX files to index alongside code, set DOCS_DIR in .env:

# In .env:
DOCS_DIR=/path/to/your/docs

Restart the container, then call the reindex_docs MCP tool. Markdown and text files within the codebase are indexed automatically during normal reindex — no extra setup needed.

On a multi-codebase server, create a DOCS_DIR/<codebase>/ subfolder per codebase (e.g. DOCS_DIR/myapp/, DOCS_DIR/api/) — when a codebase's subfolder exists, its reindex_docs (and the Docs Wiki⁴) scans only that subfolder, so external docs never cross between codebases. The flat DOCS_DIR root remains a legacy fallback (single-codebase installs stay zero-config; a multi-codebase install using it gets a logged warning).

(Optional) Access the web UI: Open http://localhost:8765/ui — nine screens: System, Index, Chat, Crawler, Search, Graph, Security, Wiki, Settings (see web-ui.md). Chat requires a configured LLM provider (see Providers).

Configuration¶

Everything the container reads is on two pages: Configuration — .env variables (paths, ports, tool surface, GPU autotune overrides, crawler, hooks), multi-codebase mode, and runtime data/settings.json (index exclusions, crawler limits); and Providers — the chat LLM (Ollama, LM Studio, vLLM, Claude, OpenAI-compatible, Gemini, OpenRouter) and the embedding slot.

Authentication and network¶

Opt-in bearer token, ports, host-vs-container bind, and every recipe for reaching the server from another machine: Network & authentication.

Connecting MCP Clients¶

Quickest path: with the server running, open http://localhost:8765/connect — a one-page wizard that detects whether auth is on and gives you copy-pasteable MCP config for Claude Code, Codex, Cursor, Antigravity, and VS Code/Cline.

Claude Code¶

1. Add to .mcp.json in your project root:

{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

See mcp-settings.json in the repo root for auth and custom-port variants.

2. Add agent instructions to your project root so Claude uses the CodeNavi tools correctly:

# Claude Code
cp templates/CLAUDE.md /path/to/your/project/CLAUDE.md

# Gemini CLI / other agents
cp templates/AGENTS.md /path/to/your/project/AGENTS.md

These templates teach the agent: - To issue CodeNavi calls in isolated turns (batch-cancellation safety) - When to use semantic_search vs direct file search - The right limit values for different query types

Other MCP Clients¶

Any client that supports MCP Streamable HTTP transport can connect to http://localhost:8765/mcp. The server also supports legacy SSE transport at the same URL for older clients.

Windows¶

Windows IDEs (Claude Code, Cursor, Windsurf, VS Code, JetBrains, Antigravity, Claude Desktop) and the Docker Desktop vs. self-managed-WSL2 distinction: Windows.

CLI¶

The codenavi CLI mirrors the everyday MCP tools (search, files, structure, index, feedback, backup, crawler) — useful when MCP is unavailable (server restarting, session dropped) or when you want to script CodeNavi from a shell. Most commands run Python imports directly inside the Docker container — no MCP session or auth token required.

codenavi search "where is payment handled?"      # semantic_search
codenavi file   "TransactionClosed"              # file_search
codenavi grep   "DB_HOST" --path config/         # grep_search
codenavi symbol verifyCredentials                # symbol_search
codenavi refs   Mailer --language php            # find_references
codenavi read   src/auth/login.php               # read_file
codenavi ls     src/auth --depth 2               # list_directory
codenavi overview                                # codebase_overview
codenavi chat   "explain the deploy process"     # POST /chat (no MCP tool)
codenavi status

See codenavi help for the grouped command list (search, files, indexing, docs, feedback, admin, crawler) or api-reference.md for the full CLI ↔ MCP mapping.

Health Check¶

curl -H "Authorization: Bearer $TOKEN" http://localhost:8765/health

With a valid token (or auth disabled), the full diagnostic body:

{
  "status": "ok",
  "embedding_models": {
    "code":    {"model": "/models/Buric-E4B", "status": "loaded"},
    "content": {"model": "/models/Buric-E4B",  "status": "idle"}
  },
  "llm": {"provider": "ollama", "model": "llama3.1", "status": "ok"},
  "tables": {
    "code_chunks": {"chunks": 12379},
    "doc_chunks":  {"chunks": 45},
    "web_chunks":  {"chunks": 8821}
  },
  "crawler": {"enabled": true},
  "tier": "Unlimited",
  "uptime_sec": 3600
}

Without a valid token, /health returns only status, version, service, product, website, license, and auth_required — no codebase names, counts, or models, so an unauthenticated caller can't inventory the deployment.

Field	Values	Meaning
`status`	`ok` / `degraded`	`ok` when code model is loaded and index has chunks
`embedding_models.code.status`	`loaded` / `idle`	Code model state
`embedding_models.content.status`	`loaded` / `idle`	Content model state (loads on first doc/web search)
`llm.status`	`ok` / `unreachable` / `error`	LLM provider reachability
`tables.*.chunks`	number	Row count per LanceDB table
`crawler.enabled`	bool	Whether crawler tools are registered

The Docker HEALTHCHECK uses this endpoint. Container health turns healthy once the code model is loaded and the index has content.

Prometheus Metrics¶

Metrics are exposed at http://localhost:9091/metrics in Prometheus format (also via the bearer-gated GET /metrics on the API port for remote scraping). They cover query traffic (by tool and codebase), latency, retrieval quality, feedback, and index health — counts / histograms / gauges only, no query text or code. A sample:

codenavi_queries_total{tool,status,codebase} — query volume
codenavi_query_duration_seconds{tool,phase,codebase} — latency by phase
codenavi_index_chunks{codebase} / codenavi_index_files{codebase} — index size per codebase
codenavi_last_reindex_timestamp — Unix timestamp of last reindex
codenavi_feedback_votes{rating} — feedback vote totals

Dashboards (Prometheus + Grafana)¶

Fastest path — turnkey stack. A ready-to-run Prometheus + Grafana that scrapes CodeNavi and auto-loads the dashboard lives in docs/observability/stack/:

cd docs/observability/stack
GRAFANA_ADMIN_PASSWORD='<choose-a-real-password>' docker compose up -d
# Grafana     -> http://localhost:3000   (admin / the password you set)
# Prometheus  -> http://localhost:9090

The CodeNavi — search & index observability dashboard is provisioned automatically (4 collapsible sections — traffic/quality, latency/locks, per-codebase, index/server-health — with $codebase and $tool selectors). Full walkthrough, the Docker-Desktop (Mac/Windows) variant, and the authenticated-remote-scrape option: docs/observability/quickstart.md.

Manual path — already running Prometheus + Grafana? Add this scrape job, then import grafana-dashboard.json via Grafana → Dashboards → New → Import:

scrape_configs:
  - job_name: codenavi
    static_configs:
      - targets: ["127.0.0.1:9091"]

Full self-host guide and metric reference: docs/observability.md and docs/api-reference.md § GET /metrics.

Supported languages¶

Tree-sitter AST-aware chunking (functions, classes, methods extracted by semantic boundaries):

Language	Extension	Since
PHP	`.php`	v1.0.0
JavaScript	`.js`	v1.0.0
TypeScript	`.ts`	v1.0.0
Python	`.py`	v1.0.0
Bash	`.sh`	v1.0.0
Go	`.go`	v1.1.0
Java	`.java`	v1.1.0
Ruby	`.rb`	v1.1.0
Rust	`.rs`	v1.1.0
C#	`.cs`	v1.1.0
Fortran	`.f90`, `.f95`, `.f03`, `.f08`, `.f`, `.for`	v1.1.0

CodeNavi also AST-chunks Perl / CGI (.pl .pm .t .psgi .cgi), Swift (.swift), Kotlin (.kt .kts), and Scala (.scala .sc) — 15 AST-chunked languages in total.

Additional file types indexed with dedicated or line-based fallback chunking: .sql, .json, .tpl (Smarty), .html/.htm, .tmpl (Template Toolkit), .css, .ini, .conf, .yml/.yaml, .ps1/.psm1/.psd1 (PowerShell), .md/.mdx, .txt/.rst. Full matrix: supported-languages.md.

Security scanner rules¶

48 detection rules organized by category:

Category	Rules	Examples
Secret leak (critical)	9	AWS keys, OpenAI, GitHub tokens, Slack tokens, Stripe keys, GCP keys/service accounts, DSN, PEM, FCM
Secret leak (high)	3	JWT, INI credentials
Secret leak (medium)	2	Generic assignments, Stripe publishable keys
Prompt injection (critical)	4	Comment injection (single/block/hash), string delimiter injection — in code
Prompt injection (high)	9	Doc-scoped prose-injection heuristics — instructions embedded in indexed documentation
Prompt injection (medium)	10	Doc-scoped prose-injection heuristics — lower-confidence patterns; AI-directed text in code and docs (override, role-play, direct address, covert action) — tag only
Dangerous function (medium)	5	PHP eval/exec, JS eval/Function, SQL concatenation
PII (medium)	6	Credit cards, IBANs (on by default); SSNs, emails, phone numbers, public IPs (extended set, opt-in)

PII hits redact but never block or quarantine a file. The extended group is opt-in because those patterns saturate configs and fixtures — note the public-IPv4 rule also matches four-part version strings like 1.2.3.4.

Custom rules can be added to data/secret_rules.json. The scanner hot-reloads rules when the file changes — no restart needed — and logs the change in the Security screen's policy-change audit. Files already in the index are re-checked against the edited rules on the next incremental reindex (vectors are kept; no full reindex needed). Use your own rule ids (shipped ids are vendor-managed and may be updated by release pattern revisions); custom PII rules must use a pii_ id prefix so they are stripped from agent-facing threat annotations and counted by the PII counters.

Model provenance¶

CodeNavi uses pre-trained embedding models for search. The code/content embedder (Buric-E4B, our fine-tuned code embedder) is baked into the GA image (or bind-mounted in dev); the reranker is fetched from Hugging Face on first run and cached locally. No fine-tuning is performed on your (customer) data — the embedder is fine-tuned once, by CodeNavi, before shipping.

Model	Version	License	Parameters	Use
`Buric-E4B` (fine-tuned from Qwen3-Embedding-4B, merged checkpoint)	Mounted via deploy	Apache 2.0	4B	Code + content embeddings (2560d)
`cross-encoder/ms-marco-MiniLM-L-6-v2`	Latest	Apache 2.0	22M	Cross-encoder reranking (default)

All models run locally — no data is sent to any external service. Model files are loaded with trust_remote_code=False to prevent arbitrary code execution.

Supply chain¶

SBOM — sbom.json (CycloneDX 1.6) ships with the Docker image at /app/sbom.json
THIRD-PARTY-LICENSES.md — full third-party attribution (docs/THIRD-PARTY-LICENSES.md: every bundled Python package + vendored web assets)
SECURITY.md — vulnerability disclosure policy and security architecture

Removing CodeNavi¶

./setup.sh --purge (Windows: setup.ps1 -Purge) removes the install permanently: it stops and removes the container, removes the image and the model volume, deletes index/, lancedb/, data/, logs/, reports/, .layer-cache/, .env and .update.conf, and prints what it removed.⁵ It shows the list first and asks you to type purge; CODENAVI_PURGE_YES=1 skips the prompt for scripted removal. The codebase it indexed is never touched — the command refuses to run if that codebase sits inside the install directory — and the package files stay, so deleting the folder is the last step. The licence key goes with data/ (the command warns before asking); copy it out first if you may reinstall a purchased key — trial installs fetch it again from the portal. Remove the agent plugin from your editor separately (claude plugin uninstall codenavi). What "permanent" means at the media level — and the manual recipe, if you prefer it — is in the shipped PRIVACY.md, section How to delete all data.

Troubleshooting¶

Moved to its own page: Troubleshooting.

Vendor change reference CN-90. ↩↩
Vendor change reference CN-233. ↩
Vendor change reference CN-289. ↩
Vendor change reference CN-367. ↩
Vendor change reference CN-749. ↩