# Factory Droid

> Add Deference to Factory Droid as a custom model in settings.json.

Droid, Factory's coding agent, loads custom models from `~/.factory/settings.json`. Custom models work in the Droid CLI and desktop app. This guide uses Chat Completions with `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 Droid.
2. Add the model to `~/.factory/settings.json` (on Windows, `%USERPROFILE%\.factory\settings.json`).

```json
{
  "customModels": [
    {
      "model": "anthropic/claude-sonnet-5.5",
      "displayName": "Deference Claude Sonnet 5.5",
      "baseUrl": "https://deference.si/v1",
      "apiKey": "${DEFERENCE_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 64000
    }
  ]
}
```

Droid watches the file, so you do not need to restart it. `${DEFERENCE_API_KEY}` is read from the environment, so the file is safe to commit.

`provider` picks the API format:

| `provider`                    | Format           | `baseUrl`                             |
| ----------------------------- | ---------------- | ------------------------------------- |
| `generic-chat-completion-api` | Chat Completions | `https://deference.si/v1`             |
| `openai`                      | Responses        | `https://deference.si/v1`             |
| `anthropic`                   | Messages         | `https://deference.si`, without `/v1` |

## Verify

1. Run `droid`, then `/model`. The model is listed under **Custom models**, by its `displayName`.
2. Select it and send a short prompt.
3. Run `/cost` to see the session's cost.
4. Open [Activity](https://deference.si/activity). The request is the top row, with the model you chose.

If the model is missing, run `/diagnostics` to see settings errors.

To run it without the interface, pass the custom model id to `droid exec`. The id is `custom:`, then the display name with spaces replaced by dashes, then a dash and the model's position in `customModels`, starting at 0.

```bash
droid exec --model "custom:Deference-Claude-Sonnet-5.5-0" \
  "Reply with exactly: gateway-ok"
```

## Pick a model

* `model` is sent as written, slashes included.
* Factory tests only Anthropic and OpenAI models through their own APIs. Other models may not work out of the box, and Factory discourages models under 30B parameters for agent work.
* `maxOutputTokens` is the only size setting. Add `"noImageSupport": true` for models that cannot read images.
* Reordering `customModels` changes the ids used by `droid exec`.

## Troubleshooting

| You see                                                                            | Cause                                               | Fix                                                        |
| ---------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------- |
| The model is not in `/model`                                                       | The JSON is invalid, or a required field is missing | Check the syntax, then run `/diagnostics`                  |
| "Invalid provider"                                                                 | `provider` is not one of the three values           | Use `generic-chat-completion-api`, `openai` or `anthropic` |
| `401 missing_api_key`, or `401 authentication_error` with the `anthropic` provider | `DEFERENCE_API_KEY` is not set where Droid starts   | Export it in that shell and start Droid again              |
| `404` on every call                                                                | `baseUrl` has the wrong `/v1` for the `provider`    | Use the table above                                        |
| `404 model_not_found`                                                              | `model` differs from the catalog id                 | Copy the id from the Models page                           |
| Custom models are blocked                                                          | Your organization's policy forbids them             | Ask the admin to allow custom models and this base URL     |