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

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.

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). 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) 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).

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) 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). 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, capturing vendorKey, baseUrl, authKind, and an array of ModelBinding objects (defined in 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:

// 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, 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, 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), 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}