System Architecture

Proxima v5.5.0 uses a modular, multi-tier agentic architecture that translates Model Context Protocol (MCP) tool requests, coordinates local and offline endpoints, and manages your browser sessions locally and privately. Everything runs on your own machine and every listening socket is bound to 127.0.0.1.

1. System Topology & Data Flow

The platform consists of three cooperating processes: the Electron hub (desktop app and central message bus), the Node.js MCP server that your editor starts, and the optional Python agent runtime. A fourth surface, the REST and WebSocket gateway, lives inside the Electron process.

DEVELOPMENT CLIENT
Cursor · VS Code · Windsurf · Antigravity · Claude Desktop (JSON-RPC over stdio)
▼
NODE.JS MCP SERVER (src/mcp/index.js)
41 tools + 2 resources · Zod validation · model discovery · EMA smart router · optional Context7 middleware
▼ local TCP (default 127.0.0.1:19222, token-gated)
ELECTRON APP HUB (central message bus)
REST/WS gateway (default :3210) · isolated BrowserViews · BYOK router · OS keychain
▼
AI PROVIDERS
Logged-in web sessions (ChatGPT, Claude, Gemini, Perplexity) OR official APIs and local models (BYOK, Ollama, LM Studio)
▲ talks to the gateway as a client
AUTONOMOUS AGENT RUNTIME (Python, optional)
Web console :8500 · self-healing loop · Chrome DevTools (CDP) :9222 · local memory stores

The agent is a client of the gateway rather than a layer in front of it: it reads rest-port.json to find the gateway and sends its model calls through the same routes your own scripts use. That is why the agent can run entirely on free web sessions or on your own API keys without any separate configuration.

2. Life of a Request

Following one tool call from the editor to the model shows where each component sits. Take ask_claude called from Cursor in Session Mode:

1. Cursor starts "node src/mcp/index.js" and talks MCP (JSON-RPC 2.0) over stdin/stdout. 2. The MCP server validates the arguments with Zod and runs its middleware (routing hints, optional library-documentation lookup, prompt-injection screening for untrusted content). 3. ipc-bridge.js opens a TCP connection to the Electron app. It scans up to 20 ports starting at 19222 and attaches the launch token from ipc-token.json to every request. 4. The Electron main process receives the action on its central message bus (handleMCPRequest) and picks the route: a logged-in provider session, or the BYOK router. 5. In Session Mode the provider's engine script, running inside an isolated BrowserView, sends the prompt through the site's own API and streams tokens back. In BYOK Mode the request goes to the official API or local endpoint instead. 6. The reply travels back over the same TCP connection and is returned to the editor as the tool result.

Three practical consequences follow. Requests wait for a free slot per provider, so two prompts to the same provider run one after the other. The bridge treats a request as stalled after 150 seconds without any response data (AGENT_HUB_IDLE_TIMEOUT_MS changes this), so long answers that keep streaming are fine. And identical questions can be answered from a five-minute response cache until you call clear_cache.

REST and WebSocket calls enter the same message bus. The HTTP server turns each call into the same internal action the MCP bridge sends, which is why smart_query from an editor and POST /v1/chat/completions from a script behave the same way.

3. Electron Hub Layer (Main Process)

The Electron shell acts as the coordinator and system host. It manages provider sessions, stores credentials, serves the gateway, and starts the background browser views.

Session management and engines

For Session Routing, Proxima loads each provider in a separate BrowserView. Per-provider engine scripts (electron/providers/engines/) capture the response stream from the provider's own network calls, so there is no HTML scraping and no reading of the page. Since 5.0.0 a failure is reported as a failure instead of falling back to the page, and requests are serialized per provider with a bounded retry that separates transient errors from deterministic ones. The views use standard user-agent strings and preload scripts so that provider sites render and behave normally.

The REST and WebSocket gateway

The gateway is optional and switched on in Settings. It listens on 3210 by default (PROXIMA_REST_PORT changes the start). If the port is busy it tries the following ports, up to 20 attempts, and writes the port it bound, its process id and a timestamp to rest-port.json. Besides the routes in the CLI and SDK reference, it serves interactive documentation with a chat widget, including Battle Mode for comparing models side by side.

Key vault encryption

In BYOK Mode, Proxima encrypts your API keys with the operating system's keychain (Electron's SafeStorage API). Keys are not stored in plain text and are not uploaded anywhere. Keys for the Python agent's own BYOK settings are kept separately in the agent's configuration.

IPC modules

Communication between the main process, preload scripts and the renderer is split into electron/ipc/core.cjs (window state), settings.cjs (settings, cookies and the REST toggle) and cli.cjs (bridging command-line parameters to the UI).

4. Node.js MCP Middleware Pipeline

The MCP server uses the official @modelcontextprotocol/sdk. Its code is split into modules (tools-chat, tools-code, tools-search, tools-content, tools-utility, tools-workflow) that each register their tools with the same registerTool pattern, plus shared helpers and the IPC bridge. Queries pass through a few local layers before they reach a model.

