microsoft/obeaver

This section walks you through everything needed to get oBeaver up and running on your machine.

Requirements

• Python 3.12+
• Foundry Local system daemon (macOS / Windows only, for Foundry Local engine):

  brew install microsoft/foundrylocal/foundrylocal   # macOS
  winget install Microsoft.FoundryLocal              # Windows
  

Note: On Linux, Foundry Local is not available. The engine defaults to ORT.

---

Installation

git clone https://github.com/microsoft/obeaver.git
cd obeaver
pip install -e .

---

Initialise Model Directory

After installation, configure the default model save location. This creates the required sub-folders (ort/, foundrylocal/, cache_dir/) automatically:

obeaver init

You can also pass a path directly:

obeaver init ~/my-models

💡 Tip: The configuration is saved to ~/.obeaver/config.json. Run obeaver with no arguments to view the welcome banner showing your current model directory paths at any time.

---

Environment Check

Verify your setup:

obeaver check

────────────────── obeaver environment check ──────────────────
Platform: macOS

✓  Foundry Local CLI found: /usr/local/bin/foundry
   Version: 0.8.119
✓  foundry-local-sdk (Python) is installed.
   SDK version: 0.5.1
────────────────────────────────────────────────────────────────

List Local Models

Use obeaver models to list all local models discovered under the configured model directory:

obeaver models

This scans the foundrylocal/ and ort/ sub-folders and shows each model's name, engine type, and category (Text, Vision + Text, or Embeddings).

---

Getting Models

Before using oBeaver, you need models. Choose based on your engine:

Foundry Local catalog (macOS/Windows)

No manual download needed — pass a catalog alias and Foundry handles it:

obeaver run phi-4-mini   # auto-downloads on first use

💡 Tip: Run obeaver models to list all locally cached models. On macOS/Windows, run foundry model list to browse the full Foundry Local catalog for more aliases.

ONNX GenAI models (all platforms)

Download pre-converted models from Hugging Face. Look for repos tagged onnxruntime-genai or use Olive to convert your own.

🔑 Hugging Face Authentication Required: Downloading models with hf download or obeaver convert requires Hugging Face CLI authentication. If you haven't logged in yet:

pip install -U huggingface-hub
huggingface-cli login

You will be prompted to enter an access token. If you don't have one, visit huggingface.co/settings/tokens to create a free account and generate a token. Some gated models (Llama, Mistral, etc.) also require accepting the model's license on the Hugging Face model page before download.

Alternatively, set the environment variable: export HF_TOKEN='your_token_here'

Run obeaver check to verify your Hugging Face authentication status.

# install the HF CLI
pip install -U "huggingface_hub[cli]"

# download Phi-3 mini (INT4, CPU-optimised)
hf download microsoft/Phi-3-mini-4k-instruct-onnx \
  --include "cpu_and_mobile/cpu-int4-rtn-block-32-acc-level-4/*" \
  --local-dir ./models/ort/phi3-mini-int4

Embedding models

Download from huggingface.co/onnx-community:

| Model | Params | HF repo | |-------|--------|---------| | Qwen3-Embedding | 0.6B | onnx-community/Qwen3-Embedding-0.6B | | Qwen3-Embedding | 4B | onnx-community/Qwen3-Embedding-4B | | Qwen3-Embedding | 8B | onnx-community/Qwen3-Embedding-8B | | EmbeddingGemma | 300M | onnx-community/embeddinggemma-300m-ONNX |

hf download onnx-community/Qwen3-Embedding-0.6B \
  --local-dir ./models/Qwen3-Embedding-0.6B

---