---
title: Installation
description: Install GNO with Bun, verify local runtime requirements, and get the local knowledge workspace ready on macOS, Linux, or Windows.
keywords: install gno, bun install gno, local knowledge workspace install, hybrid search install
---

# Installation

GNO currently requires [Bun](https://bun.sh/) 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

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

# Install GNO
bun install -g @gmickel/gno

# Verify installation
gno doctor
```

Release packages are smoke-tested with `bun run test:package`, which installs
the packed npm tarball into isolated temp paths and verifies packaged
`gno --version`, `gno --help`, and `gno doctor --json` before publish.

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:

```bash
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

```bash
bun add @gmickel/gno
```

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

> **macOS users**: Vector search requires Homebrew SQLite. See [macOS setup](#macos) below.

## Requirements

| Component | Version | Notes                                       |
| --------- | ------- | ------------------------------------------- |
| Bun       | 1.0+    | JavaScript runtime                          |
| macOS     | 12+     | Homebrew SQLite required for vector search  |
| Linux     | x64     | CLI supported; desktop remains experimental |
| Windows   | 11+ x64 | CLI supported; desktop packaging in beta    |

## Platform-Specific Setup

### macOS

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

```bash
brew install sqlite3
```

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

Run `gno doctor` to verify:

```bash
gno doctor
```

Expected output:

```
✓ config - Config loaded: ~/.config/gno/config/index.yml
✓ database - Database found: ~/.local/share/gno/index.sqlite
✓ sqlite-vec - sqlite-vec loaded (v0.1.9)
```

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

### Linux

Current recommendation:

- `linux-x64` CLI is supported
- desktop shell on Linux is still experimental
- Ubuntu `22.04+` is the first sensible Linux desktop baseline if/when that
  path is published

No additional dependencies are required for the CLI path.

```bash
gno doctor
```

### Windows

Current recommendation:

- target `windows-x64`
- use the CLI today via Bun/global install
- treat packaged desktop artifacts as beta/runtime-validated, not broad GA
- `windows-arm64` is not supported yet

```bash
gno doctor
```

See also:

- [Packaging Matrix](PACKAGING.md)
- [Windows Support](WINDOWS.md)
- [Desktop Beta Rollout](DESKTOP-BETA-ROLLOUT.md)

## 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:

```bash
# 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
```

GNO validates cached/local `.gguf` files before loading them. If a network
proxy, firewall, captive portal, or Hugging Face HTML error page is cached
instead of a model, GNO removes the bad cached file and asks you to retry with
`gno models pull --force`.

Model presets control disk usage:

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

Change preset in config:

```yaml
models:
  activePreset: slim-tuned
```

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

Need model overrides instead of a full preset switch?

- [Per-Collection Models](guides/per-collection-models.md)
- [Bring Your Own Models](guides/bring-your-own-models.md)
- [Code Embeddings](guides/code-embeddings.md)

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:

```bash
gno doctor --json
```

```json
{
  "healthy": true,
  "checks": [
    { "name": "config", "status": "ok", "message": "Config loaded" },
    { "name": "database", "status": "ok", "message": "Database found" },
    {
      "name": "fts5-snowball",
      "status": "ok",
      "message": "fts5-snowball loaded"
    },
    { "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" },
    {
      "name": "embedding-fingerprint",
      "status": "ok",
      "message": "current abc123def456, 0 pending/stale, 0 legacy, 1 group"
    }
  ]
}
```

Status meanings:

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

On Windows x64, `gno doctor --json` is also the quickest way to confirm the
packaged/runtime proof path: FTS5, vendored `fts5-snowball.dll`, and
`sqlite-vec` should all report `ok`.

## Troubleshooting

### "sqlite-vec not available" (macOS)

```bash
# 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).

```bash
# 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

```bash
# 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

- [Quickstart Guide](QUICKSTART.md) - Index and search in 5 minutes
- [Daemon Mode](DAEMON.md) - Headless continuous indexing
- [CLI Reference](CLI.md) - Full command documentation
- [Configuration](CONFIGURATION.md) - Customize collections and settings
