Custom Models (BYOK)

The Droid CLI supports custom model configurations through BYOK (Bring Your Own Key). Use your own OpenAI or Anthropic keys, connect to any open source model providers, or run models locally on your hardware.

For Factory-managed models and multipliers, see Available Models. For org-level restrictions on custom models, base URLs, and provider access, see Enterprise Controls.

Install the CLI with the 5-minute quickstart →

Configuration reference

Add custom models to ~/.factory/settings.json under the customModels array:

{
  "customModels": [
    {
      "model": "your-model-id",
      "displayName": "My Custom Model",
      "baseUrl": "https://api.provider.com/v1",
      "apiKey": "${PROVIDER_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16384
    }
  ]
}

Supported fields

modelstringrequired

Model identifier sent via API (e.g., claude-sonnet-4-5-20250929, gpt-5.3-codex, qwen3:4b).

displayNamestring

Human-friendly name shown in model selector.

baseUrlstringrequired

API endpoint base URL.

apiKeystringrequired

Your API key for the provider. Can't be empty. Supports environment variable references; see the Tip above.

providerstringrequired

Provider type that determines API compatibility. See the Understanding Providers section below.

maxOutputTokensnumber

Maximum output tokens for model responses.

noImageSupportboolean

Set to true to disable image inputs for this model.

extraArgsobject

Additional provider-specific arguments to include in API requests.

extraHeadersobject

Additional HTTP headers to send with requests.

bedrockobject

AWS Bedrock routing options (awsRegion, awsProfile, bedrockBaseUrl, awsAuthRefresh, awsCredentialExport). See AWS Bedrock.

Using extraArgs

Pass provider-specific parameters like temperature or top_p by adding an extraArgs object:

{
  "extraArgs": {
    "temperature": 0.7,
    "top_p": 0.9
  }
}

Using extraHeaders

Add custom HTTP headers to API requests by adding an extraHeaders object:

{
  "extraHeaders": {
    "X-Custom-Header": "value",
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

AWS Bedrock

To route an Anthropic or OpenAI custom model through AWS Bedrock, add a bedrock object to the model config. Credentials are resolved through the standard AWS SDK provider chain (environment variables, shared config/credentials files, or an SSO/IAM profile).

{
  "customModels": [
    {
      "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
      "displayName": "Sonnet 4.5 [Bedrock]",
      "provider": "anthropic",
      "apiKey": "not-used-for-bedrock",
      "bedrock": {
        "awsRegion": "${AWS_REGION}",
        "awsProfile": "${AWS_PROFILE}"
      }
    }
  ]
}

Bedrock fields

Environment variable interpolation

Like apiKey, the awsRegion, awsProfile, and bedrockBaseUrl fields support ${VAR_NAME} references in settings.json/settings.local.json, expanded per workspace at parse time. This lets a single centrally-distributed customModels config resolve to the correct value in each environment:

{
  "bedrock": {
    "awsRegion": "${AWS_REGION}"
  }
}

If a referenced variable is not set, Droid fails fast with a clear error naming the missing variable instead of sending the literal ${VAR_NAME} to AWS.

Region resolution

When awsRegion is omitted, Droid resolves the region using the AWS default chain, in order:

1. 1
   AWS_REGION
2. 2
   AWS_DEFAULT_REGION
3. 3
   The region set on the resolved AWS profile in ~/.aws/config

If none of these supply a region, Droid fails fast with a clear error rather than silently defaulting, so requests never target a region the workspace did not choose (important for VPC-endpoint region affinity).

Understanding providers

Factory supports three provider types that determine API compatibility:

Provider reference

Every provider below works through the configuration above. Use provider: "generic-chat-completion-api" unless you are calling OpenAI's or Anthropic's official API.

Local models

Run models on your own hardware with an OpenAI-compatible server, then point baseUrl at it:

• Ollama: set baseUrl to http://localhost:11434/v1 with any non-empty apiKey, and raise the context window to at least 32k (for example OLLAMA_CONTEXT_LENGTH=32000 ollama serve). Models with 30B+ parameters are recommended for agentic coding, and Ollama Cloud models work through the same endpoint.
• LM Studio: set baseUrl to http://localhost:1234/v1, load an OpenAI-compatible model, and start its local server.

Prompt caching

The Droid CLI automatically uses prompt caching when available to reduce API costs:

• Official providers (anthropic, openai): Factory attempts to use prompt caching via the official APIs. Caching behavior follows each provider's implementation and requirements.
• Generic providers (generic-chat-completion-api): Prompt caching support varies by provider and cannot be guaranteed. Some providers may support caching, while others may not.

Verifying prompt caching

To check if prompt caching is working correctly with your custom model:

1. 1
   Run a conversation with your custom model
2. 2
   Use the /cost command in the Droid CLI to view cost breakdowns
3. 3
   Look for cache hit rates and savings in the output

If you're not seeing expected caching savings, consult your provider's documentation about their prompt caching support and requirements.

Using custom models

Once configured, access your custom models in the CLI:

1. 1
   Use the /model command
2. 2
   Your custom models appear in a separate "Custom models" section below Factory-provided models
3. 3
   Select any model to start using it

Custom models display with the name you set in displayName, making it easy to identify different providers and configurations.

Troubleshooting