Local Backend Mode

Local backend mode connects the Web UI to the GitNexus CLI’s HTTP server, allowing you to explore CLI-indexed repositories without re-uploading or re-indexing.

Why Use Backend Mode?

No Re-Indexing

Browse any CLI-indexed repo instantly — no need to re-upload or re-index

No Size Limits

Bypass browser memory constraints. Explore repos with 100k+ files

Persistent Storage

CLI indexes are persistent — refresh the page without losing your graph

AI Chat Access

Use the Web UI’s chat interface with full CLI graph data

How It Works

Backend mode creates a bridge between the Web UI and CLI:

CLI indexes your repositories locally (persistent storage)
gitnexus serve starts an HTTP server on localhost:4747
Web UI auto-detects the local server and offers to connect
All queries route through the HTTP API to the native KuzuDB database

The Web UI becomes a frontend client for the CLI’s graph database. No WASM indexing happens — you’re viewing the native CLI index.

Quick Start

Index Your Repo (CLI)

First, index your repository with the CLI:

cd /path/to/your/repo
npx gitnexus analyze

This creates .gitnexus/ in your repo and registers it globally.

Start the Server

Launch the HTTP server:

npx gitnexus serve

The server starts at http://127.0.0.1:4747 by default.

Custom port or host

# Use a different port
npx gitnexus serve --port 8080

# Bind to all interfaces (warning: allows network access)
npx gitnexus serve --host 0.0.0.0

Open the Web UI

Navigate to:

gitnexus.vercel.app (production)
http://localhost:5173 (if running from source)

Connect

The Web UI will auto-detect the local server and show a connection prompt:

“Local GitNexus server detected. Connect?”

Click Connect to load your CLI-indexed repo.

HTTP API Routes

When connected to the backend, the Web UI uses these API endpoints:

Endpoint	Method	Purpose
`/api/repos`	GET	List all indexed repositories
`/api/repo`	GET	Get repository metadata
`/api/graph`	GET	Download full graph (nodes + edges)
`/api/query`	POST	Execute raw Cypher queries
`/api/search`	POST	Hybrid search (BM25 + semantic)
`/api/file`	GET	Read file content from disk
`/api/processes`	GET	List all execution flows
`/api/process`	GET	Get process detail with steps
`/api/clusters`	GET	List all communities
`/api/cluster`	GET	Get community members

All routes support a ?repo=name query parameter for multi-repo selection.

Multi-Repo Support

The server can serve multiple indexed repositories:

# Index multiple projects
cd ~/projects/app-1
npx gitnexus analyze

cd ~/projects/app-2
npx gitnexus analyze

cd ~/projects/lib-1
npx gitnexus analyze

# Start server (serves all three)
npx gitnexus serve

In the Web UI:

The repo selector (header dropdown) shows all indexed repos
Switch between repos without reloading
Each repo’s graph loads on-demand

Security & CORS

Default binding: The server binds to 127.0.0.1 (localhost only) by default. Only your machine can connect.

CORS policy:

Allows http://localhost:* (local dev)
Allows http://127.0.0.1:* (local dev)
Allows https://gitnexus.vercel.app (production Web UI)
Blocks all other origins

Path traversal protection:

The /api/file endpoint validates all paths
Requests outside the repo root are rejected

Network exposure: If you bind to 0.0.0.0 or a public IP:

Anyone on the network can access your code
Use this only in trusted networks or behind a firewall
Consider setting up authentication (not built-in)

Benefits vs WASM Mode

Feature	WASM Mode	Backend Mode
Max repo size	~5k files	Unlimited
Indexing speed	Slow (WASM)	Fast (native)
Persistence	Session-only	Persistent
Re-index cost	High (every session)	Low (once via CLI)
Network required	No	Localhost only
Graph loading	Immediate	~1-5s download

Auto-Connect URL

Bookmark a direct connection with the ?server query parameter:

https://gitnexus.vercel.app?server=http://localhost:4747

