What GPTPortal is (and what it isn't)

It is:

• A local-first application. It runs on your computer (or your own server). Your API keys live in a .env file that is never committed. Your conversations are held in your browser session and, optionally, in files under public/uploads/. Nothing is sent anywhere except the actual API calls to whichever provider you chose for a given message.
• A single unified interface across many providers. Switch from GPT-5.5 to Claude Opus to Gemini 3 to a local Llama in one dropdown, mid-project, without changing anything else.
• Pay-as-you-go by design. You are billed directly by each provider for exactly what you use, through your own keys. There is no subscription and no middleman. For heavy users this is dramatically cheaper than paying for several chat subscriptions; for light users it can cost a few dollars a month.

It is not:

• A hosted, multi-tenant SaaS. There is a single Basic-Auth login gate and per-browser session state. You can expose it on a network, but it is designed for one person (or a trusted household) running it locally.
• A no-key demo. Every model call goes through a provider API, so you need at least one provider key. Most providers give new accounts some free credit; several models are effectively free through Groq or a local endpoint.
• A heavyweight "AI platform." There is intentionally no vector database, no RAG pipeline, no agent-orchestration subsystem, no packaged desktop binary. If you want those, this is a good base to build on, but they are out of scope here.

Feature overview

Models and providers

• Curated core catalog of current models across OpenAI, Anthropic, Google, xAI, DeepSeek, Groq, Moonshot (Kimi), and Mistral, defined in a single JSON file.
• The entire OpenRouter catalog (hundreds of models) loaded live and cached, so anything OpenRouter serves is one click away.
• Your own OpenAI-compatible endpoints — Ollama, LM Studio, vLLM, LocalAI, or a remote gateway — added through environment variables with no code, auto-discovered into the model picker.
• A searchable, categorized model picker with per-provider logos, so you can find a model by name or family instead of scrolling.

Conversation

• Token streaming end to end. Answers appear as they are generated, and models that expose their reasoning stream that separately from the final answer.
• Markdown rendering with syntax-highlighted code blocks (highlight.js), math (KaTeX), and per-code-block copy buttons. Output is sanitized before it touches the DOM.
• Reasoning and verbosity controls for models that support them, plus temperature and max-token sliders, all wired through to the request.
• Vision: attach an image and ask a vision-capable model about it.
• File uploads: attach text-based files; their name and contents are added to your prompt.
• Voice: dictate a message (speech-to-text) and have replies read back to you (text-to-speech).
• Image generation: prefix a message with Generate: to produce an image inline.
• Assistants mode (OpenAI): a stateful, tool-using assistant with a persistent thread and code execution, for people who want that workflow.

Workflow

• Compare view: send one prompt to several models at once and read the answers side by side, each with its own cost.
• Presets: save and reapply bundles of system prompt + temperature + max tokens + reasoning effort + verbosity.
• Context, token, and cost tracking: a live indicator of how full the context window is and what the conversation has cost.
• Export the conversation to a self-contained HTML file.
• Edit the system prompt and your .env from inside the browser.
• Prompt caching for Claude, to cut the cost of long, stable system prompts.

Interface

• A fully redesigned, token-driven UI with light and dark themes (auto-detected from your OS, with a manual toggle that persists).
• A semantic, responsive shell: collapsible chat-history rail, main chat column, and a docked composer. It works on a laptop and degrades gracefully to a phone.
• Keyboard shortcuts for every common action.

Architecture

The point of the 2.0 rewrite was to make the codebase legible. Here is the whole map.

node server.js
    │
    ▼
src/server/core/Application.js         ← wires everything together, emits lifecycle events
    ├── MiddlewareManager              ← Basic Auth, sessions, CORS, rate limiting, CSP, body parsing, static files
    ├── ServiceManager                 ← instantiates and holds the services below
    └── RouteManager                   ← mounts every HTTP route onto Express

Services (src/server/services/**)
    ├── providers/providerFactory.js   ← picks a handler for a given model id and dispatches to it
    │     ├── openai/**                ← Chat Completions + Responses API, images, audio, assistants
    │     ├── claudeHandler.js         ← Anthropic Messages API, adaptive thinking, web search, caching
    │     ├── geminiHandler.js         ← Google @google/genai SDK
    │     ├── grok / deepseek / groq / kimi / mistral / openrouterHandler.js
    │     ├── customEndpointHandler.js ← generic OpenAI-compatible handler for your own endpoints
    │     └── endpointResolver.js      ← turns `<prefix>/<model>` + config into a concrete call target
    ├── modelProviders/modelRegistry.js← unifies core + OpenRouter + custom models for the API/UI
    ├── costService / tokenService / contextWindowService / tokenCountService
    ├── promptCacheService             ← Claude cache-control breakpoints
    ├── titleService / exportService / modelSyncService
    └── shared/modelLoader.js          ← loads and caches the model catalog

Frontend (public/**, no build step)
    ├── portal.html + chat.css         ← app shell + the single design-token stylesheet
    └── js/modules/*.js                ← dynamicModelManager, modelUI, modelSearch, chatManager,
                                          messageHandler, uiManager, portalInit, presets, compare

A few design decisions worth knowing up front, because they explain how everything else behaves:

• The model catalog is the source of truth. public/js/data/models.json defines every core model. Routing, pricing, context windows, and capability flags are read from it. providerFactory consults each model's provider field first when deciding which handler to use, and only falls back to string-pattern matching for ids that aren't in the catalog (like OpenRouter's vendor/model ids). This means adding a model to an existing provider is usually a one-file change.
• Handlers share one contract. Every provider handler exposes handleRequest(payload) (non-streaming) and, where the provider supports it, async *streamCompletion(payload) that yields a small set of event types (thinking, text, usage, error). The rest of the system doesn't care which provider it's talking to.
• State is per-session, not global. Conversation history, the current image, and upload state live in req.session.chat, not in module-level variables, so two browsers don't step on each other.
• The frontend has no framework. Modules attach to window and coordinate through a handful of well-known objects (window.chatManager, window.dynamicModelManager, and so on). It is old-fashioned on purpose and easy to trace.

If you want to add a provider or model, read Extending and the dedicated MODEL_UPDATE.md.

Requirements

• Node.js 18 or newer. The current LTS is recommended. Download it from nodejs.org. Check your version with node --version.
• npm, which ships with Node. Check with npm --version.
• Git (optional but recommended) to clone and update the repository. You can also download the repo as a ZIP.
• At least one provider API key. Which one is up to you — see Providers and models. If you only have an OpenAI key, everything OpenAI works; the other providers simply stay disabled until you add their keys.
• A modern browser. Chrome, Edge, Firefox, Brave, Arc, and other Chromium/Firefox browsers all work well. Safari works for text but cannot do the voice features because WebKit lacks the audio codecs the recorder needs — use a Chromium browser or Firefox if you want voice.

Quick start

If you already know your way around a terminal:

git clone https://github.com/Zaki-1052/GPTPortal.git
cd GPTPortal
npm install
cp .env.example .env      # then edit .env: set USER_USERNAME, USER_PASSWORD, and at least one API key
node server.js

Open http://localhost:3000/portal, sign in with the username and password you set, pick a model, and start typing. That's the whole thing.

If you'd rather not touch a text editor, you can instead run node server.js first and visit http://localhost:3000/setup, which gives you a browser form to enter your keys and writes the .env for you.

Installation, step by step

This section assumes no prior experience. If you've done this kind of thing before, the Quick start above is all you need.

1. Install Node.js

Go to nodejs.org and install the LTS build for your operating system. This also installs npm, the package manager the project uses. When it's done, open a terminal — Terminal on macOS, Command Prompt or PowerShell on Windows — and confirm it worked:

node --version
npm --version

Both should print a version nu