# Custom Provider



<DocImage src="features/custom-provider/add-provider-button" alt="The Provider settings with the Add custom provider button highlighted" width="1792" height="716" />

Ideavo allows you to connect model providers outside of its built-in provider list, including local models, self-hosted endpoints, and custom cloud providers, at no extra cost.

Using a Supported Provider?

Custom Providers are for local models, self-hosted endpoints, custom Base URLs, and provider configurations you control yourself. If you only want to connect a provider that Ideavo already supports with an API key or OAuth, use [BYOK](/docs/features/byok) instead.

## Add a Custom Provider [#add-a-custom-provider]

Click **Add Provider** to open the provider setup dialog. The dialog has two modes:

* **Form mode** for the guided setup experience.
* **Raw mode** for editing the provider configuration directly as JSON.

<div
  style="{
  display: &#x22;grid&#x22;,
  gridTemplateColumns: &#x22;repeat(auto-fit, minmax(180px, 1fr))&#x22;,
  gap: &#x22;1rem&#x22;,
  alignItems: &#x22;start&#x22;,
  marginTop: &#x22;1rem&#x22;,
}"
>
  <DocImage src="features/custom-provider/add-provider-form" alt="The Add custom provider form with fields for provider ID, name, package, API key, base URL and models" width="1120" height="996" />

  <DocImage src="features/custom-provider/raw-json-dialog" alt="Custom provider raw JSON dialog" width="1120" height="1132" />
</div>

### Form Mode [#form-mode]

Form mode is the recommended setup path for most users. It keeps the configuration structured and helps avoid JSON syntax mistakes.

| Field             | What to enter                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider ID**   | A unique ID for the provider. This is the technical identifier Ideavo uses internally. Use a stable, lowercase value such as `local-ollama` or `my-openai-compatible`. |
| **Name**          | A display name for the provider. This can be any name you want users to see in Ideavo, such as `Local Ollama` or `My Provider`.                                        |
| **Package**       | The SDK package that matches the provider implementation. Choose one of the supported packages listed below.                                                           |
| **API key**       | The credential used to authenticate with the provider. Some custom providers may not require one, but hosted providers usually do.                                     |
| **Base URL**      | The exact API endpoint Ideavo should send model requests to.                                                                                                           |
| **Model ID**      | The exact model identifier expected by the provider API. This must match the provider's model ID.                                                                      |
| **Model name**    | A friendly display name for the model inside Ideavo. This can be any name you want to show in the model picker.                                                        |
| **Context limit** | Optional. The model's total context window, in tokens.                                                                                                                 |
| **Output limit**  | Optional. The maximum output tokens the model can return.                                                                                                              |

<Callout type="warn">
  Make sure the **Base URL** is exact, including the protocol, hostname, port,
  and API path when required. An incorrect Base URL is one of the most common
  reasons a custom provider fails to connect.
</Callout>

### Supported Packages [#supported-packages]

Ideavo supports and tests these SDK packages by default:

| Package                     | Provider type                                                |
| --------------------------- | ------------------------------------------------------------ |
| `@ai-sdk/openai-compatible` | OpenAI-compatible APIs and many custom/self-hosted providers |
| `@ai-sdk/openai`            | OpenAI                                                       |
| `@ai-sdk/anthropic`         | Anthropic                                                    |
| `@ai-sdk/google`            | Google                                                       |
| `ollama-ai-provider`        | Ollama                                                       |

Choose the package that matches the API format exposed by your provider. For custom providers that expose an OpenAI-compatible API, `@ai-sdk/openai-compatible` is usually the right choice.

### Models [#models]

Each custom provider needs at least one model. Click **Add** in the Models section to open the model details dialog.

* **Model ID** is the provider-facing value used in API calls. It must be exact.
* **Model name** is the readable label shown in Ideavo. You can name it whatever helps your team recognize the model.
* **Limits** are optional context and output token values for the model.
* **Reasoning** should only be enabled for models that truly support reasoning or effort controls.

For example, a local Ollama model ID might be `llama3.2`, while the display name could be `Llama 3.2 Local`.

<DocImage src="features/custom-provider/model-detail" alt="Custom provider model details dialog" width="1120" height="1000" />

<Callout type="info">
  Model limits are optional, but they help Ideavo understand when a conversation
  is approaching the model's usable context window. If limits are not added, long
  conversations for that custom model may never compact automatically.
</Callout>

<Callout type="warn">
  Enable **Reasoning** only if the model and provider API support it. If enabled
  incorrectly, requests may fail or produce unexpected responses. See
  [Effort](/docs/features/effort) for how reasoning effort works.
</Callout>

### Raw Mode [#raw-mode]

Raw mode is built for power users who want full control over the provider configuration. It lets you edit the same configuration directly in JSON, including provider options and model definitions.

Use raw mode when you need to customize advanced settings that are not exposed in the form, or when you already have a provider config you want to paste in directly.

