From 861fe6820bdf80fe13079543b1da6f19b84192b8 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 10 Dec 2025 07:42:55 -0800 Subject: [PATCH 1/4] configure custom providers --- .../docs/getting-started/providers.md | 291 +++++++++++++++++- 1 file changed, 284 insertions(+), 7 deletions(-) diff --git a/documentation/docs/getting-started/providers.md b/documentation/docs/getting-started/providers.md index 1356d0f77afb..6894c1c3e4de 100644 --- a/documentation/docs/getting-started/providers.md +++ b/documentation/docs/getting-started/providers.md @@ -42,7 +42,7 @@ goose is compatible with a wide range of LLM providers, allowing you to choose a | [Venice AI](https://venice.ai/home) | Provides access to open source models like Llama, Mistral, and Qwen while prioritizing user privacy. **Requires an account and an [API key](https://docs.venice.ai/overview/guides/generating-api-key)**. | `VENICE_API_KEY`, `VENICE_HOST` (optional), `VENICE_BASE_PATH` (optional), `VENICE_MODELS_PATH` (optional) | | [xAI](https://x.ai/) | Access to xAI's Grok models including grok-3, grok-3-mini, and grok-3-fast with 131,072 token context window. | `XAI_API_KEY`, `XAI_HOST` (optional) | -## CLI Providers +### CLI Providers goose also supports special "pass-through" providers that work with existing CLI tools, allowing you to use your subscriptions instead of paying per token: @@ -88,7 +88,7 @@ To configure your chosen provider, see available options, or select a model, vis 1. If you have a specific provider you want to use with goose, and an API key from that provider, choose `Other Providers`. - 2. Find the provider of your choice and click its `Configure` button. If you don't see your provider in the list, click `Add Custom Provider` at the bottom of the window. + 2. Find the provider of your choice and click its `Configure` button. If you don't see your provider in the list, click `Add Custom Provider` at the bottom of the window to [configure a custom provider](#configure-custom-provider). 3. Depending on your provider, you'll need to input your API Key, API Host, or other optional [parameters](#available-providers). Click the `Submit` button to authenticate and begin your first session. :::info Ollama Model Detection @@ -214,6 +214,10 @@ To configure your chosen provider, see available options, or select a model, vis This change takes effect the next time you start a session. + :::note + `goose configure` doesn't support entering custom model names. To use a model not in the provider's list, use goose Desktop or edit the `GOOSE_MODEL` variable in your [`config.yaml`](/docs/guides/config-files) directly. + ::: + :::tip Set the model for an individual session using the [`run` command](/docs/guides/goose-cli-commands#run-options): @@ -225,15 +229,15 @@ To configure your chosen provider, see available options, or select a model, vis -## Using Custom OpenAI Endpoints +### Using Custom OpenAI Endpoints -goose supports using custom OpenAI-compatible endpoints, which is particularly useful for: +When configuring the OpenAI provider, goose supports custom OpenAI-compatible endpoints, which are particularly useful for: - Self-hosted LLMs (e.g., LLaMA, Mistral) using vLLM or KServe - Private OpenAI-compatible API servers - Enterprise deployments requiring data governance and security compliance - OpenAI API proxies or gateways -### Configuration Parameters +#### Configuration Parameters | Parameter | Required | Description | |-----------|----------|-------------| @@ -243,7 +247,7 @@ goose supports using custom OpenAI-compatible endpoints, which is particularly u | `OPENAI_PROJECT` | No | Project identifier for resource management | | `OPENAI_CUSTOM_HEADERS` | No | Additional headers to include in the request. Can be set via environment variable, configuration file, or CLI, in the format `HEADER_A=VALUE_A,HEADER_B=VALUE_B`. | -### Example Configurations +#### Example Configurations @@ -281,7 +285,7 @@ goose supports using custom OpenAI-compatible endpoints, which is particularly u -### Setup Instructions +#### Setup Instructions @@ -313,6 +317,279 @@ goose supports using custom OpenAI-compatible endpoints, which is particularly u For enterprise deployments, you can pre-configure these values using environment variables or configuration files to ensure consistent governance across your organization. ::: +## Configure Custom Provider + +Configure goose to connect to corporate API gateways, third-party services, and other providers that aren't in the [available providers](#available-providers) list. The provider's API endpoints must use OpenAI, Anthropic, or Ollama compatible formats to work with goose. OpenAI compatible providers can be configured with custom headers for services that require additional authentication headers, API keys and tokens, or tenant identifiers. + +Custom providers appear in the goose providers list and can be selected like any other provider. Each custom provider maps to a JSON configuration file. + +**To add a custom provider:** + + + 1. Click the button in the top-left to open the sidebar + 2. Click the `Settings` button on the sidebar + 3. Click the `Models` tab + 4. Click `Configure providers` + 5. Click `Add Custom Provider` at the bottom of the window + 6. Fill in the provider details: + - **Provider Type**: + - `OpenAI Compatible` (most common) + - `Anthropic Compatible` + - `Ollama Compatible` + - **Display Name**: A friendly name for the provider + - **API URL**: The base URL of the API endpoint + - **API Key**: The API key, which is accessed using a custom environment variable and stored in the keychain (or `secrets.yaml` if the keyring is disabled) + - For `Ollama Compatible` providers, click `This is a local model (no auth required)` + - **Available Models**: Comma-separated list of available model names + - **Streaming Support**: Whether the API supports streaming responses (click to toggle) + 7. Click `Create Provider` + + :::info Custom Headers + Currently, custom headers for OpenAI compatible providers can't be defined in goose Desktop. As a workaround, configure the provider using goose CLI or edit the provider configuration file directly. + ::: + + + + 1. In your terminal, run the following command: + + ```sh + goose configure + ``` + + 2. Select `Custom Providers`. Use the arrow keys (↑/↓) to move through the options. + + ```sh + ┌ goose-configure + │ + ◆ What would you like to configure? + │ ○ Configure Providers + // highlight-start + │ ● Custom Providers (Add custom provider with compatible API) + // highlight-end + │ ○ Add Extension + │ ○ Toggle Extensions + │ ○ Remove Extension + │ ○ goose Settings + └ + ``` + + 3. Select `Add A Custom Provider` + + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Custom Providers + │ + ◆ What would you like to do? + // highlight-start + │ ● Add A Custom Provider (Add a new OpenAI/Anthropic/Ollama compatible Provider) + // highlight-end + │ ○ Remove Custom Provider + └ + ``` + + 4. Follow the prompts to enter the provider details: + - **API Type**: + - `OpenAI Compatible` (most common) + - `Anthropic Compatible` + - `Ollama Compatible` + - **Name**: A friendly name for the provider + - **API URL**: The base URL of the API endpoint + - **API Key**: The API key, which is accessed using a custom environment variable and stored in the keychain (or `secrets.yaml` if the keyring is disabled) + - For `Ollama Compatible` providers, press `Enter` to skip (or enter any value to be able to use the provider in goose Desktop) + - **Available Models**: Comma-separated list of available model names + - **Streaming Support**: Whether the API supports streaming responses + - **Custom Headers**: Required header names and values (`OpenAI Compatible` providers only) + + + + + First create a JSON file in the `custom_providers` directory: + - macOS/Linux: `~/.config/goose/custom_providers/` + - Windows: `%APPDATA%\Block\goose\config\custom_providers\` + + Example `custom_corp_api.json` configuration file: + ```json + { + "name": "custom_corp_api", + "engine": "openai", + "display_name": "Corporate API", + "description": "Custom Corporate API provider", + "api_key_env": "CUSTOM_CORP_API_API_KEY", + "base_url": "https://api.company.com/v1/chat/completions", + "models": [ + { + "name": "gpt-4o", + "context_limit": 128000 + }, + { + "name": "gpt-3.5-turbo", + "context_limit": 16385 + } + ], + "headers": { + "x-origin-client-id": "your-client-id", + "x-origin-secret": "your-secret" + }, + "supports_streaming": true + } + ``` + + Then use the `api_key_env` to set the key for your session. For example: + ```bash + export CUSTOM_CORP_API_API_KEY="your-api-key" + goose session start --provider custom_corp_api + ``` + + :::tip Keychain Key Storage + If you want to store the API key in the `goose` keychain, update the provider in goose Desktop and enter the key. This provides secure, persistent storage and allows goose to connect natively to the provider. + ::: + + + + +**To update a custom provider:** + + + + 1. Click the button in the top-left to open the sidebar + 2. Click the `Settings` button on the sidebar + 3. Click the `Models` tab + 4. Click `Configure providers` + 5. Click on your custom provider in the list + 6. Update the fields you want to change +
**Important:** Verify that `Provider Type` shows the correct value before saving. Otherwise, it may default to `OpenAI Compatible` regardless of the original setting. + 7. Click `Update Provider` + + + + + 1. In your terminal, run the following command: + + ```sh + goose configure + ``` + + 2. Select `Configure Providers` from the menu and press `Enter`. + + ```sh + ┌ goose-configure + │ + ◆ What would you like to configure? + // highlight-start + │ ● Configure Providers (Change provider or update credentials) + // highlight-end + │ ○ Custom Providers + │ ○ Add Extension + │ ○ Toggle Extensions + │ ○ Remove Extension + │ ○ goose Settings + └ + ``` + + 3. Select the custom provider you want to update and press `Enter`. Use the arrow keys (↑/↓) to move through the options. + + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Configure Providers + │ + ◆ Which model provider should we use? + │ ○ Amazon Bedrock + │ ○ Amazon SageMaker TGI + │ ○ Anthropic + │ ○ Azure OpenAI + │ ○ Claude Code CLI + // highlight-start + │ ● Corporate API (Custom Corporate API provider) + // highlight-end + │ ○ Cursor Agent + │ ○ ... + └ + ``` + + 4. Follow the prompts to update the fields. + + + + + Open the custom provider configuration file in the `custom_providers` directory: + - macOS/Linux: `~/.config/goose/custom_providers/` + - Windows: `%APPDATA%\Block\goose\config\custom_providers\` + + Update the fields you want to change and save your changes. + + + +Your changes are available in your next goose session. + +**To remove a custom provider:** + + + + Currently you cannot remove custom providers using goose Desktop. + + + + 1. In your terminal, run the following command: + + ```sh + goose configure + ``` + + 2. Select `Custom Providers`. Use the arrow keys (↑/↓) to move through the options. + + ```sh + ┌ goose-configure + │ + ◆ What would you like to configure? + │ ○ Configure Providers + // highlight-start + │ ● Custom Providers (Add custom provider with compatible API) + // highlight-end + │ ○ Add Extension + │ ○ Toggle Extensions + │ ○ Remove Extension + │ ○ goose Settings + └ + ``` + + 3. Select `Remove Custom Provider`. + + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Custom Providers + │ + ◆ What would you like to do? + │ ○ Add A Custom Provider + // highlight-start + │ ● Remove Custom Provider (Remove an existing custom provider) + // highlight-end + └ + ``` + + 4. Select the custom provider you want to remove. + + The provider configuration file is removed from the `custom_providers` directory and the key is removed from the keychain. + + + + + :::tip + If the provider's API key is stored in the keychain, use goose CLI to remove the custom provider. This also removes the stored API key. + ::: + + Delete the custom provider configuration file in the `custom_providers` directory: + - macOS/Linux: `~/.config/goose/custom_providers/` + - Windows: `%APPDATA%\Block\goose\config\custom_providers\` + + + + ## Using goose for Free goose is a free and open source AI agent that you can start using right away, but not all supported [LLM Providers][providers] provide a free tier. From 848352e2e9c193309e4f99cc491aa29e972d3cd5 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 10 Dec 2025 11:50:28 -0800 Subject: [PATCH 2/4] differentiate custom options --- documentation/docs/getting-started/providers.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/documentation/docs/getting-started/providers.md b/documentation/docs/getting-started/providers.md index 6894c1c3e4de..c3d2eb9ed2a9 100644 --- a/documentation/docs/getting-started/providers.md +++ b/documentation/docs/getting-started/providers.md @@ -231,12 +231,16 @@ To configure your chosen provider, see available options, or select a model, vis ### Using Custom OpenAI Endpoints -When configuring the OpenAI provider, goose supports custom OpenAI-compatible endpoints, which are particularly useful for: +The built-in OpenAI provider can connect to OpenAI's official API (`api.openai.com`) or any OpenAI-compatible endpoint, such as: - Self-hosted LLMs (e.g., LLaMA, Mistral) using vLLM or KServe - Private OpenAI-compatible API servers - Enterprise deployments requiring data governance and security compliance - OpenAI API proxies or gateways +:::tip Custom Provider Option +Need to connect to multiple OpenAI-compatible endpoints? [Configure custom providers](#configure-custom-provider) instead for easier switching and better organization, along with custom naming and shareable configurations. +::: + #### Configuration Parameters | Parameter | Required | Description | @@ -319,9 +323,16 @@ For enterprise deployments, you can pre-configure these values using environment ## Configure Custom Provider -Configure goose to connect to corporate API gateways, third-party services, and other providers that aren't in the [available providers](#available-providers) list. The provider's API endpoints must use OpenAI, Anthropic, or Ollama compatible formats to work with goose. OpenAI compatible providers can be configured with custom headers for services that require additional authentication headers, API keys and tokens, or tenant identifiers. +Custom providers let you connect to services that aren't in the [available providers](#available-providers) list. They appear in goose's provider list and can be selected like any other provider. + +**Benefits:** +- **Multiple endpoints**: Switch between different services (e.g., vLLM, corporate proxy, OpenAI) +- **Pre-configured models**: Store a list of preferred models +- **Shareable configuration**: JSON files can be shared across teams or checked into repos +- **Custom naming**: Show "Corporate API" instead of "OpenAI" in the UI +- **Separate credentials**: Assign each provider its own API key -Custom providers appear in the goose providers list and can be selected like any other provider. Each custom provider maps to a JSON configuration file. +Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats. OpenAI-compatible providers can include custom headers for additional authentication, API keys, tokens, or tenant identifiers. Each custom provider maps to a JSON configuration file. **To add a custom provider:** From b099c6a57752ade0042a986af73acdef8c2d5773 Mon Sep 17 00:00:00 2001 From: Diane Diaz Date: Wed, 10 Dec 2025 11:56:32 -0800 Subject: [PATCH 3/4] tweak --- documentation/docs/getting-started/providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/getting-started/providers.md b/documentation/docs/getting-started/providers.md index c3d2eb9ed2a9..4fed3026635e 100644 --- a/documentation/docs/getting-started/providers.md +++ b/documentation/docs/getting-started/providers.md @@ -238,7 +238,7 @@ The built-in OpenAI provider can connect to OpenAI's official API (`api.openai.c - OpenAI API proxies or gateways :::tip Custom Provider Option -Need to connect to multiple OpenAI-compatible endpoints? [Configure custom providers](#configure-custom-provider) instead for easier switching and better organization, along with custom naming and shareable configurations. +Need to connect to multiple OpenAI-compatible endpoints? [Configure custom providers](#configure-custom-provider) instead for easier switching and better organization, as well as custom naming and shareable configurations. ::: #### Configuration Parameters From 52de60615a812a3c14371675e3641fe44592d435 Mon Sep 17 00:00:00 2001 From: dianed-square <73617011+dianed-square@users.noreply.github.com> Date: Wed, 10 Dec 2025 12:14:27 -0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- documentation/docs/getting-started/providers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/getting-started/providers.md b/documentation/docs/getting-started/providers.md index 4fed3026635e..1a7be2692fcc 100644 --- a/documentation/docs/getting-started/providers.md +++ b/documentation/docs/getting-started/providers.md @@ -440,8 +440,8 @@ Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats. O } ], "headers": { - "x-origin-client-id": "your-client-id", - "x-origin-secret": "your-secret" + "x-origin-client-id": "YOUR_CLIENT_ID", + "x-origin-secret": "YOUR_SECRET_VALUE" }, "supports_streaming": true }