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