1. The Multi-Model Routing Challenge

Modern software engineering workflows increasingly require different AI models for different programming tasks. An engineer might prefer Claude 3.5 Sonnet for complex refactoring and AST transformations, ChatGPT-4o for rapid code explanations, DeepSeek R1 for algorithmic proofs, and Perplexity for querying live framework documentation.

However, managing four independent AI models locally introduces severe security and operational challenges:

  • Cookie & State Collisions: If models run inside a shared browser environment or single cookie jar, cross-origin scripts and authentication tokens can leak between provider contexts.
  • Insecure Key Storage: Storing raw API tokens in plain-text .env or JSON configuration files leaves developer credentials vulnerable to malicious npm packages or repository leakage.
  • Latency & Interception: Passing requests through intermediate cloud relays introduces latency and violates enterprise data compliance mandates.

Proxima resolves this through a Local-First Routing Engine combining Electron partition sandboxing, OS keychain encryption, and a local loopback IPC socket.

2. Sandboxed Partition Isolation (persist:*)

In the desktop core (electron/browser-manager.cjs), each AI provider is given its own persistent Electron session through session.fromPartition(). There are four:

  • persist:chatgpt for chatgpt.com
  • persist:claude for claude.ai
  • persist:gemini for gemini.google.com
  • persist:perplexity for perplexity.ai
JavaScript // electron/browser-manager.cjs (abridged)
this.providers = {
  perplexity: { url: 'https://www.perplexity.ai/',  partition: 'persist:perplexity' },
  chatgpt:    { url: 'https://chatgpt.com/',         partition: 'persist:chatgpt' },
  claude:     { url: 'https://claude.ai/',           partition: 'persist:claude' },
  gemini:     { url: 'https://gemini.google.com/app', partition: 'persist:gemini' },
};

setupSession(provider) {
  const config = this.providers[provider];
  const ses = session.fromPartition(config.partition, { cache: true });
  // A browser-like user agent per provider so the sites render normally
  ses.setUserAgent(provider === 'claude'
    ? 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:119.0) Gecko/20100101 Firefox/119.0'
    : this.userAgent);
  ...
}

Because each partition has its own storage, cookies, localStorage, IndexedDB and cache are kept apart. A page loaded in the ChatGPT partition cannot read the cookies of the Claude partition. The persist: prefix makes the session survive restarts, which is why you only log in once. Proxima does not copy your cookies out of your everyday browser: you sign in inside these views, as you would in any browser, and you can import or export a session's cookies manually from Settings.

