Installation¶

System Requirements¶

You also need:

• A dbt manifest.json (generated by dbt compile or dbt build)

Remote manifests are supported via DBT_NOVA_MANIFEST_URI (http(s), dbfs, s3, gs).

Quick Install (Recommended)¶

Use the installer script (defaults to slim):

# Public repo (unauthenticated)
curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  bash -s -- --slim --non-interactive

# Private repo (authenticated)
GH_TOKEN="$(gh auth token)"
curl -fsSL -H "Authorization: Bearer ${GH_TOKEN}" \
  https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  DBT_NOVA_GITHUB_TOKEN="${GH_TOKEN}" bash -s -- --slim --non-interactive

Non-interactive examples:

# Public repo: default slim in non-interactive mode
curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  bash -s -- --non-interactive

# Public repo: force slim
curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  bash -s -- --slim --non-interactive

# Private repo: default slim in non-interactive mode
GH_TOKEN="$(gh auth token)"
curl -fsSL -H "Authorization: Bearer ${GH_TOKEN}" \
  https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  DBT_NOVA_GITHUB_TOKEN="${GH_TOKEN}" bash -s -- --non-interactive

# Private repo: force slim
GH_TOKEN="$(gh auth token)"
curl -fsSL -H "Authorization: Bearer ${GH_TOKEN}" \
  https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  DBT_NOVA_GITHUB_TOKEN="${GH_TOKEN}" bash -s -- --slim --non-interactive

The installer places dbt-nova in ~/.local/bin. For bundled installs, it also places models/ next to the binary so Nova auto-discovers it.

Need to decide between local builds, bootstrap contracts, remote prebuilt artifacts, or remote model hydration? See Modes & Combinations.

Optional: Install + Pre-Warm Models¶

If you want users to avoid first-run model downloads, pre-warm during install:

curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  DBT_NOVA_EMBEDDINGS_CACHE_DIR="$HOME/.dbt-nova/models" \
  DBT_NOVA_WARMUP_REQUIRED_MODELS=3 \
  bash -s -- --slim --warm-models --non-interactive

Use the same DBT_NOVA_EMBEDDINGS_CACHE_DIR value in your MCP client config so every client process reuses that cache.

Optional: Install Agent Skills to ~/.agents/skills¶

To install the built-in persona skills (analyst, engineer, governance) into the standard Agent Skills user directory:

curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  bash -s -- --slim --install-skills --non-interactive

To choose a different destination:

curl -fsSL https://raw.githubusercontent.com/joe-broadhead/dbt-nova/master/scripts/install.sh | \
  DBT_NOVA_SKILLS_DIR="$HOME/.codex/skills" \
  bash -s -- --slim --install-skills --non-interactive

Verify Installation¶

export PATH="$HOME/.local/bin:$PATH"
command -v dbt-nova
dbt-nova --version
export DBT_MANIFEST_PATH=/path/to/manifest.json
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | dbt-nova

If you pre-warmed models, verify three required model snapshots exist:

find "$HOME/.dbt-nova/models" -type f \
  \( -path "*/snapshots/*/onnx/model.onnx" -o -path "*/snapshots/*/model.onnx" \) \
  | sed -E 's#/(onnx/)?model\.onnx$##' | sort -u | wc -l

The installer verifies SHA-256 checksums for downloaded archives by default. Set DBT_NOVA_VERIFY_CHECKSUM=0 to skip this check.

To also verify the checksum signature, install cosign and set:

export DBT_NOVA_VERIFY_SIGNATURE=1

Example (explicit checksum+signature verification):

gh release download --repo joe-broadhead/dbt-nova \
  --pattern dbt-nova-linux-x86_64.tar.gz --output dbt-nova-linux-x86_64.tar.gz
gh release download --repo joe-broadhead/dbt-nova \
  --pattern dbt-nova-linux-x86_64.sha256 --output dbt-nova-linux-x86_64.sha256
gh release download --repo joe-broadhead/dbt-nova \
  --pattern dbt-nova-linux-x86_64.sha256.sig --output dbt-nova-linux-x86_64.sha256.sig
gh release download --repo joe-broadhead/dbt-nova \
  --pattern dbt-nova-linux-x86_64.sha256.crt --output dbt-nova-linux-x86_64.sha256.crt

sha256sum -c dbt-nova-linux-x86_64.sha256
cosign verify-blob \
  --signature dbt-nova-linux-x86_64.sha256.sig \
  --certificate dbt-nova-linux-x86_64.sha256.crt \
  dbt-nova-linux-x86_64.sha256

Local Build (Developer)¶

