Factory Droid

A customModels entry in ~/.factory/settings.json — model, baseUrl and provider — puts Droid on any endpoint that speaks Anthropic Messages or OpenAI Chat Completions.

// ~/.factory/settings.json  (Windows: %USERPROFILE%\.factory\settings.json)
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "Sonnet 5 [Kunavo]",
      "baseUrl": "https://api.kunavo.com",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "anthropic"
    },
    {
      "model": "gpt-5-6-sol",
      "displayName": "GPT-5.6 Sol [Kunavo]",
      "baseUrl": "https://api.kunavo.com/v1",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "generic-chat-completion-api"
    }
  ]
}

// Then, in the shell Droid starts from:
//   export KUNAVO_API_KEY=sk-kn-...
// ${VAR_NAME} expansion is a settings.json feature. It does NOT apply to the
// legacy ~/.factory/config.json, which Factory still loads and merges.

Step by step

1. Create a key at /app/keys and copy it — it is shown once. Export it as KUNAVO_API_KEY in the shell you start Droid from, so the key itself never lands in a settings file.
2. Open ~/.factory/settings.json (create it if it is not there) and add the customModels array above. Factory marks exactly three fields required — model, baseUrl and provider — and displayName is the label the picker shows you.
3. Check the provider spelling. It must be exactly one of anthropic, openai or generic-chat-completion-api; Factory's troubleshooting section lists a typo there as the cause of its "Invalid provider" error.
4. Run /model in the CLI. Your entries appear in a separate Custom models section below Factory's own, labelled with the displayName you set. Factory watches the settings file, so a save is enough — no restart.
5. Give it a task that reads and edits a file rather than a greeting. Droid leans on tool calling for nearly everything it does, and that is the part a plain chat turn will not exercise. Then run /cost, which is where Factory reports cache hit rates — Kunavo serves Anthropic's cache_control markers natively, and Factory's own note is that on the generic Chat Completions provider caching “varies by provider and cannot be guaranteed”.

Checked against Factory's Custom Models (BYOK) page on September 21, 2026. Third-party settings move; if a field name here no longer matches what you see, that page is the authority, not this one.

Verify before you debug the client

One request settles whether a failure is the endpoint, the key, or the configuration file. If this returns JSON, the same base URL and key work in Factory Droid.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Which model id to put in the field

Every text model is reachable as a model id — the live list is GET /v1/models, and the catalog with prices is on the models page. Rates are USD per 1M tokens, input / output.

What a custom model in Droid does not reach

Three limits come from Factory's own pages, and each one changes what you should expect from the config above rather than whether it works.

• Local surfaces only. Factory's BYOK page states that custom models are available in the Droid CLI and the desktop app, which read your local settings.json, and that they “don't appear in Factory's hosted web or mobile platforms”. Work delegated through the hosted product keeps running on Factory-billed inference whatever key you configured here.
• An administrator can switch it off. Factory's enterprise controls document modelPolicy.allowCustomModels and allowedBaseUrls, which disable user BYOK outright or pin every custom model to one approved host. On a managed machine, check that before you debug the file.
• The plan fee survives. A key here is additive rather than a replacement — what Factory charges past its BYOK allowance, and what that allowance is, is the subject of the cost guide and is not re-derived on this page.

One trap worth knowing before you copy a config from anywhere else: Factory still loads the legacy ~/.factory/config.json with snake_case custom_models and base_url, merging it under settings.json, and it documents that ${VAR_NAME} expansion does not apply there. A key written as a placeholder in that file is sent literally. Use settings.json.