These views carry a standard browser identity (a Chrome user agent matching Electron's bundled Chromium, and a Firefox one for Claude) and preload scripts so that provider sites load and behave normally. The app also enforces one request at a time per provider, which keeps a long answer from being interleaved with the next prompt.

3. Loopback IPC Bridge (Default Port 19222)

The MCP server is a separate Node.js process that your editor starts and talks to over standard input and output. To reach the desktop app, which owns the provider views, it opens a TCP connection to 127.0.0.1. The default port is 19222.

IDE (Cursor, VS Code, Windsurf, Antigravity): MCP host
↓ stdin / stdout (JSON-RPC)
Proxima MCP server (src/mcp/index.js, ipc-bridge.js)
↓ TCP 127.0.0.1:19222, one JSON message per line, token on every request
Electron hub (electron/main-v2.cjs): picks the provider view or the BYOK router
Figure 2: Inter-process communication topology

Three details of the real client in src/mcp/ipc-bridge.js matter in practice:

  • Port scan: the client tries the last port that worked first, then scans about 20 ports upward from the base (AGENT_HUB_PORT sets the base). That lets two Proxima instances, or a port conflict, coexist.
  • Token: at launch the desktop app writes a random 32-byte token to ipc-token.json, and the server refuses any request (except ping) that does not carry it. The client reads the file and adds the token to every request. If the app cannot write the token file, it logs the problem and falls back to trusting any loopback connection.
  • Idle timeout: each request has an id and an inactivity timer (150 seconds by default, AGENT_HUB_IDLE_TIMEOUT_MS). The timer restarts whenever the app reports activity, so long streamed answers do not time out, but a silent stall does.
JavaScript // src/mcp/ipc-bridge.js (abridged)
async send(action, provider = null, data = {}) {
  if (!this.connected) await this.connect();       // scans ports 19222 .. 19241
  const requestId = ++this.requestId;
  const request = { requestId, action, provider, data };
  if (this.token) request.token = this.token;      // from ipc-token.json

  return new Promise((resolve, reject) => {
    // inactivity timer: IDLE_TIMEOUT_MS = AGENT_HUB_IDLE_TIMEOUT_MS || 150000
    ...
    this.socket.write(JSON.stringify(request) + '\n');   // newline-delimited JSON
  });
}

4. OS-Level Key Encryption via Electron SafeStorage

When developers choose to use API keys instead of browser sessions, credentials must be stored securely. In proxima/electron/api/byok/keys.cjs, Proxima leverages Electron’s safeStorage API to encrypt API keys before persisting them to disk (byok.json).

SafeStorage delegates cryptography to the host operating system's native credential store, so the encryption key is held by the OS rather than by Proxima:

  • Windows: Data Protection API (DPAPI) tied to user account cryptographic keys.
  • macOS: Apple Keychain with AES-128 encryption.
  • Linux: Secret Service API or GNOME Keyring / KWallet.
JavaScript // simplified from electron/api/byok/keys.cjs
const { app, safeStorage } = require('electron');
const path = require('path');

const storePath = path.join(app.getPath('userData'), 'byok.json');

// Each key is wrapped in an "envelope" before it is written to the store.
function encrypt(plain) {
  if (safeStorage && safeStorage.isEncryptionAvailable()) {
    const cipher = safeStorage.encryptString(plain);       // OS keychain / DPAPI / libsecret
    return { enc: 1, data: cipher.toString('base64') };
  }
  return { plain };                                         // fallback, see the note below
}

function decrypt(envelope) {
  if (envelope.enc === 1) {
    if (!safeStorage.isEncryptionAvailable()) return null;  // cannot read it without the OS vault
    return safeStorage.decryptString(Buffer.from(envelope.data, 'base64'));
  }
  return envelope.plain ?? null;
}
Note on the fallback: if the operating system's encryption is not available (for example a Linux desktop without a Secret Service provider), Proxima stores the key unencrypted in byok.json, protected only by the file permissions. Check that your platform provides a keyring before relying on at-rest encryption. A key that was saved encrypted cannot be read back if the OS vault later becomes unavailable.

5. The 12 BYOK Providers Pipeline

The BYOK router (electron/api/byok/router.cjs) knows twelve built-in provider IDs. Four of them have a dedicated adapter because their APIs differ (OpenAI, Anthropic, Google and Perplexity), and the other eight share one OpenAI-compatible adapter that only changes the endpoint:

Provider ID Adapter Module Target API Endpoint
chatgpt providers/openai.cjs https://api.openai.com/v1/chat/completions
claude providers/anthropic.cjs https://api.anthropic.com/v1/messages
gemini providers/google.cjs https://generativelanguage.googleapis.com/v1beta/models
perplexity providers/perplexity.cjs https://api.perplexity.ai/chat/completions
deepseek providers/openai-compatible.cjs https://api.deepseek.com/v1/chat/completions
groq providers/openai-compatible.cjs https://api.groq.com/openai/v1/chat/completions
xai providers/openai-compatible.cjs https://api.x.ai/v1/chat/completions
openrouter providers/openai-compatible.cjs https://openrouter.ai/api/v1/chat/completions
together providers/openai-compatible.cjs https://api.together.ai/v1/chat/completions
fireworks providers/openai-compatible.cjs https://api.fireworks.ai/inference/v1/chat/completions
mistral providers/openai-compatible.cjs https://api.mistral.ai/v1/chat/completions
nvidia providers/openai-compatible.cjs https://integrate.api.nvidia.com/v1/chat/completions

The same shared adapter is what lets you add any other OpenAI-compatible service, including local servers such as Ollama and LM Studio, as a custom provider by giving it an endpoint URL (http or https) and, if needed, a key.

6. Engineering Trade-offs: Web Sessions vs BYOK API Keys

Selecting between Web Session Routing and BYOK API keys depends on your team's workflow requirements:

Dimension Web Session Routing (Electron Partitions) BYOK API Keys (Direct REST)
Setup Requirement Log in once in desktop app partition Acquire API key from cloud developer console
Billing Mechanism Uses existing personal/pro user subscription Pay-per-token billed directly by provider
Rate Limit Profile Standard web tier concurrency High-throughput tier concurrency
Headless CLI Support Requires Electron background runtime Runs completely headless in terminal/CI

7. Failure Analysis & Troubleshooting

Symptom Cause Diagnosis Fix
Keys are stored without OS encryption (Linux without a keyring) No Secret Service provider (such as gnome-keyring or KWallet) is running, so Electron's SafeStorage reports encryption as unavailable and Proxima falls back to writing the key unencrypted, with owner-only file permissions. Check whether a keyring service is running and unlocked. Install libsecret and a keyring, unlock it, then re-enter the keys. Keys already saved encrypted cannot be read while the vault is unavailable.
Session expired / re-login required Provider session cookie reached natural cloud expiration interval. Open provider tab in Proxima desktop app to verify login prompt. Complete interactive authentication; session will persist in partition.
The MCP server cannot connect ("is Proxima running?") The desktop app is not running, or it started on a different port because 19222 was busy (it retries on the next ports), or the token file could not be read. Open the app. Run netstat -ano | findstr 19222 to see who holds the port. The MCP process scans about 20 ports from the base, so a nearby port is found automatically. Start Proxima before the editor, or set AGENT_HUB_PORT for both if you need a fixed port. Close stale Proxima processes if the port is held by one.

8. Architectural Takeaways

By combining Electron partition sandboxing, OS keychain encryption with SafeStorage (where the platform provides one), and a token-gated loopback IPC bridge that defaults to port 19222, Proxima routes several models through one local gateway while keeping credentials and traffic on your machine.