diff --git a/Environment-Variables.md b/Environment-Variables.md index 086d96f..2674bd0 100644 --- a/Environment-Variables.md +++ b/Environment-Variables.md @@ -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
using the [vault](Vault). The variables are named after the client to which they apply;
e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. | -| `COYOTE_PLATFORM` | Combine with `{client}_API_KEY` to run Coyote without a configuration file.
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,
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
using the [vault](Vault). The variables are named after the client to which they apply;
e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. | +| `COYOTE_PLATFORM` | Combine with `{client}_API_KEY` to run Coyote without a configuration file.
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,
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. | `/coyote` | +| Environment Variable | Description | Default Value | +|------------------------|------------------------------------------------------------------------|-----------------------------------| +| `COYOTE_CONFIG_DIR` | Customize the location of the Coyote configuration directory. | `/coyote` | | `COYOTE_ENV_FILE` | Customize the location of the `.env` file to load at startup. | `/.env` | | `COYOTE_CONFIG_FILE` | Customize the location of the global `config.yaml` configuration file. | `/config.yaml` | | `COYOTE_ROLES_DIR` | Customize the location of the `roles` directory. | `/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 | `/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 | `/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.
Tool scripts (`run-tool.sh`, `run-agent.sh`, etc.) read from this file instead of command-line args
to avoid JSON escaping issues when data passes through `cmd.exe` → bash. **Not intended to be set by users.** | | diff --git a/Model-Sync.md b/Model-Sync.md new file mode 100644 index 0000000..8e9efb5 --- /dev/null +++ b/Model-Sync.md @@ -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 `/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: "" # 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//.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 `. + +## 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 `/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 | grep `. +- 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. diff --git a/_Sidebar.md b/_Sidebar.md index 98d984c..e83fea6 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -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)