Proxima Documentation

Proxima is an open-source, local-first developer platform combining a Multi-AI Model Context Protocol (MCP) server with a closed-loop Autonomous Python Coding Agent. It enables developers to route frontier AI models (ChatGPT, Claude, Gemini, Perplexity) and offline local models (Ollama, LM Studio) directly into modern IDEs (Cursor, VS Code, Windsurf, Antigravity) with zero cloud relay proxies.

Current release: v5.5.0. Highlights: live model discovery (list_available_models), thinking-depth controls, request cancellation, automatic port discovery, and Battle Mode in the chat widget. Upgrading from 5.0.0? Read What's new in 5.5.0.
Pillar 01 // Protocol Bridge

Model Context Protocol (MCP) →

Standardized JSON-RPC 2.0 stdio server exposing 41 tools and 2 resources: live model discovery, web search, code review, multi-model consensus and debate, and session routing, directly in your IDE.

Pillar 02 // Autonomous Runtime

Autonomous Coding Agent →

Python background engine daemon running at localhost:8500 featuring closed-loop AST error self-healing, Chrome DevTools (CDP) automation, and 4 SQLite memory vaults.

Routing Modes

Proxima supports three primary execution engines designed to balance cost, privacy, and reasoning power:

Mode Cost Providers Technical Architecture & Reference
1. Session Routing (Default) 100% Free ChatGPT, Claude, Gemini, Perplexity Automates free browser logins inside isolated Chromium partitions (BrowserViews). Intercepts internal WebSocket/REST streams. Zero API keys or subscriptions required. Read the Session Routing Guide →
2. BYOK (Bring Your Own Key) Official API Pricing OpenAI, Claude, DeepSeek (V3/R1), Groq, xAI, OpenRouter, Mistral, NVIDIA NIM Direct official APIs. All API keys encrypted locally using OS native keychain via Electron SafeStorage. Automatic context compaction and token tracking.
3. Local Offline Hardware Free & Offline Ollama, LM Studio, vLLM, LocalAI Runs open-weight models (Llama 3, DeepSeek-Coder, Qwen 2.5) entirely on local GPU/CPU. Prompts stay on your machine when you use a local model (web tools and update checks still need the internet). Read the Local Models Guide →

Installation

Requirements

  • Node.js 18+ (for core Electron Hub, MCP stdio server, and CLI)
  • Python 3.10+ (required for the Autonomous Agent engine & SQLite memory vaults)
  • Windows 10 / 11 — pre-built standalone installer available
  • macOS & Linux — supported via source build and Electron

Option 1: Windows Installer (Recommended)

Download the latest signed release binary from GitHub. This automatically initializes the Node server, desktop tray app, and virtual environment for the Python Agent.

Download for Windows ↗ GitHub Repository ↗

Option 2: Run from Source

Clone the official repository from GitHub (Zen4-bit/Proxima) and install dependencies:

# Clone repository from GitHub git clone https://github.com/Zen4-bit/Proxima.git cd Proxima # Install Node dependencies and launch Proxima Electron Hub npm install npm start # Setup Python Autonomous Agent runtime cd proxima-agent python -m venv venv # Windows: venv\Scripts\activate # macOS / Linux: source venv/bin/activate # Install agent dependencies & launch pip install -r requirements.txt python main.py

Configuration

1. MCP Server Configuration (IDEs)

Add this to your AI coding app's MCP configuration (Cursor, VS Code, Claude Desktop, Antigravity, etc.):

{ "mcpServers": { "proxima": { "command": "node", "args": ["C:/path/to/proxima/src/mcp/index.js"] } } }

Tip: You can copy the exact pre-filled configuration JSON directly from the "Settings" tab inside the Proxima desktop application.

2. Ports & Local Files

Proxima uses the following local loopback interfaces. All of them bind to 127.0.0.1 only:

Service / PortProtocolDescription
127.0.0.1:19222Local TCP (IPC)Bridge between the MCP process (src/mcp/index.js) and the desktop app. This is the default; if it is taken, the MCP process scans a small range of nearby ports, and AGENT_HUB_PORT overrides it.
http://localhost:3210HTTP / WebSocketOptional REST and WebSocket gateway (enable it in Settings). Default port; if busy, Proxima tries the next ports and records the bound port in rest-port.json. PROXIMA_REST_PORT changes the starting port.
http://localhost:8500HTTP / RESTAutonomous Agent Web Dashboard, live state observer, and task dispatcher.
ws://127.0.0.1:9222WebSocketChrome DevTools Protocol (CDP) remote debugging port for automated browser sessions.
~/.proxima-agent/SQLite 3Directory containing the 4 local memory databases (vault.db, insights.db, memory.db, skills.db).

Chat & Models (9 tools)

