CodeNavi — Air-Gapped Setup¶

Install from the signed, self-contained package — nothing on the install machine needs internet access. Index your codebase and start searching in about 5 minutes.

Machine online? The connected setup does all of this with one command and adds small one-command updates — same product, and your code stays just as local.

1. Unpack and install¶

CodeNavi ships as a signed, self-contained package — the tarball from your license email, with the image, models, and license all inside. Unpack it and run the installer:

tar xzf codenavi-*.tar.gz
cd codenavi
./setup.sh --airgap

setup.sh detects your platform (Linux GPU/CPU, or macOS) and your container engine — Docker, or Podman on docker-less Fedora/RHEL hosts (podman guide) — verifies the package, loads the image, writes .env, asks for the absolute path of the codebase to index, and starts the server. On Windows 11: install Docker Desktop and run powershell -ExecutionPolicy Bypass -File .\setup.ps1 instead (no WSL shell). A CUDA GPU is strongly recommended for indexing — RTX 20-series or newer, driver ≥ 570.65; CPU indexing is impractically slow.

2. It's already running¶

./setup.sh --airgap starts the server for you. The embedder (Buric-E4B) is baked into the image; first start downloads only the ~80 MB reranker. Watch it warm up — run this from your install folder, since the container is named after that folder, not codenavi:

docker compose logs -f

Wait for Startup self-test: OK — the server is ready.

3. Verify¶

curl -s http://localhost:8765/health | python3 -m json.tool

You should see "status": "ok". The unauthenticated /health is deliberately terse — version and status, nothing about your code.

To see your codebase and its chunk count, send the token setup.sh generated for you (it's CODENAVI_AUTH_TOKEN in your .env):

curl -s -H "Authorization: Bearer $(grep ^CODENAVI_AUTH_TOKEN= .env | cut -d= -f2-)" \
     http://localhost:8765/health | python3 -m json.tool

4. Connect your AI tool¶

Claude Code¶

setup.sh generates an auth token and writes it to your .env — so the client has to send it, or every tool call comes back 401. Grab it:

grep CODENAVI_AUTH_TOKEN .env

# In your project directory (paste the token from above):
cat > .mcp.json <<'JSON'
{
  "mcpServers": {
    "codenavi": {
      "type": "http",
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
    }
  }
}
JSON

Then start Claude Code — it will auto-connect. Try: "search for authentication logic"

Tools not showing up? That's almost always a missing or mistyped token — check docker compose logs (run from your install folder) for 401.

Claude Desktop¶

Claude Desktop speaks stdio only, so it needs the mcp-remote bridge (Node) — a direct http URL won't connect. In claude_desktop_config.json:

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

Replace YOUR_TOKEN_HERE with CODENAVI_AUTH_TOKEN from your .env. Without it every call returns 401 and the tools never register.

Other MCP clients (Cursor, Windsurf, VS Code, OpenCode, …)¶

Point your MCP client at http://localhost:8765/mcp (Windsurf uses the key serverUrl, not url). Easiest of all: the running server's Connect wizard at http://localhost:8765/connect writes the exact config for each client — see connecting-vscode.md for the per-client shapes.

5. Search¶

Your AI tool now has 33 CodeNavi tools on your codebase (41 with the opt-in crawler) — semantic search, file browsing, call-graph analysis, reindexing, feedback, backup, and more. By default the server advertises an 11-tool core and loads the rest on demand via reveal_tools() (config.md). The ones your agent will reach for first:

Tool	What it does	Example prompt
`semantic_search`	Find code by meaning	"how does payment processing work"
`grep_search`	Find exact text matches	"find all uses of DB_HOST"
`symbol_search`	Find functions/classes	"find the UserAuth class"
`read_file`	Read a file	"show me src/auth/login.php"
`list_directory`	Browse folders	"what's in the controllers directory"
`find_callers`	Who calls this symbol?	"who calls verifyCredentials"
`impact_analysis`	Blast radius of a change	"what breaks if I change PaymentService"

Full catalog — every tool with parameters, return shapes, and examples: API reference.

Remote access / HTTPS¶

Serving a client that is not on this machine? A teammate's laptop on the same LAN needs only the auth token (already on by default) and CODENAVI_HOST=0.0.0.0 on the server; Claude Desktop's Connectors UI, claude.ai and phones need an HTTPS URL on top — a tunnel (Tailscale Funnel, Cloudflare Tunnel) or your own reverse proxy (Caddy / nginx). Full walkthrough: remote-access.md.

What's next¶

Web UI — open http://localhost:8765/ui (nine screens: system/index/chat/crawler/search/graph/security/wiki/settings; see web-ui.md).
Multi-codebase — set CODEBASE_CONFIG in .env to index multiple projects
Full docs — see docs/setup.md for all configuration options
Reindex — after code changes: ./codenavi reindex (incremental — seconds; add --full for a full rebuild)