# Crush

> Add Deference to Crush as an OpenAI-compatible provider in crushrc.

Crush, from Charm, reads provider setup from a `crushrc` file: a short shell script that runs Crush's own commands. The `openai-compat` type speaks Chat Completions, so the base URL is `https://deference.si/v1`.

## Set up

1. Create a key in [API keys](https://deference.si/keys) and export it as `DEFERENCE_API_KEY`.
2. Create `crushrc` in `~/.config/crush/` (on Windows, `%USERPROFILE%\.config\crush\crushrc`). A `.crushrc` file in a project folder works too, and is safe to commit because it holds no key.

```bash
provider add deference \
  --name Deference \
  --type openai-compat \
  --base-url "https://deference.si/v1" \
  --api-key "${DEFERENCE_API_KEY:?set DEFERENCE_API_KEY}"

model add deference/anthropic/claude-sonnet-5.5 \
  --name "Claude Sonnet 5.5" \
  --context-window 200000 \
  --default-max-tokens 32000

model large deference/anthropic/claude-sonnet-5.5
model small deference/anthropic/claude-sonnet-5.5
```

3. Start Crush.

The key is read from your environment when the file runs, so it is never written down. `model large` is the model Crush uses for the main agent, and `model small` is the lighter one it uses for light tasks. Point `small` at a smaller model if you like.

Declare the models you want with `model add` so their context and output limits are explicit. Crush can also discover models for an OpenAI-compatible provider with no declared models. Add `--discover-models true` to merge discovered models with your declarations; your explicit settings take priority. See [Crush's configuration guide](https://github.com/charmbracelet/crush/blob/main/docs/config/README.md).

## Verify

1. Run `crush models`. It lists `deference/anthropic/claude-sonnet-5.5`.
2. Run a one-off prompt.

```bash
crush run -m deference/anthropic/claude-sonnet-5.5 \
  "Reply with exactly: gateway-ok"
```

3. Open [Activity](https://deference.si/activity). The request is the top row, with the model you chose.

If something fails, `crush logs --tail 50` shows the provider errors.

## Pick a model

* Crush splits `provider/model` on the first slash. In `deference/anthropic/claude-sonnet-5.5` the provider is `deference` and the model id is `anthropic/claude-sonnet-5.5`. Without the `deference/` prefix, Crush reads `anthropic` as the provider and fails with "model not found".
* Change the model in a session with Ctrl L.
* Use `--type openai-compat` for Deference. The `openai` type is for OpenAI itself.

## Troubleshooting

| You see                                   | Cause                                 | Fix                                     |
| ----------------------------------------- | ------------------------------------- | --------------------------------------- |
| `set DEFERENCE_API_KEY` when Crush starts | The variable is not set in that shell | Export it, then start Crush             |
| `401 invalid_api_key`                     | The variable holds another key        | Set it to your `sk-df-` key             |
| "model not found"                         | The `deference/` prefix is missing    | Pass the full `deference/...` name      |
| The desired model does not appear         | It was not declared or discovered     | Add a `model add` line with its full id |
| `404 model_not_found`                     | The model id differs from the catalog | Copy the id from the Models page        |