Talk to individual providers or let Proxima route for you. Model names are discovered at runtime from your logged-in accounts and BYOK configuration, so the list below never goes out of date.

Tool NameDescription
list_available_modelsLists the models that are live on your account right now, with availability status, capability tags (Fast, Reasoning, Pro) and how to call each one. Pass refresh: true to bypass the cache.
ask_chatgptQuery ChatGPT. Accepts auto or any model slug returned by list_available_models.
ask_claudeQuery Claude (strong at coding and reasoning).
ask_geminiQuery Gemini. Supports sub-engines (argon, flash, pro) and an optional thinking_level: default, low, medium, high.
ask_perplexityQuery Perplexity (web search with citations).
ask_modelUniversal chat: send to any enabled session provider or configured BYOK provider. Supports thinking_level.
ask_all_aisSend the same message to several providers in parallel and get every answer side by side.
smart_queryBest general entry point. Modes: auto (fast single AI), verify (primary plus a cross-model check), consensus (all vote), collaborate (role-based teamwork).
new_conversationReset conversation memory for one provider, or for all enabled providers if none is named.

MCP Resources

Besides tools, the server exposes two read-only resources that clients can fetch without calling a tool:

Resource URIContent
proxima://modelsThe same live model list as list_available_models, as JSON.
proxima://statusServer name, version, loaded modules, enabled providers, and whether the bridge to the desktop app is connected.
Asking for a model that is not available? Since v5.5.0 Proxima does not silently substitute another model. It returns an error that points you to list_available_models, so you can pick a slug that your account actually has. See What's new in 5.5.0.

Code Tools (12 tools)

Generate, review, fix, convert and test code.

Tool NameDescription
generate_codeWrite new code from a description, with comments, error handling and usage examples.
explain_codeExplain a snippet line by line.
review_codeReview a snippet for bugs, security, performance and best practices.
optimize_codeImprove code for speed, memory or readability and show before/after.
verify_codeQuick best-practices check of a snippet for a stated purpose.
solveEnd-to-end solution for a coding task, feature or bug. The broadest code tool.
fix_errorDiagnose an error or stack trace: root cause, fix, prevention, full code.
explain_errorExplain an error in plain language with likely causes and step-by-step fixes.
convert_codeTranslate code between languages or frameworks, preserving behavior.
write_testsGenerate a complete test file for a given file path: happy path, edge cases, errors.
build_architectureDesign a system architecture: stack, schema, APIs, deployment.
security_auditDeep audit for injection, auth, secrets, crypto, config and dependencies, with severity and fixes.

Search & Web (4 tools)

Find and read information from the web.

Tool NameDescription
deep_searchAI research with typed prompts: web, reddit, github, news, math, academic, factcheck, stats.
ddg_searchFree DuckDuckGo search returning ranked title, URL and snippet. No provider or key needed. Detects rate limits and bot challenges.
web_scrapeFetch one URL and convert it to clean Markdown. Guarded against SSRF.
get_ui_referenceUI/UX design reference: colors, typography, layout, components, accessibility.

Content & Verification (4 tools)

Write, compare, debate and cross-check.

Tool NameDescription
contentGeneral text tool with modes: summarize, write, brainstorm, howto, analyze, extract, improve.
compareCompare two items, options or technologies side by side, optionally for a given context.
debateProviders argue different stances on a topic, then conclude. Needs two or more enabled providers for a true multi-AI debate.
verifyAsk one or more providers to answer a claim with a confidence rating and caveats, to cross-check an answer.

Agentic & Workflow (5 tools) v5.0.0

Multi-agent collaboration, structured workflows, and diagnostics.

Tool NameDescription
crewRole-based pipeline (default Researcher, Writer, Reviewer), each role on its own provider, passing output down the chain.
run_workflowOrdered multi-step pipeline where each step's output feeds the next, with automatic provider routing per step.
run_loopIterate one task: generate, have another AI review, improve, until it converges or reaches maxTurns.
proxima_agentic_statusRead-only status of the agentic pipeline: mode (session or BYOK), router and provider health, memory, run-loop, cost.
proxima_cost_reportRead-only report of this session's token usage and estimated savings per provider.

Files & Utility (7 tools)

Codebase analysis and window and cache controls.

Tool NameDescription
analyze_fileAnalyze a file or whole directory: codebase packing, smart slicing, symbol extraction, grep and secret scan.
review_code_fileReview a single code file on disk, optionally focused on bugs, performance, security or style.
clear_cacheClear the in-memory response cache so the next identical question is asked fresh.
show_windowShow the Proxima window.
hide_windowHide the window. The app and MCP keep running in the background.
toggle_windowToggle the window between visible and hidden.
set_headless_modeEnable or disable headless mode (runs without a visible window; MCP keeps working).

