Dark-Alex-17/coyote
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity
Page: Model Sync
Pages
AIChat Migration Agents Bash Prompt Helpers Clients Custom Bash Tools Custom Tools Environment Variables Getting Started Graph Agents Home Installation MCP Servers Macros Memory Model Sync Patches RAG REPL Prompt REPL Roles Sandboxes Sessions Sharing Configurations Shell Integrations Skills TODO System Themes Tools Vault
Clone
1
Model Sync
Alex Clarke edited this page 2026-05-28 16:35:26 -06:00
Table of Contents

Coyote ships with a registry of supported models baked into the binary at build time, sourced from the models.yaml file in the upstream repository. This registry is what tells Coyote which models exist for each provider, their context windows, capabilities (function calling, vision, etc.), and pricing.

There are two situations where the baked-in registry isn't enough:

  1. A provider released a new model and the upstream models.yaml hasn't been updated yet (or hasn't been released in a new Coyote version).
  2. You want to use a model Coyote doesn't know about. This could be a self-hosted model, a private fine-tune, or a model exposed via an openai-compatible provider.

For both cases, Coyote supports a local override file: models-override.yaml. You can populate it automatically with coyote --sync-models, or hand-author it for custom models. This page covers both mechanisms.

models-override.yaml

Overview

On startup, Coyote checks for a models-override.yaml file in your Coyote configuration directory. If the file is present and valid, it is loaded as the complete model registry instead of the baked-in models.yaml. If the file is missing, malformed, or the version stamp doesn't match your installed Coyote, Coyote silently falls back to the baked-in registry.

⚠️ The override file replaces the entire registry. It does not extend it.

If you hand-author an override file with only your custom model, you will lose access to every built-in model. To add a custom model while keeping the built-ins, copy the entire upstream models.yaml first and then append your additions. See Hand-Authoring below.

Location

The file lives in your Coyote configuration directory as models-override.yaml. To find your config directory:

coyote --info | grep 'config_dir' | awk '{print $2}'

The full path is therefore <coyote-config-dir>/models-override.yaml. If $COYOTE_CONFIG_DIR is set, the file is loaded from that directory instead. See Environment Variables for the full set of path overrides.

File Format

The file has two top-level keys, version and list:

version: "<coyote-version>"           # Must match your installed Coyote version
list:                                 # List of providers, each with their models
  - platform: openai
    models:
      - name: gpt-6
        type: chat
        max_input_tokens: 400000
        max_output_tokens: 16384
        supports_function_calling: true
        supports_vision: true
      # ...more models
  - platform: claude
    models:
      - name: claude-opus-5
        type: chat
        # ...

The schema of each entry in list: is identical to a top-level provider entry in the upstream models.yaml. When in doubt about a field, look up an existing model from the same provider as a reference.

Coyote also supports per-model patch: blocks here for request modifications. See Patches for details.

Version Compatibility

The version: field must equal your installed Coyote version. Check your version with:

coyote --version

If the versions disagree, Coyote treats the override file as unusable and silently falls back to the baked-in registry. Your custom or synced models will be invisible. To recover after a Coyote upgrade:

  • If the file was auto-generated: Re-run coyote --sync-models to regenerate it with the new version stamp.
  • If you hand-authored the file: Update the version: field to match your new Coyote version. The model schema
  • rarely changes, but skim the release notes for any model-config changes between versions.

Hand-Authoring (custom models)

If you want to add a model Coyote doesn't ship with (e.g. a private fine-tune, a self-hosted Ollama model, or a model exposed via an openai-compatible provider), you need to author the entire registry, not just your additions. The recommended workflow:

  1. Run coyote --sync-models to materialize a current models-override.yaml that mirrors the upstream models.yaml.
  2. Open the file in your editor.
  3. Find the appropriate platform: entry (or add a new one).
  4. Append your custom model under models:.

Example: Adding a private fine-tune to the openai-compatible provider:

version: "0.5.0"
list:
  # ...all the existing providers from the sync...
  - platform: openai-compatible
    models:
      # ...existing openai-compatible models...
      - name: my-private-fine-tune
        type: chat
        max_input_tokens: 128000
        max_output_tokens: 4096
        supports_function_calling: true
        input_price: 0
        output_price: 0

