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.
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.
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.
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.
Option 2: Run from Source
Clone the official repository from GitHub (Zen4-bit/Proxima) and install dependencies:
Configuration
1. MCP Server Configuration (IDEs)
Add this to your AI coding app's MCP configuration (Cursor, VS Code, Claude Desktop, Antigravity, etc.):
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 / Port | Protocol | Description |
|---|---|---|
127.0.0.1:19222 | Local 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:3210 | HTTP / WebSocket | Optional 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:8500 | HTTP / REST | Autonomous Agent Web Dashboard, live state observer, and task dispatcher. |
ws://127.0.0.1:9222 | WebSocket | Chrome DevTools Protocol (CDP) remote debugging port for automated browser sessions. |
~/.proxima-agent/ | SQLite 3 | Directory 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 Name | Description |
|---|---|
list_available_models | Lists 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_chatgpt | Query ChatGPT. Accepts auto or any model slug returned by list_available_models. |
ask_claude | Query Claude (strong at coding and reasoning). |
ask_gemini | Query Gemini. Supports sub-engines (argon, flash, pro) and an optional thinking_level: default, low, medium, high. |
ask_perplexity | Query Perplexity (web search with citations). |
ask_model | Universal chat: send to any enabled session provider or configured BYOK provider. Supports thinking_level. |
ask_all_ais | Send the same message to several providers in parallel and get every answer side by side. |
smart_query | Best general entry point. Modes: auto (fast single AI), verify (primary plus a cross-model check), consensus (all vote), collaborate (role-based teamwork). |
new_conversation | Reset 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 URI | Content |
|---|---|
proxima://models | The same live model list as list_available_models, as JSON. |
proxima://status | Server name, version, loaded modules, enabled providers, and whether the bridge to the desktop app is connected. |
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 Name | Description |
|---|---|
generate_code | Write new code from a description, with comments, error handling and usage examples. |
explain_code | Explain a snippet line by line. |
review_code | Review a snippet for bugs, security, performance and best practices. |
optimize_code | Improve code for speed, memory or readability and show before/after. |
verify_code | Quick best-practices check of a snippet for a stated purpose. |
solve | End-to-end solution for a coding task, feature or bug. The broadest code tool. |
fix_error | Diagnose an error or stack trace: root cause, fix, prevention, full code. |
explain_error | Explain an error in plain language with likely causes and step-by-step fixes. |
convert_code | Translate code between languages or frameworks, preserving behavior. |
write_tests | Generate a complete test file for a given file path: happy path, edge cases, errors. |
build_architecture | Design a system architecture: stack, schema, APIs, deployment. |
security_audit | Deep 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 Name | Description |
|---|---|
deep_search | AI research with typed prompts: web, reddit, github, news, math, academic, factcheck, stats. |
ddg_search | Free DuckDuckGo search returning ranked title, URL and snippet. No provider or key needed. Detects rate limits and bot challenges. |
web_scrape | Fetch one URL and convert it to clean Markdown. Guarded against SSRF. |
get_ui_reference | UI/UX design reference: colors, typography, layout, components, accessibility. |
Content & Verification (4 tools)
Write, compare, debate and cross-check.
| Tool Name | Description |
|---|---|
content | General text tool with modes: summarize, write, brainstorm, howto, analyze, extract, improve. |
compare | Compare two items, options or technologies side by side, optionally for a given context. |
debate | Providers argue different stances on a topic, then conclude. Needs two or more enabled providers for a true multi-AI debate. |
verify | Ask 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 Name | Description |
|---|---|
crew | Role-based pipeline (default Researcher, Writer, Reviewer), each role on its own provider, passing output down the chain. |
run_workflow | Ordered multi-step pipeline where each step's output feeds the next, with automatic provider routing per step. |
run_loop | Iterate one task: generate, have another AI review, improve, until it converges or reaches maxTurns. |
proxima_agentic_status | Read-only status of the agentic pipeline: mode (session or BYOK), router and provider health, memory, run-loop, cost. |
proxima_cost_report | Read-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 Name | Description |
|---|---|
analyze_file | Analyze a file or whole directory: codebase packing, smart slicing, symbol extraction, grep and secret scan. |
review_code_file | Review a single code file on disk, optionally focused on bugs, performance, security or style. |
clear_cache | Clear the in-memory response cache so the next identical question is asked fresh. |
show_window | Show the Proxima window. |
hide_window | Hide the window. The app and MCP keep running in the background. |
toggle_window | Toggle the window between visible and hidden. |
set_headless_mode | Enable 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.
http://localhost:8500 with live task execution monitoring, workspace inspection, and execution safety controls.
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 Vault | Function & Stored Data |
|---|---|
vault.db | Full conversation histories, session lineages, and branch trees. |
insights.db | Workspace facts, technology stack preferences, and environment parameters. |
memory.db | Compiler error signatures paired with verified code diff solutions. |
skills.db | Procedural 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.
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
Flags and environment
| Option | Meaning |
|---|---|
--model, -m | Override 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, -l | Target language for code generation. |
--to / --from | Target and source language for translate. |
--json | Print the raw JSON response, for scripting. |
PROXIMA_HOST, PROXIMA_PORT / PROXIMA_REST_PORT | Override 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
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
Example
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
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
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 Principle | Technical 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. |
Testing Strategy
Proxima maintains strict test suites across both the JavaScript Electron Hub and the Python Autonomous Agent runtime:
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:
- Workflow: Fork ➔ Feature Branch ➔ Pull Request on GitHub (Zen4-bit/Proxima).
- Code Guidelines: Review our Contributing Guide (CONTRIBUTING.md) for architectural patterns and style conventions.
- Community Standards: All contributors and community members are expected to follow our Code of Conduct (CODE_OF_CONDUCT.md).
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.