Autonomous Agent Engine v5.0.0

Proxima includes a built-in Autonomous Python Agent runtime designed for closed-loop software debugging, automated test verification, and Chrome DevTools Protocol (CDP) browser automation.

Autonomous Agent Web UI: When Proxima is initialized, the agent daemon runs locally at http://localhost:8500 with live task execution monitoring, workspace inspection, and execution safety controls.
http://127.0.0.1:8500 — Proxima Agent Dashboard
Proxima Agent Interface

1. Execution Safety Modes

The agent supports 3 safety permission tiers depending on your workflow:

  • Auto: Full autonomous execution for rapid scripting, code refactoring, and test suite execution.
  • Smart (Default): Reads files and runs non-destructive commands automatically; prompts for confirmation if a system command risk score exceeds safety thresholds.
  • Suggest: Strictly displays proposed code changes as unified git diffs, waiting for manual developer approval before applying.

2. The 4 Local SQLite Memory Vaults

All persistent state, experience memory, and learned patterns are stored locally in SQLite databases inside ~/.proxima-agent/:

Database VaultFunction & Stored Data
vault.dbFull conversation histories, session lineages, and branch trees.
insights.dbWorkspace facts, technology stack preferences, and environment parameters.
memory.dbCompiler error signatures paired with verified code diff solutions.
skills.dbProcedural automation runner scripts ranked by Bayesian execution success.

3. Browser Automation via Chrome DevTools Protocol (CDP)

The agent connects directly to Chromium instances over WebSocket port 9222, enabling direct accessibility tree inspection, DOM coordinate bounding boxes, full-page screenshot verification, and synthetic keyboard/mouse interaction without heavy testing drivers.

For in-depth technical architecture, AST parsing details, and repair cycle breakdowns, explore the dedicated Autonomous Agent Guide →.

CLI Tool updated in v5.5.0

The proxima CLI lets you use any AI provider from your terminal. It talks to the local REST gateway, so the Proxima desktop app must be running and the REST API enabled.

Install

From the app: Settings → ⚡ Install CLI to PATH
From source: npm link (Windows) or sudo npm link (macOS/Linux)

Commands

proxima ask "How does async/await work?" proxima ask claude "Review this approach" proxima ask gemini "Compare these designs" --thinking high proxima compare "Bun vs Node.js" proxima search "latest Node.js release" proxima code review "def fib(n): ..." --lang python # generate | review | explain | debug proxima fix "SyntaxError: Unexpected token" proxima debate "tabs vs spaces" proxima audit "SELECT * FROM users WHERE id=" proxima translate "Hello world" --to Hindi proxima analyze "https://example.com" -q "what is this?" proxima brainstorm "dev productivity features" proxima models # live models and status proxima status # gateway health and bound port proxima stats # latency metrics proxima new claude # reset one provider's conversation

Flags and environment

OptionMeaning
--model, -mOverride the provider or a specific engine.
--thinking <level>Thinking depth: default, low, medium, high. New in 5.5.0.
--file <path>Add a local file as context. Text files are appended to the prompt; images and PDFs are uploaded natively.
--lang, -lTarget language for code generation.
--to / --fromTarget and source language for translate.
--jsonPrint the raw JSON response, for scripting.
PROXIMA_HOST, PROXIMA_PORT / PROXIMA_REST_PORTOverride the gateway host and port. Without them the CLI reads rest-port.json to find the port the gateway actually bound, then falls back to 3210.

Pipe Support

npm run build 2>&1 | proxima fix git diff | proxima code review proxima ask "What does this do?" --file src/server.js

REST API updated in v5.5.0

OpenAI-compatible REST API at http://localhost:3210 by default. Enable it in Settings → REST API & CLI. If port 3210 is busy, Proxima moves to the next free port (up to 20 attempts) and writes the port it actually bound to rest-port.json in its user data folder. The official CLI and SDKs read that file automatically. Set PROXIMA_REST_PORT to start from a different port, or call GET /api/status to confirm which port is live.

Endpoints

POST /v1/chat/completions — OpenAI-compatible chat (stream, tools, thinking controls) POST /v1/cancel — Cancel in-flight generation and flush the provider queue GET /v1/models — Live, dynamically discovered models (session and BYOK) GET /v1/functions — API function catalog GET /v1/stats — Response time stats POST /v1/conversations/new — Reset conversations GET /api/status — Server status, bound port and providers GET /docs — Interactive API docs with chat widget and Battle Mode

Example

curl http://localhost:3210/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "gemini", "message": "Analyze this trade-off", "thinking_level": "high"}'

Choosing the model

The model field accepts auto, a provider name (claude, chatgpt, gemini, perplexity), a sub-engine such as gemini:pro or gemini:flash, any slug listed by GET /v1/models, all, or an array like ["claude", "chatgpt"].

