Skip to content

Model compatibility check

Before you install models or start the provider client as a daemon, you can check which approved Flockadoo models are likely to fit on this machine.

The command detects local hardware and scores each approved build. It does not start the provider daemon and does not need an API key. flockadoo setup uses the same scoring when it asks which model to run.

It reads the public approved-model catalog from https://core.flockadoo.ai by default. It does not read your provider configuration file unless you explicitly pass a different URL with --catalog-url.

On Windows, compatibility lists llama_cpp builds. On macOS the default is vllm-metal. Pass --engine llama_cpp to score the llama.cpp rows instead. Untagged vLLM rows are not offered on Windows. See Approved model builds.

Requirements

Platform What it uses
Linux + NVIDIA nvidia-smi for GPU name, driver, CUDA, VRAM total/free
Windows + NVIDIA nvidia-smi (same as Linux) when the NVIDIA driver is on PATH
macOS (Apple Silicon) system_profiler for GPU name; unified memory from system RAM
CPU-only / Windows without NVIDIA System RAM with a slow/CPU warning

Intel Macs are not supported.

Commands

flockadoo compatibility
flockadoo compatibility --provider-type vllm
flockadoo compatibility --engine llama_cpp
flockadoo compatibility --json
flockadoo compatibility --catalog-url https://core.flockadoo.ai
flockadoo compatibility --offline-catalog ./approved-models.json
Flag Purpose
--provider-type vllm, llama_cpp, or omit
--engine vllm, vllm-metal, or llama_cpp. Default: inferred from this OS (vllm on Linux, vllm-metal on macOS, llama_cpp on Windows)
--catalog-url Flockadoo API base (default https://core.flockadoo.ai)
--offline-catalog Local JSON in the same shape as the public catalog
--json Machine-readable output for scripts
--show-too-large Include too_large rows (default: on)

For example, to use another Flockadoo API deployment:

flockadoo compatibility --catalog-url https://api.example.com

Statuses

Status Meaning
runs_well Comfortable headroom
fits Should load with normal overhead
tight Little headroom; may struggle under load
too_large Unlikely to fit
unknown Missing size or usable memory

Scoring uses each build’s public min_size_bytes plus a conservative runtime overhead. When the catalog sets max_model_len, a KV cache term is added on top. If the catalog also carries kv_cache_bytes_per_token (the model’s exact per-token KV cost), the client uses it directly: required = weights × 1.2 + kv_cache_bytes_per_token × max_model_len. For example, a Qwen 7B-class build (57,344 bytes/token) at 128k context adds ~7 GiB of KV cache. Without that field, the client falls back to an estimate (~3% of weight size per 8k tokens). A 128k target can still flip a mid-VRAM card to too_large; a 7B at 128k should still fit a 96 GB Mac. On Apple Silicon, only a fraction of unified memory is treated as usable so the OS still has headroom. On multi-GPU Linux or Windows hosts, v1 scores against the largest single GPU.

Approved vLLM builds are BF16 7B-class weights. Plan on 32 GB of system memory and 24 GB NVIDIA VRAM on Linux; on Windows 32 GB of RAM plus a fixed 64 GB page file (or 64 GB of RAM) and 24 GB NVIDIA VRAM; or 48 GB unified memory on a Mac. See Software and hardware requirements.

This is a fit check only — it does not estimate tokens/sec.

Troubleshooting

Every model is unknown

If every row shows 0 B and model size unavailable in catalog, the API response does not include a positive min_size_bytes value. Update the Flockadoo API deployment and confirm the approved builds contain measured sizes.

Catalog request fails

An HTTP 522 response means the API origin timed out behind Cloudflare. It is not caused by a missing provider client configuration file. Retry after the API is available, pass another deployment with --catalog-url, or use --offline-catalog.

Linux or Windows GPU is not detected

Run nvidia-smi directly. If it is unavailable, install the NVIDIA driver and ensure the command is on PATH. In containers, expose the GPU with the NVIDIA container runtime.