Vera runs in two modes, and both start from the same setup wizard:

• API mode with the Qwen preset (recommended): qwen/qwen3-embedding-8b plus qwen/qwen3-reranker-8b through OpenRouter with a single shared API key. Measured on the 320-task Semble subset, the Qwen pair with reranking scored 0.8647 nDCG@10 versus 0.8538 for local-only defaults, with recall@1 up three points: the strongest quality configuration Vera ships. Setup is one key entry and the wizard fills the rest.
• Local mode with Potion Code (the easy default): minishlab/potion-code-16M-v2 runs locally on CPU on any supported machine, and indexes the 63-repository Semble corpus in about two minutes. It is what you get with no API key, no account, and no GPU or ONNX Runtime requirement.

The Qwen numbers above are screening measurements on the tuning subset, not full-suite claims. API mode trades a paid endpoint and network latency for measured reranker gains, while local mode is private and runs without an API key.

vera setup downloads model assets into the Vera data directory (see Installation). Jina ONNX backends also install the matching ONNX Runtime library into lib/.

When local reranking is enabled, the Jina ONNX family provides this built-in cross-encoder:

With reranking disabled, the default Potion Code path uses vector/BM25 fusion plus Vera's deterministic ranking heuristics.

These screening results (2026-08-21/22, pre-dating the ranking-signal improvements of v1.3.0; the v1.4.0 local defaults score 0.8538 on the same subset, see benchmarks.md) use Vera's hybrid retrieval with reranking disabled. The first set has 320 Semble tasks; the independent set has 180 tasks from separate repositories.

Within local mode, Potion Code remains the recommended local backend because it runs on all supported machines and has the lowest screening index time among these embedding alternatives. The full benchmark tables and methodology are in benchmarks.md.

Reranking is opt-in through retrieval.reranking_enabled and is off by default. The no-reranker heuristic stack is the baseline for normal searches.

In the 2026-08-23 dual-set screening, every tested cross-encoder scored below that baseline. Scores are 320-task subset / independent set nDCG@10:

Reranking is off by default. Use an API reranker, including the Qwen preset, when you want optional reranking; tested local cross-encoders scored below the no-rerank baseline, with mxbai-rerank-xsmall-v1 the closest. Configure a local model with:

vera config set retrieval.reranking_enabled true

export LOCAL_RERANKER_REPO=mixedbread-ai/mxbai-rerank-xsmall-v1
export LOCAL_RERANKER_REVISION=b5c6e9da73abc3711f593f705371cdbe9e0fe422
export LOCAL_RERANKER_ONNX_FILE=onnx/model_quantized.onnx
export LOCAL_RERANKER_TOKENIZER_FILE=tokenizer.json

See the canonical CodeRankEmbed comparison for the 6-task results and context.

You can point Vera at a different ONNX embedding model without changing the local reranker. These flags apply to the Jina ONNX backend family, not Potion Code.

vera setup --onnx-jina-cuda \
  --embedding-repo Zenabius/CodeRankEmbed-onnx \
  --embedding-pooling cls \
  --embedding-no-onnx-data \
  --embedding-query-prefix "Represent this query for searching relevant code:"

--embedding-repo also accepts a full Hugging Face URL such as https://huggingface.co/Zenabius/CodeRankEmbed-onnx.

vera setup --onnx-jina-cuda \
  --embedding-dir /path/to/model-dir \
  --embedding-onnx-file onnx/model_quantized.onnx \
  --embedding-tokenizer-file tokenizer.json \
  --embedding-dim 768

Use this when you already downloaded or exported the model yourself.

The local cross-encoder can be replaced with an ONNX-compatible model from Hugging Face. The variables above select the recommended mxbai-rerank-xsmall-v1 export. Leave LOCAL_RERANKER_REVISION unset to use the main ref and the legacy cache path. A non-empty revision stores assets under models/<repo>/revisions/<revision>/, so different model revisions do not overwrite one another.

For a custom ONNX embedding model, Vera needs:

• an ONNX model file
• a tokenizer file
• optionally an ONNX external data file

The defaults are:

