---
title: "HeliosDB-Nano pilot deployment"
---

# HeliosDB-Nano pilot deployment

A single-command install of HeliosDB-Nano + the code-graph indexer
+ the MCP endpoint into a hidden git-ignored directory inside any
git repo. Validated end-to-end during the FR-1 pilot on Nano's own
`src/` tree (cold-index 128 s, warm re-index 12 ms).

## Prerequisites

- Linux or macOS (Windows pilot is a separate FR).
- A git working tree.
- Either: a Cargo toolchain (Rust 1.85 or newer) **or** a
  pre-built `heliosdb-nano` release binary on `$PATH`.

## Install

From any git repo root:

```sh
sh scripts/install-nano-pilot.sh
```

Or from a remote checkout (read the script first if you don't
trust the source):

```sh
curl -fsSL https://raw.githubusercontent.com/HeliosDatabase/HeliosDB-Nano/main/scripts/install-nano-pilot.sh | sh
```

After the installer runs you have:

| Path | Purpose |
|---|---|
| `.helios-nano/bin/heliosdb-nano` | The binary, built with `code-graph,graph-rag,mcp-endpoint`. |
| `.helios-nano/data/` | RocksDB data files. |
| `.helios-nano/config.toml` | Loopback-only defaults. |
| `.git/hooks/pre-commit` | Re-indexes touched files on every commit. |
| `.gitignore` | The `.helios-nano/` line, appended idempotently. |

## First index (cold)

```sh
HELIOS=.helios-nano
$HELIOS/bin/heliosdb-nano code-graph index \
    --data-dir $HELIOS/data \
    --table src
```

Timing on a medium repo (~10 k LOC): 5 – 30 s.

## Warm re-index

The git pre-commit hook runs the same indexer on the changed
file set, so subsequent edits cost ~tens of ms thanks to the
content-hash gate (`code_graph::storage::sha256_hex`).

You can trigger a warm pass manually:

```sh
git diff --cached --name-only --diff-filter=ACMR | \
  $HELIOS/bin/heliosdb-nano code-graph hook \
    --data-dir $HELIOS/data \
    --repo-root . \
    --source-table src
```

## Wire into your AI client

:::caution[No engine subcommand]
HeliosDB Nano has no `mcp-server` subcommand. For stdio MCP clients, use the
separate HeliosDB CodeKB MCP server (`cargo install heliosdb-codekb-mcp`); for HTTP,
WebSocket or SSE, run `heliosdb-nano start` from a build with `mcp-endpoint` and use
`POST /mcp`, `/mcp/ws` or `/mcp/sse`.
:::

Drop this snippet into `~/.config/claude/claude.json` (or the
equivalent for Cursor / Codex / Continue):

```json
{
  "mcpServers": {
    "helios-nano-myrepo": {
      "command": "/abs/path/to/.helios-nano/bin/heliosdb-nano",
      "args": ["mcp-server", "--db", "/abs/path/to/.helios-nano/data"]
    }
  }
}
```

The 16-tool catalogue plus the auto-registered LSP / GraphRAG
extensions show up in the agent's tool list immediately.

## Run the flagship query

```json
{
  "name": "helios_graphrag_search",
  "arguments": {
    "seed_text": "ProductQuantizer",
    "hops": 2,
    "limit": 30
  }
}
```

The agent gets back the seed code symbol plus its 2-hop subgraph
with hop_distance + node_kind + path metadata.

## Tear down

```sh
rm -rf .helios-nano/
git restore --source HEAD --staged --worktree .gitignore .git/hooks/pre-commit
```

(or, if the hook isn't tracked, just delete `.git/hooks/pre-commit`).

## See also

- [Code-graph tutorial](/docs/nano/guides/tutorials/code_graph_tutorial/) — architecture + feature flag map.
- [troubleshooting.md](https://www.heliosdb.com/docs/nano/features/code-graph/troubleshooting/) — common gotchas.