# How to Configure PI Desktop Connection Settings: A Complete Guide

> Learn how to configure PI Desktop connection settings with this complete guide. Easily manage MCP servers, AI providers, and network proxies for secure and immediate activation.

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

---

**PI Desktop stores all external service configurations—including MCP servers, AI providers, and network proxies—in a centralized Settings interface that persists encrypted credentials to a local JSON store and immediately activates them in the Electron runtime.**

All connection management in the `vastsa/PI-Desktop` repository is handled through a React-based settings UI that communicates with the Electron main process. Whether you need to route traffic through a corporate proxy or authenticate with OpenAI, understanding how PI Desktop connection settings are structured will help you secure and troubleshoot your integrations.

## Architecture of PI Desktop Connection Settings

The configuration system is organized into three distinct layers: the React frontend components, the shared settings abstraction, and the Electron runtime consumers.

- **UI Layer** – The [`SettingsPage.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/SettingsPage.tsx) component hosts a tabbed layout for editing connections, while specialized dialogs like [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx) and [`NetworkProxySection.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/NetworkProxySection.tsx) collect provider-specific fields.
- **Persistence Layer** – The [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) module in `packages/shared/src/` handles JSON serialization, schema validation, and encryption for sensitive fields.
- **Runtime Layer** – The Electron main process in [`user-mcp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/user-mcp.ts) reads the persisted configuration and instantiates live client objects such as `McpControl`.

Key source files include:
- [`apps/desktop/src/pages/SettingsPage.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/pages/SettingsPage.tsx) – Orchestrates the settings UI.
- [`apps/desktop/src/components/settings/NetworkProxySection.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/NetworkProxySection.tsx) – Proxy configuration interface.
- [`apps/desktop/src/components/settings/ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/settings/ProviderSetupDialog.tsx) – AI provider setup flow.
- [`packages/shared/src/settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/settings.ts) – Centralized storage and secret handling.
- [`apps/desktop/electron/main/user-mcp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/user-mcp.ts) – Loads stored connections into the runtime.
- [`packages/shared/src/racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/racp.ts) – Defines RACP operations like `connection/ping`.

## Step-by-Step Configuration Workflow

### Opening the Settings Interface

Launch PI Desktop and click the gear icon in the sidebar, or navigate to **File → Settings**. The application renders the main settings container from [`SettingsPage.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/SettingsPage.tsx), which presents tabs for **Network Proxy**, **Providers**, and **Vendor Accounts**.

### Configuring Network Proxies

For environments requiring HTTP or SOCKS proxies, the [`NetworkProxySection.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/NetworkProxySection.tsx) component renders a form that captures URL, credentials, and TLS preferences.

```tsx
// NetworkProxySection.tsx (excerpt)
<FormField label="Proxy URL">
  <Input value={proxyUrl} onChange={e => setProxyUrl(e.target.value)} />
</FormField>
<FormField label="Username" optional>
  <Input value={username} onChange={e => setUsername(e.target.value)} />
</FormField>
<FormField label="Password" optional>
  <Input type="password" value={password} onChange={e => setPassword(e.target.value)} />
</FormField>
<Button onClick={testConnection}>Test connection</Button>

```

When you click **Test connection**, the component invokes `testProxyConnection`, which issues a `fetch` request to validate credentials against the proxy URL. A successful validation displays a green checkmark, and the configuration is persisted via `settings.set('networkProxy', {...})`.

### Adding AI Providers

To connect an AI service like OpenAI or Anthropic, open the **Providers** tab to trigger [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx). This dialog collects the provider ID, API key, and optional base URL.

```tsx
// ProviderSetupDialog.tsx (excerpt)
<FormField label="Provider">
  <Select options={providerOptions} value={provider} onChange={setProvider} />
</FormField>
<FormField label="API Key">
  <Input type="password" value={apiKey} onChange={e => setApiKey(e.target.value)} />
</FormField>
<FormField label="Base URL" optional>
  <Input value={baseUrl} onChange={e => setBaseUrl(e.target.value)} />
</FormField>
<Button onClick={testProvider}>Test connection</Button>

```

The `testProvider` function sends a `connection/initialize` request defined in [`racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/racp.ts) to verify the token. Valid providers appear immediately in the **Model Selection** UI for use by sub-agents.

### Testing and Persistence

Every connection editor includes a test mechanism that leverages the RACP schema. The `connection/ping` operation validates network reachability before committing changes. Once validated, settings are written to the user data directory at `~/.pi-desktop/settings.json`.

## How Connection Data Is Stored and Secured

The [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) module abstracts all disk I/O and applies schema validation to prevent malformed configurations. Fields marked with `secret: true` are encrypted at rest.

A typical persisted entry looks like this:

```json
{
  "networkProxy": {
    "url": "http://proxy.company.com:8080",
    "username": "alice",
    "password": "<encrypted>"
  },
  "providers": [
    {
      "id": "openai",
      "apiKey": "<encrypted>",
      "baseUrl": "https://api.openai.com"
    }
  ]
}

```

The module ensures that sensitive tokens never appear as plaintext in memory dumps and that the JSON structure remains compatible with the `McpControlConnectionInfo` type used by the runtime.

## Runtime Activation in the Electron Main Process

When PI Desktop launches, the Electron main process executes [`user-mcp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/user-mcp.ts) to bootstrap the connection layer. This script reads the JSON configuration from [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) and constructs `McpControl` instances for each active connection.

The [`mcp-control.ts`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.ts) file defines the `McpControlConnectionInfo` interface and manages the WebSocket handshake for MCP servers. Each instance exposes methods like `ping()` for health checks and `close()` for graceful shutdowns. This architecture ensures that UI changes to PI Desktop connection settings propagate immediately to the live runtime without requiring an application restart.

## Summary

- **PI Desktop connection settings** are centralized in a React-based Settings UI accessible via the gear icon or File menu.
- **Network proxies** and **AI providers** are configured through dedicated components in [`NetworkProxySection.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/NetworkProxySection.tsx) and [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx).
- All configurations are validated via RACP operations (`connection/ping`, `connection/initialize`) before persistence.
- **Sensitive data** is encrypted by the [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) module and stored in `~/.pi-desktop/settings.json`.
- The **Electron main process** loads these settings via [`user-mcp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/user-mcp.ts) and instantiates live `McpControl` objects for immediate use.

## Frequently Asked Questions

### Where does PI Desktop store connection credentials?

PI Desktop stores connection credentials in a local JSON file located at `~/.pi-desktop/settings.json`. The [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) module encrypts any field marked as a secret, ensuring API keys and passwords are never stored as plaintext.

### How do I test if my proxy configuration is working?

Click the **Test connection** button in the **Network Proxy** section of the Settings page. This triggers the `testProxyConnection` function, which performs an HTTP request through the specified proxy. A green checkmark indicates successful authentication and connectivity.

### Can I configure multiple AI providers simultaneously?

Yes. The [`ProviderSetupDialog.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/ProviderSetupDialog.tsx) component supports adding multiple providers to the `providers` array in the settings store. Each provider entry requires a unique ID, API key, and optional base URL, and all configured providers appear in the Model Selection dropdown.

### Do I need to restart PI Desktop after changing connection settings?

No. Changes to PI Desktop connection settings take effect immediately. The [`user-mcp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/user-mcp.ts) runtime reads the updated configuration from [`settings.ts`](https://github.com/vastsa/PI-Desktop/blob/main/settings.ts) and reconfigures the live `McpControl` instances without requiring an application restart.