Run Factory Droid on Claude

Factory's Droid is an agentic CLI in the same family as Claude Code, and it lets you bring your own models through a config file. Pointing it at the AI Prime Tech gateway means Droid's agent loops run on Claude alongside whatever else the gateway serves.

Edit the settings file

Droid reads ~/.factory/settings.json. Add a customModels array, where each entry describes one model you want available. This is the modern config path; the older config.json is legacy and does not support everything settings.json does.

One file covers your whole Droid setup, so a single customModels list defines every model the CLI can switch between. Keep it at the user level rather than per project.

Knowing settings.json is the current file saves real confusion, because older notes and threads still reference config.json and some features behave differently between the two. When something works in one place and not the other, settings.json is almost always the one to trust. When advice conflicts, defaulting to settings.json over config.json resolves most of it. The newer file is the one Factory actively supports, and it is where the variable syntax actually works.

Describe the model

Each customModels entry takes a model id, a baseUrl, an apiKey, a provider, and maxOutputTokens. Set model to the gateway id such as claude-sonnet-4-5, and baseUrl to the gateway host.

These fields together tell Droid exactly how to reach the model. Because Droid does not assume a single provider, you spell out each piece, which is what makes it flexible enough to target a gateway.

That explicitness is what lets one Droid install front several Claude models on the same gateway, each as its own customModels entry sharing the baseUrl and key. The CLI treats them as distinct selectable models even though they all resolve to the one endpoint upstream. One install fronting several Claude models through one endpoint is exactly what the explicit fields enable. Each entry shares the baseUrl and key while keeping its own model id, so the gateway does the routing and Droid just picks a name.

Choose the provider mode

The provider field sets the wire format. Use anthropic for the gateway's native Messages surface, openai for the Responses style, or generic-chat-completion-api for an OpenAI-style /v1 chat endpoint. For Claude on the gateway, anthropic is the natural choice.

Matching provider to the gateway's actual surface is what prevents first-run errors. With provider anthropic, Droid speaks the native format the gateway serves for Claude.

The three provider modes also map cleanly onto what a multi-model gateway can expose, so if the same gateway serves an OpenAI-style model you would add that as a separate entry with generic-chat-completion-api. Keeping each entry's provider aligned with its surface is the rule that keeps a mixed setup error-free. Aligning provider with surface on every entry is the rule that keeps a mixed gateway setup clean. A native Claude entry and an OpenAI-style one can coexist happily.

Handle the API key

Put the key in apiKey, ideally as a ${VAR} reference such as ${AIPRIME_API_KEY} so the secret stays in your environment rather than the file. Note that ${VAR} expansion works in settings.json but not in the legacy config.json.

The apiKey field also must not be empty, even for a gateway that would technically accept an anonymous request. Droid validates that the field has a value, so always provide the key or the variable that holds it.

These two facts together explain a common stumble: people put ${VAR} in the old config.json, where it is not expanded, and Droid sees a literal unresolved string. Use settings.json for the variable form, and make sure the variable is actually exported in the shell that launches Droid. Confirming the variable is exported in the launching shell is the last piece people tend to miss. Droid only sees variables present in the environment that started it.

Switch and run

Inside the Droid CLI, switch between configured models with the /model command. Add a second entry for claude-opus-4-8 and you can flip to it for harder tasks without touching the config again.

From there Droid runs its agent loop against Claude on the gateway. Because the setup lives in settings.json, the same configuration applies every time you start the CLI.

Having both a Sonnet and an Opus entry ready means you can match the model to the task on the fly — Sonnet for steady implementation, Opus when a problem needs harder reasoning — all through the gateway with no reconfiguration. The /model switch makes that a one-line change mid-session. A one-line /model switch mid-session is what makes matching model to task feel effortless. You move from Sonnet to Opus without leaving the session.

// ~/.factory/settings.json
{
  "customModels": [
    {
      "model": "claude-sonnet-4-5",
      "baseUrl": "https://aiprimetech.io",
      "apiKey": "${AIPRIME_API_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    }
  ]
}
// export AIPRIME_API_KEY=<key>   (apiKey must NOT be empty)
// Switch models in the CLI with /model

Frequently asked questions

How do I run Factory Droid on Claude?
Add a customModels entry in ~/.factory/settings.json with provider anthropic, baseUrl {SITE}, your model id, and the apiKey. Switch with /model.

Which provider value for Claude?
anthropic for the native Messages surface. openai or generic-chat-completion-api target OpenAI-style endpoints instead.

Can apiKey be empty?
No — Droid requires a value. Use a ${VAR} reference like ${AIPRIME_API_KEY}; expansion works in settings.json, not legacy config.json.

How do I switch models?
Use the /model command in the Droid CLI to flip between any entries in your customModels list.

AI Prime Tech is an independent API gateway. It is not affiliated with, endorsed by, or a reseller of Anthropic. Claude and related model names are trademarks of their respective owners.