Windows¶

CodeNavi runs on Windows 11 inside Docker Desktop, with your NVIDIA GPU passed through by Docker Desktop's WSL2 backend. You install Docker Desktop, run two PowerShell lines, and from then on CodeNavi is a URL your Windows IDE talks to — http://localhost:8765. You never open a Linux shell, and there is no port proxy to configure.

"No WSL" usually means "no Linux." WSL2 is the layer Docker Desktop uses to run containers and it is the only path to GPU acceleration in Docker on Windows (the legacy Hyper-V engine cannot pass a card through, so it cannot index). Docker Desktop sets WSL2 up and manages it for you.

What you need¶

Windows 11 (Windows 10 21H2+ works the same way).
An NVIDIA GPU, RTX 20-series or newer (compute ≥ 7.5). 24 GiB cards index at full speed; 11–16 GiB is still Tier A, just slower. Pre-RTX cards (GTX 10-series / Pascal) are not supported — the installer checks and stops.³
A recent NVIDIA Windows driver — it carries the WSL2 CUDA runtime (≥ 570.65 for this build). Never install a Linux GPU driver inside WSL; it breaks passthrough.
~45 GB free disk for Docker Desktop, the image and your index. No admin rights are needed to run the installer.
AMD GPUs: Windows is NVIDIA-only. AMD acceleration is a Linux path (GPU compatibility).

Install¶

Install Docker Desktop and start it. Wait for the whale icon to read Engine running. On Windows 11 it enables the WSL2 backend itself. Docker Desktop is free for organisations under 250 employees / USD 10M revenue; larger organisations can use Podman Desktop instead. This is the only thing you install by hand.
Run the install command from your trial email — PowerShell, no admin. The first line saves a script you can read, the second runs it:
```
curl.exe -fsSL "https://codenavi.com/trial/install/<your-token>?os=windows" -o codenavi-install.ps1
powershell -ExecutionPolicy Bypass -File .\codenavi-install.ps1
```
It downloads CodeNavi, verifies every file against the checksums published by codenavi.com, loads the image and installs into %USERPROFILE%\codenavi. It asks one question — the absolute path of the repository to index (Explorer's Copy as path pastes it straight in). An air-gapped package instead unpacks and runs powershell -ExecutionPolicy Bypass -File .\setup.ps1 — see Air-gapped setup.
The installer proves the GPU works. It does not just look for a card — it runs a real CUDA operation inside the container. If the GPU is usable you see GPU: enabled and the autotune picks a batch size for your VRAM. If it is not (old driver, wrong Docker backend, pre-RTX card) it stops with the exact fix rather than silently falling back to CPU, which would be ~100× slower.
Open Connect and wire your IDE. When it finishes, open http://localhost:8765/connect, paste the token it printed, click Build it first → to index, then pick your editor — the wizard hands you a ready-made config with the token filled in. Docker Desktop publishes the port to Windows, so localhost:8765 works from every Windows MCP client with no port proxy and no netsh.

Updates are one command from %USERPROFILE%\codenavi: .\update.ps1 — see Updating CodeNavi.

Connect a Windows IDE¶

Most Windows IDEs speak MCP Streamable HTTP natively and need only the URL and the token. The connect wizard generates each of these; the shapes, for reference:

IDE	Config location	Entry
Claude Code (Windows)	`.mcp.json` in project root	`{"codenavi":{"type":"http","url":"http://localhost:8765/mcp","headers":{"Authorization":"Bearer <token>"}}}`
Cursor	Settings → MCP → Add server	URL `http://localhost:8765/mcp`, transport HTTP, same header
Windsurf	Settings → MCP servers	URL `http://localhost:8765/mcp`
VS Code + Cline / Continue	Extension MCP settings	URL `http://localhost:8765/mcp` — VS Code guide
Google Antigravity	MCP servers panel	Antigravity on Windows
JetBrains AI Assistant / Junie	MCP servers panel	URL `http://localhost:8765/mcp`

Claude Desktop is the exception — it only speaks stdio, so it needs mcp-remote as a bridge. In claude_desktop_config.json:

{
  "mcpServers": {
    "codenavi": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8765/mcp"]
    }
  }
}

