# Custom Models (BYOK)

Connect your own API keys, use open source models, or run local models

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](/models).
For org-level restrictions on custom models, base URLs, and provider access, see [Enterprise Controls](/enterprise/hierarchical-settings-and-org-control).

<Note>
  Your API keys remain local and are not uploaded to Factory servers. Custom models are only available in the CLI and won't appear in Factory's web or mobile platforms.
</Note>

[Install the CLI with the 5-minute quickstart →](/droid-cli/quickstart)

---

## Configuration reference

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

```json
{
  "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
    }
  ]
}
```

<Tip>
  In `settings.json` (and `settings.local.json`), `apiKey` supports environment variable references using `${VAR_NAME}` syntax. For example, `"apiKey": "${PROVIDER_API_KEY}"` reads from the environment variable named `PROVIDER_API_KEY` (for example: `export PROVIDER_API_KEY=your_key_here`).
</Tip>

<Note>
  **Legacy support**: Custom models in `~/.factory/config.json` using snake_case field names (`custom_models`, `base_url`, etc.) are still supported for backwards compatibility. Both files are loaded and merged, with `settings.json` taking priority. Environment variable expansion for `apiKey` does not apply to legacy `config.json`.
</Note>

### Supported fields

<PropertyList>
  <Property name='model' type='string' required>
    Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`,
    `gpt-5.3-codex`, `qwen3:4b`).
  </Property>
  <Property name='displayName' type='string'>
    Human-friendly name shown in model selector.
  </Property>
  <Property name='baseUrl' type='string' required>
    API endpoint base URL.
  </Property>
  <Property name='apiKey' type='string' required>
    Your API key for the provider. Can't be empty. Supports environment
    variable references; see the Tip above.
  </Property>
  <Property name='provider' type='string' required>
    Provider type that determines API compatibility. See the Understanding
    Providers section below.
  </Property>
  <Property name='maxOutputTokens' type='number'>
    Maximum output tokens for model responses.
  </Property>
  <Property name='noImageSupport' type='boolean'>
    Set to `true` to disable image inputs for this model.
  </Property>
  <Property name='extraArgs' type='object'>
    Additional provider-specific arguments to include in API requests.
  </Property>
  <Property name='extraHeaders' type='object'>
    Additional HTTP headers to send with requests.
  </Property>
  <Property name='bedrock' type='object'>
    AWS Bedrock routing options (`awsRegion`, `awsProfile`, `bedrockBaseUrl`,
    `awsAuthRefresh`, `awsCredentialExport`). See [AWS Bedrock](#aws-bedrock).
  </Property>
</PropertyList>

### Using extraArgs

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

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

### Using extraHeaders

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

```json
{
  "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).

```json
{
  "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

| Field | Type | Description |
|-------|------|-------------|
| `awsRegion` | `string` | AWS region for Bedrock requests. Optional; when omitted, Droid falls back to the AWS default region chain. Supports `${VAR_NAME}` interpolation. |
| `awsProfile` | `string` | AWS profile name to resolve credentials and (as a last resort) a region. Supports `${VAR_NAME}` interpolation. |
| `bedrockBaseUrl` | `string` | Explicit Bedrock endpoint override. Accepts a full URL or a `${VAR_NAME}` reference that expands to one. |
| `awsAuthRefresh` | `string` | Shell command run to refresh AWS credentials before requests. |
| `awsCredentialExport` | `string` | Shell command whose output exports AWS credentials into the request environment. |

### 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:

```json
{
  "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.

<Note>
  `awsAuthRefresh` and `awsCredentialExport` are **not** expanded by the settings parser. They run through a shell, so `${VAR}` in those commands is substituted by the shell at run time against the child process environment.
</Note>

### Region resolution

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

1. `AWS_REGION`
2. `AWS_DEFAULT_REGION`
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).

<LabeledDivider label='Choosing a provider' />

## Understanding providers

Factory supports three provider types that determine API compatibility:

| Provider | API Format | Use For | Documentation |
|----------|------------|---------|---------------|
| `anthropic` | Anthropic Messages API (v1/messages) | Anthropic models on their official API or compatible proxies | [Anthropic Messages API](https://docs.claude.com/en/api/messages) |
| `openai` | OpenAI Responses API | OpenAI models on their official API or compatible proxies. Required for the newest models like GPT-5 and GPT-5-Codex. | [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) |
| `generic-chat-completion-api` | OpenAI Chat Completions API | OpenRouter, Fireworks, Together AI, Ollama, vLLM, and most open-source providers | [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) |

<Warning>
  Factory is actively verifying Droid's performance on popular models, but we cannot guarantee that all custom models will work out of the box. Only Anthropic and OpenAI models accessed via their official APIs are fully tested and benchmarked.
</Warning>

<Note>
  **Model Size Consideration**: Models below 30 billion parameters have shown significantly lower performance on agentic coding tasks. While these smaller models can be useful for experimentation and learning, they are generally not recommended for production coding work or complex software engineering tasks.
</Note>

---

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

| Provider | `baseUrl` | Example `model` |
| --- | --- | --- |
| OpenAI (official) | `https://api.openai.com/v1` | `gpt-5.3-codex` (set `provider: "openai"`) |
| Anthropic (official) | `https://api.anthropic.com` | `claude-sonnet-4-5-20250929` (set `provider: "anthropic"`) |
| OpenRouter | `https://openrouter.ai/api/v1` | `openai/gpt-oss-20b` |
| Fireworks AI | `https://api.fireworks.ai/inference/v1` | `accounts/fireworks/models/deepseek-v3p1-terminus` |
| DeepInfra | `https://api.deepinfra.com/v1/openai` | `Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo` |
| Groq | `https://api.groq.com/openai/v1` | `moonshotai/kimi-k2-instruct-0905` |
| Baseten | `https://inference.baseten.co/v1` | your deployed model ID |
| Hugging Face | `https://router.huggingface.co/v1` | `openai/gpt-oss-120b:fireworks-ai` |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/` | `gemini-2.5-pro` |

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

<LabeledDivider label='After setup' />

## 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. Run a conversation with your custom model
2. Use the `/cost` command in the Droid CLI to view cost breakdowns
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. Use the `/model` command
2. Your custom models appear in a separate "Custom models" section below Factory-provided models
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

<Troubleshooting>
  <TroubleshootingItem title="Model not appearing in selector">
    - Check JSON syntax in `~/.factory/settings.json` (or `config.json` if using legacy format)
    - Settings changes are detected automatically via file watching
    - Verify all required fields are present
  </TroubleshootingItem>

  <TroubleshootingItem title='"Invalid provider" error'>
    - Provider must be exactly `anthropic`, `openai`, or `generic-chat-completion-api`
    - Check for typos and ensure proper capitalization
  </TroubleshootingItem>

  <TroubleshootingItem title="Authentication errors">
    - Verify your API key is valid and has available credits
    - Check that the API key has proper permissions
    - Confirm the base URL matches your provider's documentation
  </TroubleshootingItem>

  <TroubleshootingItem title="Local model does not connect">
    - Ensure your local server is running (e.g., `ollama serve`)
    - Verify the base URL is correct and includes `/v1/` suffix if required
    - Check that the model is pulled/available locally
  </TroubleshootingItem>

  <TroubleshootingItem title="Rate limiting or quota errors">
    - Check your provider's rate limits and usage quotas
    - Monitor your usage through your provider's dashboard
  </TroubleshootingItem>
</Troubleshooting>

<RelatedLinks>
  <RelatedLink href='/models' title='Available Models'>
    Browse Factory-managed models and multipliers.
  </RelatedLink>
  <RelatedLink href='/enterprise/hierarchical-settings-and-org-control' title='Enterprise Controls & Managed Settings'>
    Restrict custom models, base URLs, and provider access at the org level.
  </RelatedLink>
</RelatedLinks>