Thinking depth

Send thinking_level (default, low, medium, high) or the OpenAI-style reasoning_effort. If both are present with conflicting values, or a value is unsupported, the API answers with HTTP 400 instead of guessing.

Cancelling a request

curl -X POST http://localhost:3210/v1/cancel \ -H "Content-Type: application/json" \ -d '{"provider": "gemini"}'

The provider field is optional. The reply is {"success": true, "cancelled": true}. For single-provider requests, a client that disconnects before the reply is finished also cancels the request.

WebSocket updated in v5.5.0

Real-time bidirectional streaming at ws://localhost:3210/ws (same host and port as the REST API, which must be enabled). Messages accept the same thinking_level option as REST.

Example

const ws = new WebSocket("ws://localhost:3210/ws"); ws.onopen = () => { ws.send(JSON.stringify({ action: "ask", model: "gemini", thinking_level: "high", message: "What is a closure?", id: "req_1" })); }; ws.onmessage = (e) => { const msg = JSON.parse(e.data); console.log(msg); // streamed chunks, status events, or completion };

Security & Privacy

Proxima is architected with a strict local-first security model. Proxima does not operate servers that receive your telemetry, code snippets, prompt histories or API keys. Your prompts go only to the provider or local model you choose.

Security PrincipleTechnical Implementation
Local-First Loopback MCP/IPC (:19222 by default), REST/WS (:3210 by default) and Agent HTTP (:8500) bind exclusively to 127.0.0.1. Zero public internet ports are opened.
Credential Isolation Session mode reuses existing local browser cookies inside sandboxed views. BYOK API keys are encrypted at rest using the operating system's keychain (where the platform provides one) through (Electron SafeStorage).
Zero Telemetry Proxima sends no analytics or usage telemetry to its author. Network traffic is limited to the AI providers you choose, update checks against GitHub Releases in installed builds, the web tools you call (ddg_search, web_scrape), and Context7 only if you enable it with PROXIMA_CONTEXT7=1.
Gated Agent Safety The Python agent includes 3-tier safety execution gates (Auto, Smart, Suggest) preventing unauthorized bash commands or destructive file system overwrites.
SSRF Guardrails The web_scrape tool and internal HTTP fetchers validate DNS targets against private IP blocks (10.0.0.0/8, 192.168.0.0/16, 169.254.0.0/16) to prevent SSRF vulnerabilities.
Vulnerability Reporting: If you discover a potential security flaw, please review our Security Policy (SECURITY.md) and report via private GitHub Security Advisories rather than public issues.

Testing Strategy

Proxima maintains strict test suites across both the JavaScript Electron Hub and the Python Autonomous Agent runtime:

# Run JavaScript unit & MCP integration tests npm test # Run Python Autonomous Agent test suite cd proxima-agent python -m unittest discover -s tests -p "test_*.py"

For details on our mock-at-boundary testing methodology and continuous integration coverage, see TESTING.md on GitHub ↗.

Contributing & Community

Contributions to Proxima are welcome! Whether you are implementing new MCP tool handlers, improving session interception, or enhancing agent self-healing loops, please follow our standard guidelines:

Sponsors & Backers

Proxima is an independent open-source project supported by developer sponsors.

Special thanks to Star Sponsor @TheNetworker. Support ongoing open-source development on GitHub Sponsors (Zen4-bit) ↗.

Troubleshooting

Windows Firewall Prompt

Proxima runs locally on localhost:19223, localhost:3210, and localhost:8500. Click "Allow" — only accepts local loopback connections from your machine.

Provider shows "Not logged in"

Click the provider tab in the desktop application and complete standard browser login. Use email OTP codes for ChatGPT, Claude, and Perplexity. Gemini uses session cookies from your active browser.

MCP Tools not appearing in IDE

  • Ensure Proxima is running in your system tray or terminal.
  • Verify the absolute file path in your MCP config (use the Copy button in Settings).
  • Restart your coding environment (Cursor, VS Code, Windsurf, or Antigravity).

CLI: "proxima" not found

Open a fresh terminal window after installation. If still unresolved, click 🔧 Fix in Settings → CLI inside the Proxima desktop app or run npm link from source.

CLI: "Cannot connect to Proxima"

Proxima must be running and the REST API must be enabled. The CLI connects to http://localhost:3210. See the CLI & SDK Guide →.

WebSocket won't connect

The WebSocket stream shares the REST API server daemon. Enable the REST API in Proxima Settings first.

License & Terms

Proxima is licensed under the Proxima Personal Use License (Personal, Non-Commercial use only).

Review the full license terms and conditions in the official LICENSE file on GitHub ↗. For commercial or enterprise licensing inquiries, please contact the repository author or reach out via @Zen4-bit.