How to Configure PI Desktop Connection Settings: A Complete Guide

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 component hosts a tabbed layout for editing connections, while specialized dialogs like ProviderSetupDialog.tsx and NetworkProxySection.tsx collect provider-specific fields.
• Persistence Layer – The 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 reads the persisted configuration and instantiates live client objects such as McpControl.

Key source files include:

• apps/desktop/src/pages/SettingsPage.tsx – Orchestrates the settings UI.
• apps/desktop/src/components/settings/NetworkProxySection.tsx – Proxy configuration interface.
• apps/desktop/src/components/settings/ProviderSetupDialog.tsx – AI provider setup flow.
• packages/shared/src/settings.ts – Centralized storage and secret handling.
• apps/desktop/electron/main/user-mcp.ts – Loads stored connections into the runtime.
• 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, which presents tabs for Network Proxy, Providers, and Vendor Accounts.

Configuring Network Proxies

For environments requiring HTTP or SOCKS proxies, the NetworkProxySection.tsx component renders a form that captures URL, credentials, and TLS preferences.

// 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. This dialog collects the provider ID, API key, and optional base URL.

// 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 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 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:

{
  "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 to bootstrap the connection layer. This script reads the JSON configuration from settings.ts and constructs McpControl instances for each active connection.

The 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 and ProviderSetupDialog.tsx.
• All configurations are validated via RACP operations (connection/ping, connection/initialize) before persistence.
• Sensitive data is encrypted by the settings.ts module and stored in ~/.pi-desktop/settings.json.
• The Electron main process loads these settings via 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 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 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 runtime reads the updated configuration from settings.ts and reconfigures the live McpControl instances without requiring an application restart.

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