git clone https://github.com/joe-broadhead/dbt-nova.git
cd dbt-nova
cargo build --release
# default is partial (model files only)
bash scripts/warm_models.sh

Binary is at target/release/dbt-nova.

Local Install (Cargo)¶

cargo install --path . --features embeddings --locked

Release Artifacts¶

Published release assets are slim (binary only). Models download on first run or can be pre-warmed with scripts/warm_models.sh.

If you request --bundled and no bundled artifact exists for that release/target, the installer automatically falls back to slim.

Published targets:

• linux-x86_64 (Cloud Run compatible)
• macos-arm64 (Apple Silicon)

Other platforms can build from source.

Default builds include S3/GCS SDK support. If you need a minimal binary, build with --no-default-features and selectively enable embeddings, s3, and gcs.

Example:

gh release download --repo joe-broadhead/dbt-nova \
  --pattern dbt-nova-linux-x86_64.tar.gz --output dbt-nova-linux-x86_64.tar.gz
tar -xzf dbt-nova-linux-x86_64.tar.gz

Installer Script¶

DBT_NOVA_REPO=joe-broadhead/dbt-nova bash scripts/install.sh

The installer defaults to slim and supports:

• DBT_NOVA_INSTALL_FLAVOR=bundled|slim
• DBT_NOVA_INSTALL_SKILLS=1 (install Agent Skills)
• DBT_NOVA_SKILLS_DIR=/custom/skills/path (default: ~/.agents/skills)
• DBT_NOVA_INSTALL_WARM_MODELS=1 (pre-warm model files after install)
• DBT_NOVA_INSTALL_NONINTERACTIVE=1
• DBT_NOVA_INSTALL_DIR=/custom/path
• --bundled, --slim, --warm-models, --install-skills, --skills-dir <path>, --non-interactive, --install-dir <path>
• DBT_NOVA_VERIFY_CHECKSUM=1|0
• DBT_NOVA_VERIFY_SIGNATURE=1|0
• DBT_NOVA_COSIGN_BINARY=cosign

Troubleshooting¶

Common Issues¶

Debug Logging¶

Enable verbose logs to diagnose issues:

DBT_NOVA_LOG=debug dbt-nova

First-Run Model Downloads¶

Slim/source installs download models on first run with embeddings enabled. This happens once and is cached in the configured DBT_NOVA_EMBEDDINGS_CACHE_DIR. If unset, Nova uses models/ next to the binary when present, otherwise <DBT_NOVA_STORAGE_DIR>/.fastembed_cache.

To pre-download models explicitly:

bash scripts/warm_models.sh

scripts/warm_models.sh supports two modes:

• partial (default): download/seed model files only
• full: download/seed model files and run a manifest-scoped warmup to generate embeddings.rkyv.zst and sparse_embeddings.rkyv.zst

To run full warmup:

DBT_NOVA_WARMUP_MANIFEST_PATH=/path/to/manifest.json \
  bash scripts/warm_models.sh full

If direct model downloads fail (for example, restricted access to Hugging Face), scripts/warm_models.sh auto-falls back first to direct cache seeding from Hugging Face URLs, then to seeding models from the latest GitHub release (when a model bundle is available). You can control this behavior with:

• DBT_NOVA_WARMUP_FALLBACK_FROM_HF_DIRECT=1|0
• DBT_NOVA_WARMUP_FALLBACK_FROM_RELEASE=1|0
• DBT_NOVA_WARMUP_REPO=<owner/repo>
• DBT_NOVA_WARMUP_VERSION=<tag|latest>
• DBT_NOVA_WARMUP_REQUIRED_CACHE_FILES=<count> (full mode only, default: 2)

For direct Hugging Face fallback, you can enable checksum verification:

• DBT_NOVA_WARMUP_CHECKSUM_MODE=off|warn|required (default: off)
• DBT_NOVA_WARMUP_CHECKSUM_FILE=/path/to/checksums.txt
• Template manifest: scripts/warm_models.checksums.example

Checksum manifest format is one entry per line:

<sha256> <url>

Example:

3f2c... https://huggingface.co/intfloat/multilingual-e5-base/resolve/main/onnx/model.onnx

required mode fails warmup if a checksum entry is missing or mismatched. warn mode logs and continues when entries are missing.

During direct Hugging Face seeding, downloads are validated against HTTP Content-Length before replacing cached files, and can be additionally guarded by SHA-256 verification when checksum mode is enabled.

Example (pin fallback seed to a specific release tag):

DBT_NOVA_WARMUP_VERSION=v0.1.0 bash scripts/warm_models.sh

See Also¶

• Quick Start - Configure your first MCP client
• MCP Clients - Client-specific setup guides
• Configuration Reference - All environment variables