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 →

Add a custom model

• CLI: run /settings and open Custom models, or run /model and select Manage custom models. Choose Add model, pick a provider, fill in the fields, and select Save changes.
• Desktop app: open Settings > Custom Models and click Add Model. Fill in the Form view, or switch to JSON to edit the model object directly.
• Settings file: add an entry to customModels in ~/.factory/settings.json, as described below.

Both editors save to ~/.factory/settings.json and list only your personal models, not organization or project models. Saved models appear under Custom Models in /model, labeled with their displayName.

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.

baseUrlstring

API endpoint base URL. Required unless the model has a bedrock block.

apiKeystring

Your API key for the provider. Optional: omit it for a keyless endpoint, or use apiKeyHelper instead. If set, it can't be empty. Supports environment variable references; see the Tip above.

apiKeyHelperstring

Shell command whose stdout is used as the API key, resolved at request time and refreshed on a TTL and after a 401. Takes precedence over apiKey. Honored in user and org-managed settings, but not in project or folder settings; see Dynamic credentials.

apiKeyHelperTtlMsnumber

Refresh interval for apiKeyHelper output, in milliseconds. Defaults to 5 minutes; the FACTORY_API_KEY_HELPER_TTL_MS environment variable overrides it.

authMode"provider-default" | "bearer"

Credential transport for HTTP Anthropic models. Omit it or use provider-default to send the credential as x-api-key. Use bearer to send it as Authorization: Bearer. Bearer mode requires provider: "anthropic" and isn't supported for Bedrock models.

providerstringrequired

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

maxOutputTokensnumber

Maximum output tokens for model responses.

maxContextLimitnumber

The model's context window, in input tokens. Droid compacts the conversation to stay within it and won't send a message too large to fit. A larger value doesn't make Droid compact later, though: compaction still starts at your compaction token limit, 250,000 by default, as it does for built-in models with large windows. To compact later, raise Default compaction token limit or choose Add model compaction override in /settings, or set compactionTokenLimit or compactionTokenLimitPerModel in ~/.factory/settings.json. Keep that limit below maxContextLimit so the response still fits. If your provider's window counts output tokens too, set maxContextLimit to the window minus maxOutputTokens. If you omit maxContextLimit and Droid doesn't know the model's window, it assumes 250,000 tokens or your compaction token limit, whichever is higher.

reasoningEffortstring

Default reasoning effort for a model Droid doesn't recognize. Setting it also offers off, low, medium, and high in the model selector. When model or baseModelId matches a built-in model, that model's levels and default apply instead.

enableThinkingboolean

For anthropic and bedrock-converse models, set to true to turn on extended thinking.

thinkingMaxTokensnumber

Token budget for extended thinking on anthropic and bedrock-converse models.

baseModelIdstring

ID of the built-in model this entry serves (see Available Models), for example when your provider uses its own name for it. Droid applies that model's reasoning levels.

useInRouterboolean

Set to true to let Auto Model use this model in place of the built-in model named by baseModelId. Requires your organization to allow BYOK in Auto Model (modelPolicy.allowFactoryRouterByok).

noImageSupportboolean

Set to true to disable image inputs for this model. Defaults to false for anthropic, openai, and bedrock-converse models and true for generic-chat-completion-api models.

extraArgsobject

Additional provider-specific arguments to include in API requests.

extraHeadersobject

Additional HTTP headers to send with requests.

bedrockobject

AWS Bedrock routing options (authMethod, awsRegion, awsProfile, bedrockBaseUrl, awsAuthRefresh, awsCredentialExport, requestMetadata). 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"
  }
}

Dynamic credentials with apiKeyHelper

Some gateways issue short-lived tokens (for example, an internal LLM gateway fronted by an identity provider) rather than a long-lived static key. Instead of a static apiKey, point the model at an apiKeyHelper command whose standard output is the token. Droid runs it at request time, caches the result, and refreshes it automatically.

{
  "customModels": [
    {
      "model": "your-model",
      "displayName": "Gateway Model",
      "baseUrl": "https://llm-gateway.internal.example.com/v1",
      "provider": "generic-chat-completion-api",
      "apiKeyHelper": "/usr/local/bin/mint-gateway-token.sh",
      "apiKeyHelperTtlMs": 300000
    }
  ]
}

Behavior:

• The command's trimmed stdout is used as the credential (sent as the provider-appropriate auth header). apiKeyHelper takes precedence over any static apiKey.
• The command runs from your home directory, so use an absolute path or one relative to your home directory.
• The token is cached and re-minted when it expires. TTL resolution order: the FACTORY_API_KEY_HELPER_TTL_MS environment variable, then the per-model apiKeyHelperTtlMs, then a 5-minute default.
• The token is also refreshed once after a 401 response. If the command fails, it enters a short cooldown and fails fast rather than retrying on every request.
• The token, command output, and command text are never logged.

This mirrors Claude Code's apiKeyHelper (the FACTORY_API_KEY_HELPER_TTL_MS variable is the analog of CLAUDE_CODE_API_KEY_HELPER_TTL_MS).

Anthropic bearer authentication

By default, provider: "anthropic" sends the credential from apiKey or apiKeyHelper in the x-api-key header. Some Anthropic Messages-compatible gateways require Authorization: Bearer instead. Set authMode to bearer for those gateways:

{
  "customModels": [
    {
      "model": "claude-compatible-model",
      "displayName": "Claude-compatible gateway",
      "baseUrl": "https://llm-gateway.internal.example.com/anthropic",
      "provider": "anthropic",
      "apiKeyHelper": "/usr/local/bin/mint-gateway-token.sh",
      "authMode": "bearer"
    }
  ]
}

authMode: "bearer" is only valid for non-Bedrock models using provider: "anthropic".

AWS Bedrock

To route a custom model through AWS Bedrock, add a bedrock object and set provider to match the Bedrock API: anthropic for InvokeModel on Bedrock Runtime or Messages on Bedrock Mantle, bedrock-converse for Converse, or openai for Bedrock's OpenAI-compatible endpoint. Bedrock models don't use apiKey or baseUrl.

{
  "customModels": [
    {
      "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
      "displayName": "Sonnet 4.5 [Bedrock]",
      "provider": "anthropic",
      "bedrock": {
        "authMethod": "aws-credentials",
        "awsRegion": "us-west-2",
        "awsProfile": "my-aws-profile"
      }
    }
  ]
}

authMethod selects where Droid gets credentials:

The awsCredentialExport command must print JSON with a top-level Credentials object containing AccessKeyId, SecretAccessKey, and, for temporary credentials, SessionToken. Shell export lines are rejected. If you omit authMethod, Droid tries AWS_BEARER_TOKEN_BEDROCK, then the AWS credential chain, then awsCredentialExport, then awsAuthRefresh.

Bedrock fields

Request metadata

requestMetadata is a map of string keys to string values that Droid sends on every Bedrock inference call for that model. AWS surfaces the tags in model-invocation logs and cost allocation, which is how you attribute Bedrock spend in your own AWS account back to Droid, a team, or a cost center:

{
  "customModels": [
    {
      "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
      "displayName": "Sonnet 4.5 [Bedrock]",
      "provider": "anthropic",
      "bedrock": {
        "awsRegion": "us-west-2",
        "requestMetadata": {
          "tool": "droid",
          "team": "platform-eng",
          "cost_center": "${COST_CENTER}"
        }
      }
    }
  ]
}

Bedrock carries this parameter differently on each of its wire formats, so what Droid sends depends on the model's provider:

AWS constrains the tags, and exceeding a limit fails every call on that model:

• At most 16 entries.
• Keys are 1-256 characters; values are at most 256 characters.
• Keys and values may contain only alphanumerics, whitespace, and : _ @ $ # = / + , . -.

Droid checks these limits per model, at request time, on the two APIs that actually send the tags. A violation fails only that model with a message naming the offending key, rather than invalidating your whole settings file. If the block itself cannot be represented at all (not an object of string values, or two keys that collapse onto the same name after ${VAR_NAME} expansion), Droid logs a warning naming the key, drops requestMetadata for that model, and keeps the rest of your settings.

Environment variable interpolation

Like apiKey, the awsRegion, awsProfile, bedrockBaseUrl, and requestMetadata fields support ${VAR_NAME} references in settings.json/settings.local.json, expanded per workspace. 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. In requestMetadata, keys are expanded alongside values, and an unresolved reference is only reported on the APIs that send the tags, so it never fails a model whose dialect ignores them.

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 four 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 (no apiKey needed, though some builds want any placeholder value), 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.

Troubleshooting