If your model uses different names, pass the matching --embedding-* flags.

The default Potion Code model runs on all supported machines. Use Jina ONNX with CUDA, ROCm, CoreML, DirectML, or OpenVINO when you want an opt-in alternative. After the first index, vera update . only re-embeds changed files, so updates are fast on any backend.

Reference points, each measured on a different corpus:

Jina ONNX on CPU is a compatibility path; use Potion Code on CPU-only machines.

Interactive setup prompts for the endpoint URL, model ID, API key, and optional reranker. The wizard offers presets for OpenAI, Jina, Voyage, and Qwen (OpenRouter) with exact prefills; the Qwen preset uses qwen/qwen3-embedding-8b + qwen/qwen3-reranker-8b via https://openrouter.ai/api/v1 with a single shared key (paid usage) and the generic rerank protocol (top_n/results) by default:

vera setup --api

The reranker step also configures the wire protocol (auto, generic, or voyage), endpoint path override, and optional task instruction; for the Qwen preset setup auto-applies the generic protocol without prompting to preserve the single-key flow. Qwen via OpenRouter relies on the generic protocol unless overridden. Custom proxies can select generic or voyage via retrieval.reranker_protocol without hostname spoofing.

For non-interactive setup, export the API values first and add --yes:

export EMBEDDING_MODEL_BASE_URL=https://your-embedding-api/v1
export EMBEDDING_MODEL_ID=your-embedding-model
export EMBEDDING_MODEL_API_KEY=your-api-key

# Optional reranker
export RERANKER_MODEL_BASE_URL=https://your-reranker-api/v1
export RERANKER_MODEL_ID=your-reranker-model
export RERANKER_MODEL_API_KEY=your-api-key

vera setup --api --yes

# Reranker protocol and endpoint overrides (also configurable without a TTY)
vera config set retrieval.reranker_protocol generic
vera config set retrieval.reranker_endpoint_path "/rerank"
vera config set retrieval.reranker_task_instruction "Given a query, retrieve relevant code"

For Qwen via OpenRouter non-interactively:

export EMBEDDING_MODEL_BASE_URL=https://openrouter.ai/api/v1
export EMBEDDING_MODEL_ID=qwen/qwen3-embedding-8b
export EMBEDDING_MODEL_API_KEY=your-openrouter-key
export RERANKER_MODEL_BASE_URL=https://openrouter.ai/api/v1
export RERANKER_MODEL_ID=qwen/qwen3-reranker-8b
export RERANKER_MODEL_API_KEY=your-openrouter-key
vera setup --api --yes
vera config set retrieval.reranker_protocol generic

Only model calls leave your machine. Indexing, storage, and search remain local.

When switching between endpoints or local model names that provide identical embeddings, configure aliases so Vera does not require a full re-index.

Set embedding.model_aliases in config or export VERA_EMBEDDING_MODEL_ALIASES:

export VERA_EMBEDDING_MODEL_ALIASES="jina-embeddings-v3,jina-v3;text-embedding-3-small,openai-small"

The syntax uses semicolon-separated groups of comma-separated equivalent model names. Each group must contain at least two names.

On macOS Apple Silicon, CoreML auto-detects unified memory by reading sysctl hw.memsize. Vera treats half of system RAM as the available GPU pool for auto-scaling and caps the CoreML auto batch size at 64 to keep macOS and other applications responsive.

• Custom ONNX options only affect opt-in Jina ONNX local embeddings. API mode and the default Potion Code model are unchanged.
• Query and document prefixes apply to both API mode and local ONNX embeddings. API mode reads EMBEDDING_QUERY_PREFIX and EMBEDDING_DOCUMENT_PREFIX, with model-ID auto-detection when they are unset. Local ONNX uses the corresponding --embedding-query-prefix and --embedding-document-prefix setup flags.
• The stored embedding model identity covers every --embedding-* setting, not just the model name, so changing pooling or either prefix also requires a re-index.
• If you switch local embedding models without configured aliases, re-index the repo so the stored vectors match the active model.
• If your network blocks CLI downloads, use manual-install.md.