# How to Add Custom Model Providers in PI-Desktop Settings: Complete Configuration Guide

> Easily add custom model providers in PI-Desktop. Follow our complete guide to configure Base URL, API Key, and more via ProviderSetupDialog for your AI models.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**You can add custom AI model providers in PI-Desktop by navigating to Settings → Providers, selecting the "Custom Service" option, and configuring the Base URL, API Key, and model discovery parameters through the `ProviderSetupDialog` component.**

PI-Desktop, maintained by vastsa, is an open-source desktop application that unifies multiple AI providers into a single chat interface. While the application ships with pre-configured vendors like OpenAI and Anthropic, you can extend it with **custom model providers** through a flexible configuration system defined in [`packages/shared/src/types/providers.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/types/providers.ts).

## Accessing the Provider Configuration Interface

To begin adding a custom provider, open the settings menu from the main application window. Click the gear icon and navigate to **Settings** → **Providers** to view the provider management interface.

Click the **Add Provider** button to launch the `ProviderSetupDialog` component ([`apps/desktop/src/components/settings/ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ProviderSetupDialog.tsx)). This dialog handles both named service configurations and custom endpoint setups through a unified React interface.

## Configuring a Custom Service Endpoint

### Select the Custom Service Type

In the service selection phase, the `ServicePicker` component ([`apps/desktop/src/components/settings/ServicePicker.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ServicePicker.tsx)) presents available options. Choose the **Custom** entry (`CUSTOM_SERVICE`) from the dropdown. When `service === CUSTOM_SERVICE`, the dialog switches to custom-service mode and renders specific input fields for external endpoints (lines 39-55 of [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx)).

### Enter Provider Credentials

The custom provider form requires four critical fields:

- **Name**: A user-friendly label for identifying the provider in the UI.
- **Base URL**: The root API endpoint (e.g., `https://api.myservice.com/v1`). The dialog validates this through `normalizeBaseUrlInput` (lines 78-94), which strips path suffixes to ensure proper endpoint construction.
- **API Key**: The authentication token entered via a secure password field.
- **API Style**: The protocol variant supported by the endpoint. The dropdown populates from `API_STYLES` filtering out internal-only styles like OpenCode-Go.

### Configure Advanced HTTP Headers (Optional)

For endpoints requiring custom HTTP headers, click **Advanced Settings** to open the header editor overlay. The `ProviderHeadersEditor` component ([`apps/desktop/src/components/settings/ProviderHeadersEditor.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ProviderHeadersEditor.tsx)) allows you to define non-secret header key-value pairs that accompany each request. This is essential for services requiring specific `User-Agent` strings or custom authentication schemes beyond standard API keys.

## Model Discovery and Selection

Once you provide a valid Base URL and API Key, the `useProviderModels` hook initiates automatic discovery (lines 82-86). This hook probes the endpoint's `/models` path (derived from `endpointPathSuffixes` in the provider runtime) to fetch the available model catalog.

The discovered models render in the `ModelSelectionPanes` component ([`apps/desktop/src/components/settings/ModelSelectionPanes.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ModelSelectionPanes.tsx)). Select one or more models to expose through PI-Desktop. The first selected model's ID becomes the `defaultModelId` stored in the provider configuration according to the `ProviderPublic` type definition.

## Saving and Persisting the Provider

The **Save** button enables only when all required fields pass validation through the `canSave` check (lines 22-28). Clicking save invokes either `api.createProvider` for new entries or `api.updateProvider` for existing modifications.

The persistence layer stores data according to the `ProviderPublic` interface in [`packages/shared/src/types/providers.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/types/providers.ts), capturing `vendorKey`, `baseUrl`, `authKind`, and an array of `ModelBinding` objects (defined in [`packages/shared/src/types/models.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/types/models.ts)) representing the selected models. After successful persistence, the dialog closes and the custom provider appears immediately in the Providers list.

## Implementation Code Reference

The following patterns demonstrate how the custom provider flow is implemented in the TypeScript/React codebase:

```tsx
// 1️⃣ Open the dialog from Settings → Providers
<Button onClick={() => setShowProviderDialog(true)}>
  {t('settings.addProviderTitle')}
</Button>

// 2️⃣ ProviderSetupDialog handles custom service configuration
<ProviderSetupDialog
  onClose={() => setShowProviderDialog(false)}
  onSaved={(provider, models) => {
    // provider is now persisted; models are the selected bindings
    refreshProviders();
  }}
/>

// 3️⃣ ServicePicker selects the custom option
<ServicePicker
  value={service}
  onChange={(next) => setService(next)} // picks CUSTOM_SERVICE for custom
/>

// 4️⃣ Advanced headers editor for custom HTTP requirements
<ProviderHeadersEditor
  pairs={headerPairs}
  onChange={setHeaderPairs}
/>

```

## Summary

- **PI-Desktop** supports custom AI providers alongside pre-configured services through the settings interface located at **Settings** → **Providers**.
- The **`ProviderSetupDialog`** component manages custom endpoint configuration, rendering specific fields when `CUSTOM_SERVICE` is selected from the `ServicePicker`.
- **Model discovery** occurs automatically via the `useProviderModels` hook once valid Base URL and API Key credentials are provided.
- **Advanced configuration** allows custom HTTP headers through `ProviderHeadersEditor` for endpoints requiring specialized authentication or routing headers.
- Provider data persists according to the **`ProviderPublic`** type system in [`packages/shared/src/types/providers.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/types/providers.ts), ensuring type safety across the application.

## Frequently Asked Questions

### Can I use any OpenAI-compatible API with PI-Desktop?

Yes. PI-Desktop's custom provider system accepts any endpoint implementing standard OpenAI-style chat completion protocols. When configuring the provider, select the appropriate **API Style** (such as `chat_completions`) that matches your endpoint's interface. The application normalizes the base URL using `normalizeBaseUrlInput` and handles request formatting according to the selected style.

### Where are custom provider configurations stored?

Custom provider configurations persist to the application's provider store via `api.createProvider` or `api.updateProvider`. The data structure follows the `ProviderPublic` interface defined in [`packages/shared/src/types/providers.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/types/providers.ts), which includes `baseUrl`, `authKind`, `vendorKey`, and an array of `ModelBinding` objects representing the available models.

### How does PI-Desktop validate the custom endpoint before saving?

The application validates configurations through the `canSave` logic (lines 22-28 of [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx)), which verifies required fields are populated. Additionally, the `useProviderModels` hook performs live discovery against the endpoint's `/models` path when provided with valid credentials. This discovery request confirms endpoint accessibility and populates the model selection interface before you finalize the save operation.

### What if my custom API requires specific HTTP headers?

You can configure custom headers through the **Advanced Settings** section of the provider dialog. The `ProviderHeadersEditor` component ([`apps/desktop/src/components/settings/ProviderHeadersEditor.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ProviderHeadersEditor.tsx)) allows you to add non-secret header key-value pairs that PI-Desktop includes with every request to that endpoint. This supports custom authentication schemes, routing headers, or specific User-Agent requirements.