Dark-Alex-17/coyote
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

docs: added documentation for the model overrides and synchronization

Alex Clarke
2026-05-28 16:35:26 -06:00
parent ee6a34c3f9
commit 2bc88c2350
3 changed files with 234 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Environment-Variables.md
+18 -18
@@ -16,8 +16,8 @@ all configuration options and more thorough descriptions, refer to the [example
Below are the most commonly used configuration settings and their corresponding environment variables:
| Setting | Environment Variable |
|----------------------------|---------------------------------|
| Setting | Environment Variable |
|----------------------------|-----------------------------------|
| `model` | `COYOTE_MODEL` |
| `temperature` | `COYOTE_TEMPERATURE` |
| `top_p` | `COYOTE_TOP_P` |
@@ -48,19 +48,19 @@ Below are the most commonly used configuration settings and their corresponding
# Client Related Variables
The following environment variables are available for clients in Coyote:
| Environment Variable | Description |
|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `{client}_API_KEY` | For clients that require an API key, you can define the keys either through environment variables or <br>using the [vault](Vault). The variables are named after the client to which they apply; <br>e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. |
| `COYOTE_PLATFORM` | Combine with `{client}_API_KEY` to run Coyote without a configuration file. <br>This variable is ignored if a configuration file exists. |
| `COYOTE_PATCH_{client}_CHAT_COMPLETIONS` | Patch chat completion requests to models on the corresponding client; Can modify the URL, body, <br>or headers. |
| `COYOTE_SHELL` | Specify the shell that Coyote should be using when executing commands |
| Environment Variable | Description |
|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `{client}_API_KEY` | For clients that require an API key, you can define the keys either through environment variables or <br>using the [vault](Vault). The variables are named after the client to which they apply; <br>e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. |
| `COYOTE_PLATFORM` | Combine with `{client}_API_KEY` to run Coyote without a configuration file. <br>This variable is ignored if a configuration file exists. |
| `COYOTE_PATCH_{client}_CHAT_COMPLETIONS` | Patch chat completion requests to models on the corresponding client; Can modify the URL, body, <br>or headers. |
| `COYOTE_SHELL` | Specify the shell that Coyote should be using when executing commands |
# Files and Directory Related Variables
You can also customize the files and directories that Coyote loads its configuration files from:
| Environment Variable | Description | Default Value |
|----------------------|------------------------------------------------------------------------|---------------------------------|
| `COYOTE_CONFIG_DIR` | Customize the location of the Coyote configuration directory. | `<user-config-dir>/coyote` |
| Environment Variable | Description | Default Value |
|------------------------|------------------------------------------------------------------------|-----------------------------------|
| `COYOTE_CONFIG_DIR` | Customize the location of the Coyote configuration directory. | `<user-config-dir>/coyote` |
| `COYOTE_ENV_FILE` | Customize the location of the `.env` file to load at startup. | `<coyote-config-dir>/.env` |
| `COYOTE_CONFIG_FILE` | Customize the location of the global `config.yaml` configuration file. | `<coyote-config-dir>/config.yaml` |
| `COYOTE_ROLES_DIR` | Customize the location of the `roles` directory. | `<coyote-config-dir>/roles` |
@@ -86,16 +86,16 @@ You can also customize the location of full agent configurations using the follo
# Logging Related Variables
The following variables can be used to change the log level of Coyote or the location of the log file:
| Environment Variable | Description | Default Value |
|----------------------|---------------------------------------------|----------------------------------|
| `COYOTE_LOG_LEVEL` | Customize the log level of Coyote | `INFO` |
| `COYOTE_LOG_FILE` | Customize the location of the Coyote log file | `<user-cache-dir>/coyote/coyote.log` |
| Environment Variable | Description | Default Value |
|----------------------|-----------------------------------------------|--------------------------------------|
| `COYOTE_LOG_LEVEL` | Customize the log level of Coyote | `INFO` |
| `COYOTE_LOG_FILE` | Customize the location of the Coyote log file | `<user-cache-dir>/coyote/coyote.log` |
**Pro-Tip:** You can always tail the Coyote logs using the `--tail-logs` flag. If you need to disable color output, you
can also pass the `--disable-log-colors` flag as well.
# Miscellaneous Variables
| Environment Variable | Description | Default Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| `AUTO_CONFIRM` | Bypass all `guard_*` checks in the bash prompt helpers; useful for agent composition and routing | |
| Environment Variable | Description | Default Value |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| `AUTO_CONFIRM` | Bypass all `guard_*` checks in the bash prompt helpers; useful for agent composition and routing | |
| `LLM_TOOL_DATA_FILE` | Set automatically by Coyote on Windows. Points to a temporary file containing the JSON tool call data. <br>Tool scripts (`run-tool.sh`, `run-agent.sh`, etc.) read from this file instead of command-line args <br>to avoid JSON escaping issues when data passes through `cmd.exe` → bash. **Not intended to be set by users.** | |
Model-Sync.md
+213
@@ -0,0 +1,213 @@
Coyote ships with a registry of supported models baked into the binary at build time, sourced from the [`models.yaml`](https://github.com/Dark-Alex-17/coyote/blob/main/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](#hand-authoring-custom-models) below.
## Location
The file lives in your Coyote configuration directory as `models-override.yaml`. To find your config directory:
```shell
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](Environment-Variables#files-and-directory-related-variables) for the full set of path overrides.
## File Format
The file has two top-level keys, `version` and `list`:
```yaml
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`](https://github.com/Dark-Alex-17/coyote/blob/main/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](Patches#model-specific-patches) for details.
## Version Compatibility
The `version:` field must equal your installed Coyote version. Check your version with:
```shell
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](https://github.com/Dark-Alex-17/coyote/releases) 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:
```yaml
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](#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
```shell
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`:
```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](https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml) 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](Environment-Variables#global-configuration-related-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:
```yaml
# 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](#hand-authoring-custom-models) for the correct workflow.
_Sidebar.md
+3
@@ -18,6 +18,9 @@
- [API Keys](Clients#api-key-authentication)
- [OAuth](Clients#oauth-authentication)
- [Patches](Patches)
- [Model Sync](Model-Sync)
- [models-override.yaml](Model-Sync#models-overrideyaml)
- [Syncing Models](Model-Sync#syncing-models)
## Tools & Function Calling
- [Tools](Tools)