# Goose

> Add Deference to Goose as a custom OpenAI-compatible provider.

Goose loads custom providers from a JSON file. The `openai` engine 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` in the shell that starts Goose.
2. Create `deference.json` in the custom providers folder: `~/.config/goose/custom_providers/` on macOS and Linux, and `%APPDATA%\Block\goose\config\custom_providers\` on Windows.

```json
{
  "name": "deference",
  "engine": "openai",
  "display_name": "Deference",
  "api_key_env": "DEFERENCE_API_KEY",
  "base_url": "https://deference.si/v1",
  "supports_streaming": true,
  "dynamic_models": true,
  "models": [
    {
      "name": "anthropic/claude-sonnet-5.5",
      "context_limit": 200000,
      "max_tokens": 32000
    }
  ]
}
```

3. Select the provider and model.

**macOS and Linux**

```bash
export GOOSE_PROVIDER=deference
export GOOSE_MODEL=anthropic/claude-sonnet-5.5
goose session
```

**Windows**

```powershell
$env:GOOSE_PROVIDER = "deference"
$env:GOOSE_MODEL = "anthropic/claude-sonnet-5.5"
goose session
```

In Goose Desktop, open **Settings**, then **Models**, then **Configure providers**, and choose **Add Custom Provider**. It takes the same fields. Desktop keeps the key in your system keychain.

`name` can use lowercase letters, digits, `_` and `-`. Keep the key out of `config.yaml`: Goose ignores a key stored there.

## Verify

1. Run `goose info -v`. It shows the config locations and active settings.
2. Run a one-off prompt.

**macOS and Linux**

```bash
GOOSE_PROVIDER=deference GOOSE_MODEL=anthropic/claude-sonnet-5.5 \
  goose run -t "Reply with exactly: gateway-ok"
```

**Windows**

```powershell
$env:GOOSE_PROVIDER = "deference"
$env:GOOSE_MODEL = "anthropic/claude-sonnet-5.5"
goose run -t "Reply with exactly: gateway-ok"
```

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

## Pick a model

* With `dynamic_models` on, Goose fills its model list from `GET /v1/models`. Your `models` entries supply the context and output limits.
* Limits come from `context_limit` and `max_tokens`. `GOOSE_CONTEXT_LIMIT` and `GOOSE_MAX_TOKENS` override them for a session.
* For Messages, set `engine` to `anthropic` and `base_url` to `https://deference.si`, without `/v1`.
* `GOOSE_PROVIDER` and `GOOSE_MODEL` override the saved choice for one process. Start sessions with them, because the `--provider` flag is documented for `goose run` only.

## Troubleshooting

| You see                                  | Cause                                                                        | Fix                                                                                       |
| ---------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `missing required key DEFERENCE_API_KEY` | The variable is not set where Goose starts                                   | Export it in that shell, or store the key in Desktop                                      |
| `401 invalid_api_key`                    | The key sits in `config.yaml`, which Goose ignores                           | Use the environment variable or Desktop                                                   |
| The provider is not listed               | The file name or `name` is invalid, or the JSON is broken                    | Check `name` and the JSON syntax                                                          |
| `404 model_not_found`                    | A `models` name differs from the catalog id                                  | Copy the id from the Models page                                                          |
| `402 insufficient_credit`                | No available credit                                                          | [Add credit](https://deference.si/wallet?tab=add)                                                             |
| `402 free_credit_not_eligible`           | The account has only free credit, and this model or request does not qualify | Use an open-weight text model, set a lower `max_tokens`, or [add credit](https://deference.si/wallet?tab=add) |
| `402 key_limit_reached`                  | The key reached the credit limit set on it                                   | Raise the key's limit in API keys, or use another key                                     |