Factory Droid

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 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).

{
  "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:

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. 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.

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