Bring Your Own Key (BYOK)

Configure custom models and provider API keys in Factory CLI.

Bring Your Own Key (BYOK) uses the Factory CLI customModels setting to add models that Factory does not manage for you. Configure the model ID, provider format, base URL, API key, and optional token or reasoning fields once, then choose the custom model from /model in the Factory CLI.

For Factory-managed models and usage multipliers, see Available Models.

Store real API keys in environment variables and reference them with . Do not commit API keys to project files.

Configure a custom model

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

{
  "customModels": [
    {
      "model": "provider-model-id",
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "${PROVIDER_API_KEY}",
      "provider": "generic-chat-completion-api"
    }
  ]
}

Set the environment variable in the shell where you launch Droid:

export PROVIDER_API_KEY="YOUR_API_KEY"

Then run /model and select the entry from Custom models. Settings changes usually reload automatically; if the model does not appear, restart Droid and validate the settings JSON.

Legacy ~/.factory/config.json custom model entries are still loaded for backwards compatibility. Use settings.json or settings.local.json for new BYOK configurations. Environment variable interpolation applies to settings files, not legacy config.json entries.

Provider matrix

Choose the provider value based on the API format exposed by your endpoint, not just the company name.

Endpoint	provider	Base URL	Use/notes
Anthropic API	anthropic	https://api.anthropic.com	Anthropic Messages API.
OpenAI API	openai	https://api.openai.com/v1	OpenAI Responses API.
Baseten	generic-chat-completion-api	https://inference.baseten.co/v1	Use the deployment model ID.
DeepInfra	generic-chat-completion-api	https://api.deepinfra.com/v1/openai	Repository-style model IDs are common.
Fireworks AI	generic-chat-completion-api	https://api.fireworks.ai/inference/v1	Model IDs may include an account path.
Groq	generic-chat-completion-api	https://api.groq.com/openai/v1	Use the Groq console model ID.
Hugging Face Router	generic-chat-completion-api	https://router.huggingface.co/v1	Accept required provider or model terms first.
OpenRouter	generic-chat-completion-api	https://openrouter.ai/api/v1	Add required headers with extraHeaders.
Google Gemini	generic-chat-completion-api	https://generativelanguage.googleapis.com/v1beta/openai	OpenAI-compatible Gemini endpoint; Vertex or gateway URLs can also apply.
Local/self-hosted servers	generic-chat-completion-api	http://localhost:11434/v1 or https://example.com/v1	Ollama, vLLM, or self-hosted /v1 servers. Start the server first.

Custom model quality, latency, image support, prompt caching, and reasoning support depend on the provider and model you choose. Validate the model on your repository before relying on it for production engineering work.

Supported fields

Required fields

Field	Description
model	Model identifier sent to the provider.
baseUrl	Provider API base URL.
apiKey	API key string or ${VAR_NAME} environment variable reference.
provider	API format: anthropic, openai, or generic-chat-completion-api.

Optional fields

Field	Description
displayName	Human-readable label shown in the model selector. Defaults to model.
id	Stable custom model ID. Droid generates one when omitted.
index	Numeric ordering/index for the custom model. Droid assigns one when omitted.
maxOutputTokens	Maximum output tokens to request from the provider.
enableThinking	Enables provider thinking/reasoning configuration when supported by the selected API format.
thinkingMaxTokens	Maximum thinking tokens when thinking is enabled.
reasoningEffort	Reasoning effort hint such as low, medium, or high when supported.
extraHeaders	Additional HTTP headers sent with each request.
extraArgs	Additional provider-specific request arguments.
noImageSupport	Set to true to disable image inputs. For non-OpenAI and non-Anthropic formats, Droid defaults this to true when omitted; set it to false only after verifying image support.

Troubleshooting

Problem	Check
Model does not appear	Confirm customModels is valid JSON and includes model, baseUrl, apiKey, and provider.
Invalid provider	Use exactly anthropic, openai, or generic-chat-completion-api.
Authentication fails	Verify the environment variable is set in the shell where you launched Droid and that the provider account has available quota.
Requests fail immediately	Confirm the baseUrl matches the API format selected by provider.
Local model fails	Start the local server, confirm the model is pulled, and test the /v1 endpoint from the same machine.
Optional fields fail	Remove unsupported enableThinking, thinkingMaxTokens, reasoningEffort, extraHeaders, or extraArgs, then add them back only when the provider documents support.
Images fail	Set noImageSupport to true unless you have verified image input support for that endpoint.