Installation

GNO currently requires Bun as its JavaScript runtime.

Beta runtime note: This is still the current beta path. GNO does not yet bundle Bun for end users. The app and API now surface this explicitly in the dashboard bootstrap panel so runtime assumptions are visible instead of implicit.

Quick Install

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install GNO
bun install -g @gmickel/gno

# Verify installation
gno doctor

If you want a guided setup after install, run gno serve and open http://localhost:3000. The first-run dashboard can add a folder, explain health, show bootstrap/runtime status, and trigger model downloads without more terminal work.

If you want a headless long-running process instead, run:

gno daemon

gno daemon keeps the same watch/sync/embed loop running without the Web UI or desktop shell. It stays in the foreground; use nohup, launchd, or systemd if you want supervision.

SDK / Library Install

bun add @gmickel/gno

import { createGnoClient } from "@gmickel/gno";

macOS users: Vector search requires Homebrew SQLite. See macOS setup below.

Requirements

Component Version Notes
Bun 1.0+ JavaScript runtime
macOS 12+ Homebrew SQLite required for vector search
Linux Any Works out of box
Windows 10+ Experimental, some tests may fail

Platform-Specific Setup

macOS

Vector search requires Homebrew’s SQLite (Apple’s bundled SQLite lacks the extension API):

brew install sqlite3

GNO auto-detects Homebrew SQLite at /opt/homebrew/opt/sqlite3/lib/libsqlite3.dylib.

Run gno doctor to verify:

gno doctor

Expected output:

✓ config - Config loaded: ~/.config/gno/config.yml
✓ database - Database found: ~/.local/share/gno/index.sqlite
✓ sqlite-vec - sqlite-vec loaded (vv0.1.7-alpha.2)

If sqlite-vec shows a warning, BM25 search still works but vector search is disabled.

Linux

Works out of box. No additional dependencies needed.

gno doctor

Windows

Experimental support. Core functionality works, but some tests may fail.

gno doctor

Capabilities Matrix

Feature Requirements Command
BM25 search None (works everywhere) gno search <query>
Vector search sqlite-vec extension gno vsearch <query>
Hybrid search sqlite-vec + embed model gno query <query>
Reranking rerank model cached gno query (auto-enabled)
AI answers gen model cached gno ask <query> --answer

Model Setup (Optional)

GNO downloads AI models on first use. Pre-download to avoid first-run delays:

# Download all models (slim-tuned preset, ~1GB)
gno models pull --all

# Or download specific models
gno models pull --embed   # Required for vector search
gno models pull --rerank  # Optional, improves ranking
gno models pull --expand  # Required for local query expansion
gno models pull --gen     # Required for --answer

Model presets control disk usage:

Preset Embed Rerank Expand Answer
slim-tuned bge-m3-Q4 Qwen3-Reranker-0.6B-Q8 GNO Slim Tuned expansion Qwen3-1.7B-Q4
slim bge-m3-Q4 Qwen3-Reranker-0.6B-Q8 Qwen3-1.7B-Q4 Qwen3-1.7B-Q4
balanced bge-m3-Q4 Qwen3-Reranker-0.6B-Q8 Qwen2.5-3B-Q4 Qwen2.5-3B-Q4
quality bge-m3-Q4 Qwen3-Reranker-0.6B-Q8 Qwen3-4B-Q4 Qwen3-4B-Q4

Change preset in config:

models:
  activePreset: slim-tuned

Or change it later in the web UI from the preset picker on the dashboard.

The dashboard also shows:

  • whether models will auto-download or stay manual/offline
  • where the cache lives
  • current cache size on disk
  • which preset roles are still missing

Verification

Run gno doctor --json to check all components:

gno doctor --json

{
  "healthy": true,
  "checks": [
    { "name": "config", "status": "ok", "message": "Config loaded" },
    { "name": "database", "status": "ok", "message": "Database found" },
    { "name": "sqlite-vec", "status": "ok", "message": "sqlite-vec loaded" },
    { "name": "embed-model", "status": "ok", "message": "embed model cached" },
    {
      "name": "rerank-model",
      "status": "warn",
      "message": "rerank model not cached"
    },
    { "name": "gen-model", "status": "ok", "message": "gen model cached" }
  ]
}

Status meanings:

  • ok - Component working
  • warn - Optional component missing (functionality limited)
  • error - Required component failing

Troubleshooting

“sqlite-vec not available” (macOS)

# Install Homebrew SQLite
brew install sqlite3

# Verify it's found
ls /opt/homebrew/opt/sqlite3/lib/libsqlite3.dylib

Models fail to download

Check network connectivity and disk space (~2GB needed for all models).

# Check model cache location
gno models path

# Clear and retry
gno models clear
gno models pull --all

Permission errors

Ensure write access to:

  • Config: ~/.config/gno/
  • Data: ~/.local/share/gno/
  • Cache: ~/Library/Caches/gno/ (macOS) or ~/.cache/gno/ (Linux)

Uninstall

# Remove binary
bun remove -g @gmickel/gno

# Remove config and data (optional)
rm -rf ~/.config/gno
rm -rf ~/.local/share/gno
rm -rf ~/Library/Caches/gno  # macOS
rm -rf ~/.cache/gno          # Linux

Next Steps