Skip to content

Commit 7d21bfc

Browse files
factory-armanfactory-droid[bot]
factory-arman
and
factory-droid[bot]
authored
docs(cli): document env-var apiKey support for custom models (#669)
* 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): clarify PROVIDER_API_KEY env-var usage in BYOK examples Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
1 parent 22a519c commit 7d21bfc

2 files changed

Lines changed: 14 additions & 6 deletions

File tree

‎docs/cli/byok/overview.mdx‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,20 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array:
2828
"model": "your-model-id",
2929
"displayName": "My Custom Model",
3030
"baseUrl": "https://api.provider.com/v1",
31-
"apiKey": "YOUR_API_KEY",
31+
"apiKey": "${PROVIDER_API_KEY}",
3232
"provider": "generic-chat-completion-api",
3333
"maxOutputTokens": 16384
3434
}
3535
]
3636
}
3737
```
3838

39+
<Tip>
40+
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`).
41+
</Tip>
42+
3943
<Note>
40-
**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.
44+
**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`.
4145
</Note>
4246

4347
### Supported Fields
@@ -47,7 +51,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array:
4751
| `model` | `string` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) |
4852
| `displayName` | `string` | | Human-friendly name shown in model selector |
4953
| `baseUrl` | `string` | ✓ | API endpoint base URL |
50-
| `apiKey` | `string` | ✓ | Your API key for the provider. Can't be empty. |
54+
| `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). |
5155
| `provider` | `string` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` |
5256
| `maxOutputTokens` | `number` | | Maximum output tokens for model responses |
5357
| `supportsImages` | `boolean` | | Whether the model supports image inputs |

‎docs/cli/configuration/byok.mdx‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,20 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array:
2727
"model": "your-model-id",
2828
"displayName": "My Custom Model",
2929
"baseUrl": "https://api.provider.com/v1",
30-
"apiKey": "YOUR_API_KEY",
30+
"apiKey": "${PROVIDER_API_KEY}",
3131
"provider": "generic-chat-completion-api",
3232
"maxOutputTokens": 16384
3333
}
3434
]
3535
}
3636
```
3737

38+
<Tip>
39+
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`).
40+
</Tip>
41+
3842
<Note>
39-
**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.
43+
**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`.
4044
</Note>
4145

4246
### Supported Fields
@@ -46,7 +50,7 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array:
4650
| `model` | ✓ | Model identifier sent via API (e.g., `claude-sonnet-4-5-20250929`, `gpt-5-codex`, `qwen3:4b`) |
4751
| `displayName` | | Human-friendly name shown in model selector |
4852
| `baseUrl` | ✓ | API endpoint base URL |
49-
| `apiKey` | ✓ | Your API key for the provider. Can't be empty. |
53+
| `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). |
5054
| `provider` | ✓ | One of: `anthropic`, `openai`, or `generic-chat-completion-api` |
5155
| `maxOutputTokens` | | Maximum output tokens for model responses |
5256

0 commit comments

Comments
 (0)