What's New in Proxima 5.5.0
Proxima 5.5.0 (October 2026) changes how you pick models, how you control reasoning, and how clients find the local gateway. This page lists what is new, what changed under the hood, and what to check when you upgrade from 5.0.0. It is based on the project's CHANGELOG and migration notes, and on reading the 5.5.0 source for the details below.
claude or chatgpt, and the privacy model are unchanged. What you should do after upgrading is stop hard-coding model names, let scripts find the REST port automatically, and re-check your editor's tool list (41 tools now).
Highlights
- Live model discovery: a new
list_available_modelstool andproxima://modelsresource. - Thinking-depth controls for Gemini and other reasoning models, in MCP, REST, SDKs and the CLI.
- Request cancellation with
POST /v1/cancel. - Automatic port discovery through
rest-port.json. - Battle Mode in the in-page chat widget.
- ES module JavaScript SDK next to the CommonJS build.
Live model discovery
In 5.0.0, clients relied on fixed model aliases. Which models you could actually use depends on your account (a free ChatGPT login and a Team workspace expose different models), so a hard-coded name could fail in confusing ways or end up answered by a different model than you asked for.
5.5.0 asks the accounts you are logged into, and your BYOK configuration, what is available right now:
- ChatGPT: models are discovered from the logged-in account, so what you see follows your plan (Free, Plus, Team or Enterprise).
- Gemini: routes to engines such as
gemini:flash,gemini:pro,gemini:argonandgemini:latest, and keeps memory separate per account. - Each model is reported with its availability, capability tags (
Fast,Reasoning,Pro) and instructions for using it.
Where to get the list
No more silent substitution
If you explicitly ask for a model your account does not have, Proxima now returns an error that tells you to call list_available_models. It does not quietly answer with a different model. The core aliases auto, claude, chatgpt, gemini and perplexity keep working exactly as before.
Thinking-depth controls
You can now choose how much reasoning a model spends on a request. Two parameters are accepted:
They work in the MCP tools ask_gemini and ask_model, in the REST API and WebSocket, in the Python and JavaScript SDKs, in the CLI as --thinking, and in the Agent web UI and desktop chat widget.
The REST API validates the values. If you send thinking_level and reasoning_effort together with contradictory meanings, or ask for an option the model does not support, the reply is HTTP 400 rather than a guess.
Cancelling a request
Before 5.5.0, a request you abandoned kept running and held up the next request to the same provider. Now you can stop it:
The provider field is optional. The reply is {"success": true, "cancelled": true}. Cancellation is handled across MCP, REST and WebSocket, and a client that disconnects mid-request on a single-provider call also cancels it.
Automatic port discovery
The REST and WebSocket gateway still starts on port 3210. In 5.0.0, if another program already used that port, the gateway failed to start and clients could not connect. In 5.5.0 Proxima tries the following ports (up to 20 attempts) and writes the port it actually bound to a small file, rest-port.json:
The official Python SDK, JavaScript SDK, CLI and Agent read this file on their own. For curl scripts and third-party OpenAI-compatible clients, keep using http://localhost:3210, or read the live port from GET /api/status. You can also start from another port by setting PROXIMA_REST_PORT.
The MCP bridge to the desktop app (default 19222) follows the same idea: it scans a small range of nearby ports, and AGENT_HUB_PORT overrides the starting value. The REST API is still switched on from Settings; discovery only changes which port it uses.
Battle Mode and the chat widget
The interactive documentation served at http://localhost:3210 includes a live chat widget. It now fills its model list from your active sessions, shows capability badges, and shows a thinking-depth selector when you pick a reasoning model. Battle Mode sends the same prompt to two or more models and shows their answers side by side, with a status and timing for each cell, so you can compare providers on your own prompts.
JavaScript SDK as an ES module
The JavaScript SDK used to be a single CommonJS file. It now has its own package.json and a native ES module entry (proxima.mjs), so both styles work:
Other changes and fixes
- Gemini multi-turn: fixed follow-up conversations that stalled or were cut off early across Gemini engines.
- Conversation isolation:
new_conversationnow clears both the active and the MCP session context, so one turn no longer bleeds into the next. - DuckDuckGo search:
ddg_searchwas refactored into a reusable utility that detects rate limits and bot challenges. - Python check: the app now validates the Python version and the required agent modules before launching the agent, instead of only finding an interpreter.
- Agent retries: terminal provider failures are treated as non-retryable, which avoids pointless retry loops.
- CLI and SDKs: consistent ESM and CommonJS imports, normalized
/v1endpoint handling, and better handling of piped standard input. - Platforms: application data paths are resolved the same way on every OS, and the startup health check is more tolerant.
Upgrade checklist (5.0.0 to 5.5.0)
| Area | What changed | Do you need to act? |
|---|---|---|
| Core aliases | claude, chatgpt, gemini, perplexity, auto | No. They still work. |
| Explicit model names | Hard-coded names such as gemini:3.5-flash are replaced by discovered slugs such as gemini:flash or gemini:argon | Yes, if you pinned one. Run list_available_models and update the name. |
| Port | 3210 by default, with automatic fallback | Only if a script hard-codes a non-standard port. Official clients need nothing. |
| MCP tool list | 41 tools (list_available_models added) and a proxima://models resource | Re-open your editor's MCP tool list in Cursor, Windsurf or Claude Desktop so it picks up the new tool. |
| JavaScript SDK | ESM entry and package.json added | No. Existing require calls keep working. |
| Agent web console | FastAPI server on port 8500 | No. Open it from the Agent tab or run proxima-agent web. |
Steps
proxima status prints it, and so does the proxima://status MCP resource.proxima models (or call list_available_models) and replace any pinned model names in your scripts and prompts.GET /api/status.If something does not behave as described here, the troubleshooting guide covers the common cases, and the documentation and CLI and SDK reference describe each interface in full.