EMA Smart Router

Classifies incoming queries into categories (for example code generation, research or security scanning) and routes them using capability profiles for each provider. It tracks provider latency with an Exponential Moving Average:

new_avg = (old_avg * 0.7) + (current_response_time * 0.3)

A provider that hits three consecutive errors is taken out of rotation for 60 seconds and the router falls back to the others.

Context7 documentation middleware (optional)

When you switch it on by starting Proxima with the environment variable PROXIMA_CONTEXT7=1, the middleware detects mentions of popular libraries (React, Next.js, Vue, Tailwind, FastAPI, Docker and similar) with pattern matching and fetches current documentation from mcp.context7.com, then adds it as context so answers do not rely on stale training data. Results are cached locally (ten minutes, up to 200 entries). It is off by default, and while it is off nothing is sent to Context7. When it is on, the library name and topic detected in your prompt are sent to that service.

Memory, fact harvesting and context compaction

A harvester extracts stack preferences and settings from conversations and scores them, applying a seven-day half-life so old facts fade and drop out under a quality threshold. For long conversations in BYOK and local mode, a pruner replaces bulky tool output with short summaries and a condenser summarizes the middle turns while keeping system instructions and recent turns intact.

5. Model Discovery Pipeline new in 5.5.0

Version 5.5.0 replaced hard-coded model assumptions with one shared discovery routine. The same code answers the list_available_models tool, the proxima://models MCP resource and the model lists in the gateway, so every client sees one consistent picture.

ModeHow models are found
Session ModeThe MCP server asks the Electron hub for each enabled provider's models. ChatGPT models come from the logged-in account, so they follow your plan. Gemini reports its engines (auto, flash, pro, latest, argon); if live discovery returns nothing it falls back to that built-in list. Claude and Perplexity are not discovered per account: each is listed as a single active-session entry (claude, perplexity).
BYOK ModeLists each configured provider with the model you selected for it, tagged as a BYOK/API model.

Every entry carries an id, a display name, a status, tags such as Fast, Reasoning, Pro, Session or BYOK, and an exact_usage example naming the tool and arguments to call it with. Models that support it also advertise their allowed thinking levels. Passing refresh: true skips the cache and re-queries the accounts. If a caller requests a model that is not in the list, the engine answers with an error that points to the discovery tool rather than swapping in a different model.

6. Autonomous Agent Integration Layer

The Python runtime in proxima-agent/ is a separate process that the desktop app can start for you. Its FastAPI web console listens on port 8500 and rejects any request whose Origin is not a loopback address on the expected port. The agent reaches the gateway through rest-port.json, drives Chrome over the DevTools Protocol on port 9222, and runs generated code inside a worker process with a time limit (300 seconds by default). Before launch, the desktop app now checks the Python version and the required agent modules instead of only locating an interpreter. See the Autonomous Agent Guide for the execution loop, safety gates and memory stores.

7. Ports and Local Data

PortUsed byNotes
19222MCP process to Electron hubDefault. The MCP process scans about 20 ports upward; AGENT_HUB_PORT sets the start.
3210REST and WebSocket gatewayDefault. Moves to the next free port if busy; recorded in rest-port.json.
8500Agent web consolePROXIMA_WEB_PORT and PROXIMA_WEB_HOST override it.
9222Chrome DevTools ProtocolPROXIMA_CDP_PORT overrides it.

State is kept in files on your machine:

LocationContents
App user-data folderrest-port.json, ipc-port.json, ipc-token.json, enabled-providers.json, and api-key.json if you generate a key.
~/.proxima-agent/vault.db, insights.db, memory.db, learned_fixes.json, strategies.json, config.json.
~/.proxima/skills.dbThe agent's reusable skills and their success statistics.
.proxima/index.db (inside a project)The repository index the agent builds for that project.

8. Security Model

  • Loopback only. The bridge, the gateway and the agent console all bind to 127.0.0.1.
  • Token-gated bridge. On launch the Electron process writes a random token to ipc-token.json. The MCP process attaches it to every request, so another local program cannot drive your provider sessions without reading that file.
  • Origin checks. The gateway returns HTTP 403 for browser requests whose Origin is not loopback on the gateway's own port or on an approved list (the agent console, plus anything in PROXIMA_ALLOWED_ORIGINS). Requests without an Origin header, such as curl and the SDKs, are not affected.
  • Optional API key. Generating a key in Settings (sk-…-proxima) makes the gateway require Authorization: Bearer on its non-public routes. Without a key, local callers are accepted.
  • SSRF guard. web_scrape and the agent's web fetcher resolve DNS first and reject private, loopback, link-local and metadata addresses, then pin the vetted address.
  • Prompt-injection screening of untrusted content before it enters system prompts, and a safety gate in the agent that fails closed when it runs without a console to ask you.
Token Gated Security: Communication between the Node.js process and the Electron process uses a local TCP socket. A random token is generated on launch in ipc-token.json; requests without it are refused.