To set model limits in raw mode, add `limit.context` and `limit.output` inside the model definition.

```json
{
  "providerId": "local-ollama",
  "npm": "ollama-ai-provider",
  "name": "Local Ollama",
  "options": {
    "baseURL": "http://localhost:11434/api"
  },
  "models": {
    "llama3.2": {
      "name": "Llama 3.2 Local",
      "tools": "true",
      "limit": {
        "context": 128000,
        "output": 8192
      },
      "reasoning": false
    }
  }
}
```

<Callout type="info">
  Raw mode gives maximum flexibility, but Ideavo expects valid JSON and exact
  provider values. If you are unsure, start in form mode and switch to raw mode
  only after the basic provider details are filled in.
</Callout>

## Manage Existing Providers [#manage-existing-providers]

After you add a custom provider, it appears in the provider panel. From there, you can open the provider again, review its configuration, edit model details, or remove it completely.

### View Your Providers [#view-your-providers]

Your saved custom providers are listed in the provider panel. This is the main place to confirm which custom or self-hosted providers are currently available in your account.

<DocImage src="features/custom-provider/provider-list" alt="Custom provider panel with added providers" width="1344" height="1020" />

### Edit a Provider [#edit-a-provider]

Click an existing provider to open the edit dialog. You can update most of the configuration, including the provider name, package, API key, Base URL, model list, and model limits.

<DocImage src="features/custom-provider/edit-provider-dialog" alt="Edit custom provider dialog" width="1120" height="1040" />

This is useful when you rotate credentials, move a custom provider to a different port, rename a model, update context/output limits, or add another model exposed by the same provider.

<Callout type="warn">
  The **Provider ID** cannot be changed after the provider is created. It stays
  disabled in form mode, and editing it in raw mode will not update the saved
  provider ID.
</Callout>

### Delete a Provider [#delete-a-provider]

Use **Delete** when you no longer want Ideavo to use that provider. Deleting a provider removes it from your custom provider list and also removes its models from the model selector.

If you only need to change credentials, Base URL, package, or model names, edit the existing provider instead of deleting and recreating it.

## Use a Local Model [#use-a-local-model]

Every custom provider needs at least one model before it can be used for building in Ideavo. Once a provider and model are saved, the model appears in the model selector under that provider's name.

<DocImage src="features/custom-provider/model-in-selector" alt="The model selector with the Ollama provider expanded and its custom Deepseek V4 Pro model selected" width="508" height="556" />

### Select the Model [#select-the-model]

Open the model selector, expand your custom provider, and choose the model you added. Ideavo will then route future model requests through your provider using the selected model ID.

The label shown in the selector comes from the **Model name** field, while the actual request uses the **Model ID** configured for that model.

<Callout type="info">
  If your model does not appear in the selector, confirm that the provider was
  saved successfully and that at least one model is configured for it.
</Callout>

## FAQ [#faq]

<Accordions>
  <Accordion title="Are there any extra costs or Ideavo credit deductions?">
    No. Ideavo does not charge extra for using custom providers, and custom model
    usage does not deduct Ideavo credits. For hosted custom providers, any usage
    cost is billed directly by the provider you connect.
  </Accordion>

  <Accordion title="Can I use a custom provider like Ollama?">
    Yes. Custom Providers are designed for local and self-hosted providers as
    well as hosted APIs. Choose the matching package, enter the local Base URL,
    and add the model IDs exposed by your custom provider.
  </Accordion>

  <Accordion title="Why is my custom provider failing to connect?">
    The most common cause is an incorrect Base URL. Make sure the URL includes
    the correct protocol, host, port, and API path required by your provider. If
    the provider requires authentication, also confirm that the API key is valid.
  </Accordion>

  <Accordion title="Can I change the Provider ID later?">
    No. The Provider ID is locked after the provider is created because Ideavo
    uses it as the stable identifier for that provider. You can update the name,
    package, Base URL, API key, and models, but not the Provider ID.
  </Accordion>

  <Accordion title="Why is my model not showing in the model selector?">
    Confirm that the provider was saved successfully and that it has at least one
    model configured. The model selector shows the model name, but requests are
    routed using the model ID, so the model ID must match what your provider
    expects.
  </Accordion>

  <Accordion title="Do I need to set model context and output limits?">
    No. Context and output limits are optional. However, adding them helps Ideavo
    understand the model's usable context window and compact long conversations
    before they exceed it. If you leave limits empty, long conversations for that
    custom model may never compact automatically.
  </Accordion>

  <Accordion title="How is this different from BYOK?">
    BYOK is best for connecting supported providers with their standard API key
    or OAuth flow. Custom Providers give you more control: you can set the Base
    URL, choose the SDK package, define your own models, and use local,
    self-hosted, or other providers that are not available in the default list.
  </Accordion>
</Accordions>