Don't pass --header "Authorization: Bearer ..." on Windows — cmd.exe mangles the space in the header value. Use the Claude Desktop connectors path instead, which also covers phones and the Connectors list (HTTPS via Tailscale Funnel or Cloudflare Tunnel — Remote access).

Your card, decoded¶

CodeNavi autotunes to the GPU at startup; you configure nothing.¹

VRAM	What happens
≥ 17 GiB (RTX 4090 / 3090, A5000-class)	Full speed — encode batch 16, reranker on the GPU. A 30k-file repo indexes in minutes.
11 – 16 GiB	Still Tier A — batch 1–4, reranker steps to the CPU while a reindex is encoding. Slower indexing, identical search quality.
8 – 10 GiB	Weights stay int8-resident, batch 2 — ~23 % less indexing throughput, identical search quality.²
Architecture	The image's CUDA build (cu128) covers RTX 20- through 50-series, sm_75 → sm_120.

Sharing the card with Ollama or another workload? CODENAVI_VRAM_BUDGET_GIB in Configuration tells the autotune to leave room.

Self-managed WSL2 install (no Docker Desktop)¶

If you run CodeNavi by hand inside a WSL2 distro with Docker --network=host — not the installer path above — Windows localhost does not reach it automatically, even with networkingMode=mirrored. Two extra steps, once:

Bind to all interfaces in deploy/.env: CODENAVI_HOST=0.0.0.0, then docker compose up -d. Verify inside WSL with ss -tlnp | grep 8765 — it must show 0.0.0.0:8765, or the proxy below returns connection-reset because nothing listens on the WSL eth0 IP.
Add the WSL2 → Windows port proxy from an admin PowerShell:
```
$wslIp = (wsl hostname -I).Trim().Split()[0]
netsh interface portproxy delete v4tov4 listenport=8765 listenaddress=127.0.0.1 2>$null
netsh interface portproxy add v4tov4 listenport=8765 listenaddress=127.0.0.1 connectport=8765 connectaddress=$wslIp
```
connectaddress=localhost does not work — it must be the eth0 IP, which can change on reboot; re-run the snippet (or wrap it in a logon scheduled task) if connectivity breaks. Verify from Windows: curl http://localhost:8765/health.

For a CodeNavi server on a different box, skip the proxy entirely and point the client at the server's LAN address — Remote access → Same LAN. An SSH tunnel onto localhost:8765 would collide with a port proxy if you have both.

Removing CodeNavi¶

powershell -ExecutionPolicy Bypass -File setup.ps1 -Purge in the install folder removes everything the installer created — the container, the image, the five named volumes (<name>-index, -lancedb, -data, -logs, -reports), logs\, .layer-cache\, .env and .update.conf — after listing it and asking you to type purge. Your repository is never touched; the folder itself and Docker Desktop stay. Same contract as setup.sh --purge on Linux: Setup → Removing CodeNavi.

Snags & fixes¶

Symptom	Fix
`GPU present but unusable by the container`	The installer's CUDA test failed. In order: update the NVIDIA Windows driver (≥ 570.65); run `wsl --update`; confirm Docker Desktop → Settings → General → Use the WSL 2 based engine is on.
`compute capability < 7.5`	A pre-RTX card. This build needs RTX 20-series or newer. To index on CPU anyway (much slower, needs lots of RAM): re-run with `$env:CODENAVI_GPU_CPU_OK='1'` set first.
`virtualization is DISABLED`	Docker Desktop cannot start its VM. Enable Intel VT-x / AMD-V in BIOS/UEFI, then in an admin PowerShell run `bcdedit /set hypervisorlaunchtype auto` and reboot.
Container is OOM-killed during a reindex	Docker Desktop's VM defaults to about half your RAM. Create `%USERPROFILE%\.wslconfig` with `[wsl2]` on one line and `memory=12GB` on the next, then restart Docker Desktop.
IDE can't reach `localhost:8765`	Confirm Docker Desktop is running and the container is up (`docker compose ps` in `%USERPROFILE%\codenavi`). No port proxy is needed on the Docker Desktop path.
Raw `curl http://localhost:8765/mcp` closes immediately	Expected — `/mcp` speaks Streamable HTTP, not REST. Smoke-test with `/health`.

Everything else: Troubleshooting.

Vendor change reference CN-233. ↩
Vendor change reference CN-289. ↩
Vendor change reference CN-568. ↩