From 09032e3df5e5e3f5b7ad48ba0a2246dcae50a107 Mon Sep 17 00:00:00 2001 From: Arman Bolat Date: Wed, 18 Feb 2026 20:24:13 -0800 Subject: [PATCH 1/2] docs(cli): document env-var apiKey references for custom models Closes FAC-12401 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/cli/byok/overview.mdx | 10 +++++++--- docs/cli/configuration/byok.mdx | 10 +++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/cli/byok/overview.mdx b/docs/cli/byok/overview.mdx index f372caf..9f63a3c 100644 --- a/docs/cli/byok/overview.mdx +++ b/docs/cli/byok/overview.mdx @@ -28,7 +28,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: "model": "your-model-id", "displayName": "My Custom Model", "baseUrl": "https://api.provider.com/v1", - "apiKey": "YOUR_API_KEY", + "apiKey": "${PROVIDER_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 } @@ -36,8 +36,12 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: } ``` + + In `settings.json` (and `settings.local.json`), `apiKey` supports environment variable references using `${VAR_NAME}` syntax. + + - **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. + **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. Env var expansion for `apiKey` applies to `settings.json`/`settings.local.json` and not to legacy `config.json`. ### Supported Fields @@ -47,7 +51,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: | `model` | `string` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) | | `displayName` | `string` | | Human-friendly name shown in model selector | | `baseUrl` | `string` | ✓ | API endpoint base URL | -| `apiKey` | `string` | ✓ | Your API key for the provider. Can't be empty. | +| `apiKey` | `string` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json`. | | `provider` | `string` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` | | `maxOutputTokens` | `number` | | Maximum output tokens for model responses | | `supportsImages` | `boolean` | | Whether the model supports image inputs | diff --git a/docs/cli/configuration/byok.mdx b/docs/cli/configuration/byok.mdx index bb0cadd..160c845 100644 --- a/docs/cli/configuration/byok.mdx +++ b/docs/cli/configuration/byok.mdx @@ -27,7 +27,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: "model": "your-model-id", "displayName": "My Custom Model", "baseUrl": "https://api.provider.com/v1", - "apiKey": "YOUR_API_KEY", + "apiKey": "${PROVIDER_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 } @@ -35,8 +35,12 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: } ``` + + In `settings.json` (and `settings.local.json`), `apiKey` supports environment variable references using `${VAR_NAME}` syntax. + + - **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. + **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. Env var expansion for `apiKey` applies to `settings.json`/`settings.local.json` and not to legacy `config.json`. ### Supported Fields @@ -46,7 +50,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: | `model` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) | | `displayName` | | Human-friendly name shown in model selector | | `baseUrl` | ✓ | API endpoint base URL | -| `apiKey` | ✓ | Your API key for the provider. Can't be empty. | +| `apiKey` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json`. | | `provider` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` | | `maxOutputTokens` | | Maximum output tokens for model responses | From 5f8ac3fc15c74a69ab0477cd4d6d64bcd3c7f2cd Mon Sep 17 00:00:00 2001 From: Arman Bolat Date: Wed, 18 Feb 2026 20:27:22 -0800 Subject: [PATCH 2/2] docs(cli): clarify PROVIDER_API_KEY env-var usage in BYOK examples Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/cli/byok/overview.mdx | 4 ++-- docs/cli/configuration/byok.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli/byok/overview.mdx b/docs/cli/byok/overview.mdx index 9f63a3c..ab47ad3 100644 --- a/docs/cli/byok/overview.mdx +++ b/docs/cli/byok/overview.mdx @@ -37,7 +37,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: ``` - In `settings.json` (and `settings.local.json`), `apiKey` supports environment variable references using `${VAR_NAME}` syntax. + 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`). @@ -51,7 +51,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: | `model` | `string` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) | | `displayName` | `string` | | Human-friendly name shown in model selector | | `baseUrl` | `string` | ✓ | API endpoint base URL | -| `apiKey` | `string` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json`. | +| `apiKey` | `string` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json` (e.g., `${PROVIDER_API_KEY}` uses the `PROVIDER_API_KEY` environment variable). | | `provider` | `string` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` | | `maxOutputTokens` | `number` | | Maximum output tokens for model responses | | `supportsImages` | `boolean` | | Whether the model supports image inputs | diff --git a/docs/cli/configuration/byok.mdx b/docs/cli/configuration/byok.mdx index 160c845..33d66ce 100644 --- a/docs/cli/configuration/byok.mdx +++ b/docs/cli/configuration/byok.mdx @@ -36,7 +36,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: ``` - In `settings.json` (and `settings.local.json`), `apiKey` supports environment variable references using `${VAR_NAME}` syntax. + 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`). @@ -50,7 +50,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array: | `model` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) | | `displayName` | | Human-friendly name shown in model selector | | `baseUrl` | ✓ | API endpoint base URL | -| `apiKey` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json`. | +| `apiKey` | ✓ | Your API key for the provider. Can't be empty. Supports `${VAR_NAME}` in `settings.json`/`settings.local.json` (e.g., `${PROVIDER_API_KEY}` uses the `PROVIDER_API_KEY` environment variable). | | `provider` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` | | `maxOutputTokens` | | Maximum output tokens for model responses |