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
.envor 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:chatgptfor chatgpt.compersist:claudefor claude.aipersist:geminifor gemini.google.compersist:perplexityfor perplexity.ai
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.
src/mcp/index.js, ipc-bridge.js)
electron/main-v2.cjs): picks the provider view or the BYOK router
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_PORTsets 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 (exceptping) 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.
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.
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;
}
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.