# Bring your own ONNX or GGUF model

Xybrid supports bringing your own ONNX or GGUF models from Hugging Face or
local files. The public registry is a curated starting point, not a model
allowlist. A model does not need a public registry entry to be used locally.

Support is based on the model format and runtime contract. For a particular
model to execute, its operators or architecture must be supported by the
runtime bundled with your SDK, its inputs and outputs must match the execution
pipeline, and the model must fit the target device's resources.

## Prepare the model

1. Identify the model's task, architecture, weight files and required tokenizer,
   configuration, preprocessing and postprocessing assets.
2. Create `model_metadata.json` describing the files and execution pipeline.
   The `xybrid-init` agent skill helps inspect a Hugging Face repository or
   local directory and prepare this metadata. Discover the current workflow at
   https://www.xybrid.ai/.well-known/agent-skills/index.json.
3. Check runtime compatibility on your target SDK and platform:
   - ONNX: supported operators/opset, input/output names and types, tensor
     shapes, external tensor data and matching preprocessing/postprocessing.
   - GGUF: an architecture supported by the SDK's bundled llama.cpp backend,
     the `llm-llamacpp` runtime feature, and any required tokenizer, chat
     template or companion assets.
   - Both: sufficient device memory, storage and platform support.
4. Load the prepared local model through the target SDK's local model loader.
   In a core SDK checkout, use the `test-model` skill for a real inference run.
   Validate the output against the model's task; generating valid metadata
   alone does not prove that inference works.

SafeTensors support is architecture-specific. It is not a generic substitute
for ONNX or GGUF support; verify the target SDK's execution templates and
features before choosing it.

## Using the registry MCP server

Connect a remote MCP client to `https://registry.xybrid.dev/mcp`. No account
or API key is required. `list_models`, `get_model` and `resolve_model` inspect
the curated catalog and resolve downloads; they do not execute inference,
download weights, register custom models or modify your project.

An unknown catalog ID means the registry has no entry under that ID. A
`BACKEND_REQUIRED` or `OS_VERSION_UNSUPPORTED` error describes the selected
catalog variant's requirements. Neither is a verdict on every possible local
ONNX or GGUF artifact for that model.

See https://github.com/xybrid-ai/xybrid for runtime features and local-loading
APIs in your SDK version, and https://docs.xybrid.dev/en/docs/quickstart for
the SDK quickstart. Local inference needs no Xybrid account or API key.