Heads up: Your hand-edits are erased the next time you run coyote --sync-models, because the sync overwrites the file with whatever it fetched from sync_models_url. If you want to mix custom models with synced models permanently, point sync_models_url at a fork of models.yaml that includes your additions. See Pointing at a Custom Registry.

Syncing Models

Overview

coyote --sync-models fetches a fresh models.yaml from a configured URL and writes it as your local models-override.yaml. Use this when the model registry shipped with your Coyote binary lags behind the latest provider releases without having to wait for a Coyote release.

Quick Start

coyote --sync-models

You'll see output like:

✓ Fetched 'https://.../models.yaml'
✓ Updated '/home/<user>/.config/coyote/models-override.yaml'

After the sync, any new models are immediately available. You can confirm this with coyote --list-models or set one explicitly with --model <name>.

Configuration

The URL that --sync-models fetches from is controlled by the sync_models_url setting in your config.yaml:

sync_models_url: https://example.com/path/to/models.yaml

A sensible default ships out of the box (pointing at the upstream Coyote models.yaml), so this setting is optional unless you want to point at a fork or a custom registry. See the example config file for the current default value.

The URL can also be overridden at runtime via the COYOTE_SYNC_MODELS_URL environment variable, which is handy for one-off syncs against a different source. See Environment Variables.

What --sync-models Does

Under the hood, the command performs these steps:

  1. Fetches the file at sync_models_url over HTTPS.
  2. Parses it as a list of provider/model entries (the same format as the upstream models.yaml).
  3. Wraps the list in the models-override.yaml envelope, stamping it with your installed Coyote version.
  4. Writes the result to <coyote-config-dir>/models-override.yaml, creating the directory if needed.

Any previous models-override.yaml is overwritten, including hand-edits.

When to Sync

  • A provider released a new model and Coyote's built-in registry is behind.
  • You upgraded Coyote and want a fresh model list stamped with the new version (also resolves an out-of-date override silently falling back to the baked-in registry).
  • You maintain a fork of models.yaml for your team and want everyone to pull the latest revision.

You generally do not need to sync just because you reinstalled Coyote. The baked-in models.yaml updates with every Coyote release. Syncing is the workaround for the lag between provider releases and Coyote releases.

Pointing at a Custom Registry

If your team maintains its own models.yaml (e.g. to track private deployments or fork the upstream registry with additions), point sync_models_url at it:

# config.yaml
sync_models_url: https://raw.githubusercontent.com/my-team/coyote-models/main/models.yaml

The file at that URL must be a valid Coyote models.yaml; a list of platform: entries, each with their models:. The wrapping version: / list: envelope is added by --sync-models automatically; do not include it in the source file.

Troubleshooting

A synced model isn't showing up

  • Confirm the sync completed without errors: coyote --sync-models should print ✓ Updated lines.
  • Confirm the file was written to the expected path: coyote --info | grep config_dir.
  • Confirm the model is actually in the upstream source you synced from: curl <sync_models_url> | grep <model-name>.
  • Confirm the version: field in models-override.yaml matches coyote --version. A mismatch causes a silent fallback to the baked-in registry.

Sync fails to fetch the URL

Network issue or wrong URL. Check sync_models_url (or COYOTE_SYNC_MODELS_URL) and verify the URL is reachable with curl.

I synced and now my hand-authored custom model is gone

--sync-models overwrites the entire models-override.yaml. To preserve custom models, either:

  • Maintain them in a fork of models.yaml and point sync_models_url at the fork, or
  • Re-add them manually to models-override.yaml after each sync.

After upgrading Coyote, all my models look like they reverted to an older list

Your old models-override.yaml is still on disk but has a version: from your previous Coyote install, so Coyote falls back to the baked-in registry, which may differ from what you remember. Re-run coyote --sync-models to regenerate the override against the new version.

Built-in models disappeared after I hand-authored an override

You probably wrote only your custom model into models-override.yaml. The override replaces the entire registry rather than extending it. See Hand-Authoring for the correct workflow.

Start Here

Using Coyote

Model Providers

Tools & Function Calling

Agents

Knowledge & Automation

Configuration