The Web UI will:

Parse the ?server param
Connect to the backend automatically
Load the default repo (first in registry)
Remove the query param from the URL (so refresh doesn’t re-trigger)

Custom server URL: If you run the server on a different port or host, pass it in the URL:

https://gitnexus.vercel.app?server=http://192.168.1.100:8080

Embeddings in Backend Mode

Semantic search works in backend mode:

The CLI generates embeddings during gitnexus analyze
The Web UI uses the server’s /api/search endpoint
The backend runs hybrid search (BM25 + semantic) server-side

You don’t need to wait for browser-based embeddings — search is immediately semantic if the CLI index includes embeddings.

Skipping embeddings in CLI

If you indexed with --skip-embeddings, the backend falls back to BM25-only search:

npx gitnexus analyze --skip-embeddings

This is faster but less accurate for semantic queries.

AI Chat in Backend Mode

The Web UI’s AI chat routes all tool calls through the backend:

query_code → /api/search
run_cypher → /api/query
read_file → /api/file
get_symbol_references → Cypher via /api/query
list_processes → /api/processes

The agent sees the full CLI-indexed graph — no memory limits.

Troubleshooting

Web UI doesn't auto-detect the server

Ensure gitnexus serve is running (check terminal output)
Verify the server is on http://localhost:4747 (default)
Check browser console for CORS errors
Manually enter the server URL in the connection dialog

Connection refused or timeout

Confirm the server is running: curl http://localhost:4747/api/repos
Check firewall settings (may block local connections)
Try http://127.0.0.1:4747 instead of localhost

Empty repo list

You haven’t indexed any repositories yet:

cd /path/to/repo
npx gitnexus analyze

Then restart gitnexus serve.

Graph loading is slow

Large repos take time to serialize and download:

50k nodes: ~5-10 seconds
100k nodes: ~20-30 seconds

This is a one-time cost per repo. Subsequent queries are instant.

CORS error from custom domain

The server only allows localhost and gitnexus.vercel.app. If you’re hosting the Web UI elsewhere:

Fork the CLI repo
Edit gitnexus/src/server/api.ts (line 112)
Add your domain to the CORS allowlist
Run from your fork: npx my-fork serve

Architecture Details

Connection Flow

KuzuDB Connection Pooling

The server uses a lazy connection pool (from LocalBackend):

Connections open on first query per repo
Max 5 concurrent connections
5-minute TTL — idle connections close automatically
Graceful shutdown on SIGINT/SIGTERM

This allows the server to handle many indexed repos without exhausting file descriptors.

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

Local Backend Mode

Why Use Backend Mode?

No Re-Indexing

No Size Limits

Persistent Storage

AI Chat Access

How It Works

Quick Start

HTTP API Routes

Multi-Repo Support

Security & CORS

Benefits vs WASM Mode

Auto-Connect URL

Embeddings in Backend Mode

AI Chat in Backend Mode

Troubleshooting

Architecture Details

Connection Flow

KuzuDB Connection Pooling

Next Steps

CLI Overview

MCP Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

​Why Use Backend Mode?

No Re-Indexing

No Size Limits

Persistent Storage

AI Chat Access

​How It Works

​Quick Start

​HTTP API Routes

​Multi-Repo Support

​Security & CORS

​Benefits vs WASM Mode

​Auto-Connect URL

​Embeddings in Backend Mode

​AI Chat in Backend Mode

​Troubleshooting

​Architecture Details

​Connection Flow

​KuzuDB Connection Pooling

​Next Steps

CLI Overview

MCP Integration

Build docs developers (and LLMs) love

Why Use Backend Mode?

How It Works

Quick Start

HTTP API Routes

Multi-Repo Support

Security & CORS

Benefits vs WASM Mode

Auto-Connect URL

Embeddings in Backend Mode

AI Chat in Backend Mode

Troubleshooting

Architecture Details

Connection Flow

KuzuDB Connection Pooling

Next Steps