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.
Cursor · VS Code · Windsurf · Antigravity · Claude Desktop (JSON-RPC over stdio)
src/mcp/index.js)41 tools + 2 resources · Zod validation · model discovery · EMA smart router · optional Context7 middleware
REST/WS gateway (default :3210) · isolated BrowserViews · BYOK router · OS keychain
Logged-in web sessions (ChatGPT, Claude, Gemini, Perplexity) OR official APIs and local models (BYOK, Ollama, LM Studio)
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:
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:
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.
| Mode | How models are found |
|---|---|
| Session Mode | The 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 Mode | Lists 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
| Port | Used by | Notes |
|---|---|---|
19222 | MCP process to Electron hub | Default. The MCP process scans about 20 ports upward; AGENT_HUB_PORT sets the start. |
3210 | REST and WebSocket gateway | Default. Moves to the next free port if busy; recorded in rest-port.json. |
8500 | Agent web console | PROXIMA_WEB_PORT and PROXIMA_WEB_HOST override it. |
9222 | Chrome DevTools Protocol | PROXIMA_CDP_PORT overrides it. |
State is kept in files on your machine:
| Location | Contents |
|---|---|
| App user-data folder | rest-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.db | The 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
Originis not loopback on the gateway's own port or on an approved list (the agent console, plus anything inPROXIMA_ALLOWED_ORIGINS). Requests without anOriginheader, such as curl and the SDKs, are not affected. - Optional API key. Generating a key in Settings (
sk-…-proxima) makes the gateway requireAuthorization: Beareron its non-public routes. Without a key, local callers are accepted. - SSRF guard.
web_scrapeand 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.
ipc-token.json; requests without it are refused.