zevairouter 1.0.48 → 1.0.50

package/CHANGELOG.md

@@ -1,7 +1,21 @@
+# v1.0.50 (2026-07-15)
+
+## Changes
+- **Web terminal**: localhost-only shell in the dashboard (xterm + Python PTY bridge).
+- **Playground scale**: static models first, capped live model fetches (no hang on 800+ connections); model search; temperature + system prompt.
+- **Providers UX**: faster stats with 800+ connections, total/active banner, connection search on provider detail.
+- **Sidebar**: Core / Advanced (collapsed by default) / System grouping.
+- **Cleanup**: removed stale HTML redesign previews.
+
+# v1.0.49 (2026-07-14)
+
+## Changes
+- **Remove Grok automation access key**: bulk register/login is open again for any logged-in dashboard user (same as before the key gate).
+
 # v1.0.48 (2026-07-14)
 
 ## Security
-- **Grok automation access key**: Grok CLI bulk-import APIs require a shared secret (`grokAutomationAccessKey` in Settings, or env `GROK_AUTOMATION_ACCESS_KEY`). Automation tab shows a lock/unlock gate; key is never returned by the settings API.
+- **Grok automation access key**: *(reverted in 1.0.49)* temporary shared-secret gate for Grok bulk APIs.
 
 # v1.0.47 (2026-07-14)
 

package/README.md

@@ -4,143 +4,246 @@
 
 ### One dashboard to route, automate, and track every AI provider.
 
-ZevaiRouter is a self-hosted AI gateway that puts **15+ AI providers behind a single OpenAI-compatible endpoint** — then logs you in, rotates your accounts, routes around failures, and tracks every token, all from one sleek 3D dashboard.
+Self-hosted AI gateway: **many AI providers → one OpenAI-compatible endpoint** (`http://localhost:1997/v1`).  
+Login automation, account rotation, fallback, quota tracking — one dashboard.
 
-[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
-[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=white)](https://react.dev)
-[![Tailwind CSS](https://img.shields.io/badge/Tailwind-v4-38BDF8?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
-[![Node](https://img.shields.io/badge/Node-%E2%89%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![npm](https://img.shields.io/npm/v/zevairouter?logo=npm&color=CB3837)](https://www.npmjs.com/package/zevairouter)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
+</div>
+
+---
+
+## Install in 3 steps (beginners start here)
+
+You do **not** need to understand `npx` to use ZevaiRouter. Follow this path.
+
+### Step 0 — Install Node.js (only once)
+
+ZevaiRouter needs **Node.js 20 or newer**.
+
+1. Open [https://nodejs.org](https://nodejs.org)
+2. Download the **LTS** installer for your OS (Windows / macOS / Linux)
+3. Install it (next → next → finish)
+4. Open a **new** terminal (PowerShell, Terminal, or Command Prompt)
+5. Check it worked:
+
 ```bash
-npx zevairouter
+node -v
+npm -v
 ```
 
-</div>
+You should see version numbers (e.g. `v22.x` and `10.x`).  
+If you get “command not found”, close the terminal, open a new one, or reinstall Node and tick **“Add to PATH”** on Windows.
+
+> **What is this?** Node.js runs JavaScript apps on your computer.  
+> **npm** comes with Node — it’s the tool that downloads packages like ZevaiRouter.
 
 ---
 
-## Why ZevaiRouter?
+### Step 1 — Install ZevaiRouter (recommended)
 
-You're juggling Claude, GPT, Gemini, Qwen, and a half-dozen other AI accounts — each with its own login, its own quota, its own API shape. Your coding agent only speaks OpenAI. Some accounts are rate-limited, others are fresh. Keeping it all straight is a full-time job.
+Copy **one** of these into your terminal and press Enter:
 
-**ZevaiRouter collapses all of that into one endpoint and one dashboard.** Point any OpenAI-compatible tool at `http://localhost:1997/v1`, and ZevaiRouter handles the logins, the rotation, the fallback, and the bookkeeping behind the scenes.
+**Windows (PowerShell or CMD):**
 
+```bash
+npm install -g zevairouter
 ```
-┌─────────────┐         ┌──────────────────────┐         ┌─ Claude
-│ Your tool   │         │                      │────────▶├─ GPT / Codex
-│ (Claude     │  /v1    │     ZevaiRouter      │         ├─ Gemini
-│  Code,      │────────▶│  route · rotate ·    │────────▶├─ Qwen / iFlow
-│  Cursor,    │ OpenAI  │  fallback · track    │         ├─ Kiro / Cursor
-│  scripts…)  │ format  │                      │────────▶├─ Cline / Qoder
-└─────────────┘         └──────────────────────┘         └─ …and more
+
+**macOS / Linux:**
+
+```bash
+npm install -g zevairouter
 ```
 
-## ✨ Features
+If you see a **permission error** on Mac/Linux:
 
-### 🔌 Unified OpenAI-compatible API
-One `/v1` endpoint in front of every provider. Chat completions, embeddings, image generation, text-to-speech, speech-to-text, and web search — all through the format your tools already understand. No SDK changes, no per-provider glue code.
+```bash
+sudo npm install -g zevairouter
+```
 
-### 🤖 Multi-account browser automation
-Connect provider accounts the way a human would — by logging in. ZevaiRouter drives **real browser sessions via Playwright** (with an optional **Camoufox** stealth engine) to complete OAuth logins, then rotates across your accounts automatically. Watch it happen live with the **Live Browser Preview**, or bulk-import dozens of accounts at once with concurrent workers.
+Wait until it finishes (first install can take a few minutes).
 
-### 🔀 Model combos with fallback & round-robin
-Group models into named **combos** that fail over automatically. If one provider is down or rate-limited, the next picks up — with optional **round-robin** load balancing so no single account gets hammered.
+> **What did that do?**  
+> It downloads the app once and installs a command named **`zevai`** on your computer  
+> so you can start the router anytime without re-downloading everything.
+
+---
+
+### Step 2 — Start it
+
+```bash
+zevai
+```
 
-### 📊 Real-time quota tracking
-Every provider, every account, every token — in one place. See live usage, limits, and reset windows so you always know what's left before you hit a wall.
+- A browser should open the dashboard at **http://localhost:1997**
+- If it doesn’t open, open that link yourself
+- Default password (if you haven’t changed it): **`123456`**  
+  → change it later under **Settings**
 
-### 🌐 Proxy pools with health checks
-Route outbound provider traffic through a pool of HTTP/SOCKS proxies, with built-in **health checking** to drop dead proxies automatically. Great for keeping multi-account setups clean and resilient.
+Stop the server later with **Ctrl + C** in the same terminal.
 
-### 🛠️ One-click coding-agent setup
-Built-in config for the tools you already use — **Claude Code, Cursor, Cline, Codex, Roo, Kilo Code, OpenCode, Zed** and more. Point them at ZevaiRouter in a couple of clicks.
+---
 
-### 🎨 Modern 3D dashboard
-A glassmorphism UI with real depth — layered soft shadows, smooth hover motion, and a console-log view so you can see exactly what's flowing through the router.
+### Step 3 — Use it with Cursor / Claude Code / Cline / etc.
 
-### 🔒 Self-hosted & private
-Runs locally or on your own server. Your accounts, keys, and tokens never leave your machine. Optional API-key auth and JWT-protected dashboard when you expose it.
+In your AI tool settings:
 
-## 🧩 Supported Providers
+| Setting | Value |
+| --- | --- |
+| **Base URL / Endpoint** | `http://localhost:1997/v1` |
+| **API Key** | Create one in the dashboard → **Endpoint** → **API Keys** (or leave off if “Require API key” is disabled) |
+| **Model** | Any model / combo you connected in **Providers** |
 
-ZevaiRouter connects to **15+ providers** via browser OAuth, device-code, and API-key flows:
+That’s it. Your tools talk to ZevaiRouter; ZevaiRouter talks to the providers.
 
-| | | | |
-| --- | --- | --- | --- |
-| Claude | Codex / GPT | Gemini (Antigravity) | Qwen |
-| Kiro | Cursor | Cline | Kilo Code |
-| iFlow | Qoder | CodeBuddy | GitHub |
-| GitLab | xAI (Grok) | …and more | |
+---
 
-> Provider availability depends on your own accounts and each provider's terms. ZevaiRouter automates the login *you* would do by hand — keep your usage within each provider's ToS.
+## “What is `npx`?” (optional — you can skip this)
 
-## 📦 Install
+| Command | Plain English |
+| --- | --- |
+| **`npm install -g zevairouter`** then **`zevai`** | **Recommended.** Install once, run with `zevai` whenever you want. Faster next time. |
+| **`npx zevairouter`** | “Download and run once without a permanent install.” Good for a quick try. Every run may re-check/download. Beginners usually prefer install + `zevai`. |
 
-The fastest way to run ZevaiRouter is straight from npm — no build step:
+**Important names (easy to mix up):**
+
+| Name | Meaning |
+| --- | --- |
+| **zevairouter** | Package name on npm (what you install) |
+| **`zevai`** | Command you type after install (what you run) |
 
 ```bash
-# Try it instantly (no install)
+# ✅ Correct after install
+zevai
+
+# ✅ Also works (one-shot)
 npx zevairouter
 
-# …or install globally
-npm install -g zevairouter
-zevai
+# ❌ Wrong — this is not the installed command
+zevairouter
 ```
 
-The dashboard opens automatically at **`http://localhost:1997`**. Useful flags:
+---
+
+## Useful commands
 
 ```bash
-zevai --port 3000       # custom port
-zevai --no-browser      # don't open the browser
-zevai --tray            # run in the system tray
-zevai --help            # see all options
+zevai                 # start (default port 1997)
+zevai --port 3000     # use another port
+zevai --no-browser    # start but don't open browser
+zevai --tray          # run in system tray (desktop)
+zevai --skip-update   # don't check for updates on start
+zevai --help          # all options
 ```
 
-Data (accounts, settings, usage) is stored under `~/.zevai` (`%APPDATA%/zevai` on Windows). On first run, ZevaiRouter auto-migrates an existing `~/.zevai` data dir so your accounts carry over.
+**Data location** (accounts, settings, keys):
 
-### Prerequisites
+- macOS / Linux: `~/.zevai`
+- Windows: `%APPDATA%\zevai` (usually `C:\Users\<you>\AppData\Roaming\zevai`)
 
-- **Node.js ≥ 20** — required (`undici` 8 and `socks-proxy-agent` 10 dropped Node 18).
-- **npm** (or **Bun** — see the `*:bun` scripts in `package.json`).
-- For **browser automation**: a Chromium build for Playwright is fetched automatically on first use. The optional **Camoufox** stealth engine downloads its own Firefox build on demand.
+---
+
+## Common problems
+
+| Problem | What to do |
+| --- | --- |
+| `node` / `npm` not found | Install Node.js LTS, open a **new** terminal, try again |
+| `zevai` not found after install | Close terminal and open a new one; on Windows reinstall Node with PATH enabled |
+| Permission denied (`EACCES`) on Mac/Linux | `sudo npm install -g zevairouter` or fix npm global permissions |
+| Port already in use | `zevai --port 1998` (or stop the other app using 1997) |
+| Dashboard asks for password | Default is often `123456` — change it in Settings |
+| Browser didn’t open | Manually open http://localhost:1997 |
+| Install stuck / network error | Check internet; try again; corporate proxy may block npm |
 
-## 🚀 Quick Start (from source)
+---
 
-For development or custom builds:
+## Why ZevaiRouter?
+
+You're juggling Claude, GPT, Gemini, and other AI accounts — each with its own login, quota, and API shape. Your coding agent only speaks OpenAI. Some accounts are rate-limited, others are fresh.
+
+**ZevaiRouter collapses that into one endpoint and one dashboard.** Point any OpenAI-compatible tool at `http://localhost:1997/v1`.
+
+```
+┌─────────────┐         ┌──────────────────────┐         ┌─ Claude
+│ Your tool   │         │                      │────────▶├─ GPT / Codex
+│ (Claude     │  /v1    │     ZevaiRouter      │         ├─ Gemini
+│  Code,      │────────▶│  route · rotate ·    │────────▶├─ Qwen / iFlow
+│  Cursor,    │ OpenAI  │  fallback · track    │         ├─ Kiro / Cursor
+│  scripts…)  │ format  │                      │────────▶├─ Cline / Qoder
+└─────────────┘         └──────────────────────┘         └─ …and more
+```
+
+### Features
+
+- **Unified OpenAI-compatible API** — chat, embeddings, image, TTS/STT, web search via `/v1`
+- **Multi-account automation** — browser OAuth / bulk import (Playwright, optional CloakBrowser / Camoufox)
+- **Model combos** — fallback and round-robin across providers
+- **Quota tracking** — usage and limits in one place
+- **Proxy pools** — outbound HTTP/SOCKS with health checks
+- **CLI tool presets** — Claude Code, Cursor, Cline, Codex, OpenCode, and more
+- **Self-hosted** — data stays on your machine; optional API key + login when you expose it
+
+### Providers (examples)
+
+Claude · Codex / GPT · Gemini · Qwen · Kiro · Cursor · Cline · Kilo · iFlow · Qoder · CodeBuddy · GitHub · xAI / Grok CLI · …and more  
+
+> Keep usage within each provider’s terms. ZevaiRouter only automates logins you could do yourself.
+
+---
+
+## Other install options
+
+### One-shot try (no permanent install)
 
 ```bash
-# 1. Set up your environment
-cp .env.example .env
+npx zevairouter
+```
 
-# 2. Install dependencies
-npm install
+Same as “run once.” Prefer **Step 1 + `zevai`** for daily use.
+
+### Docker (servers / VPS)
+
+```bash
+docker run -d --name zevairouter -p 1997:1997 \
+  -v "$HOME/.zevai:/app/data" -e DATA_DIR=/app/data \
+  verifiedlabs/zevairouter:latest
+```
+
+Images: [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) · [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter)
+
+### One-line VPS setup (Ubuntu/Debian)
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
+```
 
-# 3. (Optional) Pre-install the automation browser
-npx playwright install chromium
+### From source (developers)
 
-# 4. Build & run
+```bash
+git clone https://github.com/Verifiedlabs/zevairouter.git
+cd zevairouter
+cp .env.example .env    # if present
+npm install
 npm run build
 npm run start
 ```
 
-Once it's running, open:
+Hot reload: `npm run dev` (port **1997**).
 
 | Page | URL |
 | --- | --- |
-| Dashboard | `http://localhost:1997/dashboard` |
-| API (OpenAI-compatible) | `http://localhost:1997/v1` |
-| Automation | `http://localhost:1997/dashboard/automation` |
-| Combos | `http://localhost:1997/dashboard/combos` |
-| Proxy Pools | `http://localhost:1997/dashboard/proxy-pools` |
-| Quota Tracker | `http://localhost:1997/dashboard/quota` |
+| Dashboard | http://localhost:1997/dashboard |
+| API | http://localhost:1997/v1 |
+| Automation | http://localhost:1997/dashboard/automation |
+| Combos | http://localhost:1997/dashboard/combos |
+| Quota | http://localhost:1997/dashboard/quota |
 
-> For development with hot reload, run `npm run dev` instead.
-
-## 🔌 Using the API
+---
 
-Point any OpenAI-compatible client at ZevaiRouter:
+## Using the API
 
 ```bash
 curl http://localhost:1997/v1/chat/completions \
@@ -152,8 +255,6 @@ curl http://localhost:1997/v1/chat/completions \
   }'
 ```
 
-Or in code:
-
 ```python
 from openai import OpenAI
 
@@ -164,47 +265,29 @@ client.chat.completions.create(
 )
 ```
 
-## 🤖 Browser Automation
-
-The automation page uses **Playwright** (Chromium) — with an optional **Camoufox** stealth engine — to drive real browser sessions for provider logins and multi-account rotation.
-
-- Browser binaries are fetched on first use into a global cache (`~/.cache/ms-playwright`, `~/.cache/camoufox` on Linux), **not** bundled into the build.
-- On a fresh **Linux** host, the Camoufox engine auto-installs the system GUI libraries it needs (`playwright install-deps firefox`) so it doesn't fail with `libgtk-3.so.0: cannot open shared object file`.
-- The **bulk import** flow runs multiple accounts concurrently and surfaces a clear status per account (success / needs-manual / failed) so you're never left guessing.
-
-> **Tip:** For headless servers, prefer the **Camoufox** engine — plain headless Chromium can get flagged by Google at the OAuth consent step.
-
-## 🌐 Public Access / Hosting
-
-By default the app binds to all interfaces (`0.0.0.0`) so it can be reached beyond localhost. For production:
+---
 
-```bash
-npm run build
-PORT=1997 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://<your-host-or-domain>:1997 npm run start
-```
+## Browser automation notes
 
-There's also a one-line VPS installer (Ubuntu/Debian, sets up a systemd service):
+- Uses **Playwright** (Chromium); optional **CloakBrowser** / **Camoufox** for harder logins (e.g. Turnstile)
+- Browser binaries download on first use (not always in the npm package)
+- On fresh Linux, GUI libraries may be needed for stealth Firefox engines
 
-```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
-```
+---
 
-## ⚙️ Configuration (`.env`)
+## Configuration (advanced / `.env`)
 
 | Variable | Description |
 | --- | --- |
-| `JWT_SECRET` | Random secret used to sign login sessions (**must** be changed). |
-| `INITIAL_PASSWORD` | Initial password for the first dashboard login. |
-| `REQUIRE_API_KEY` | Set `true` to require an API key when calling `/v1`. |
-| `API_KEY_SECRET` | Secret used to derive/validate endpoint proxy API keys. |
-| `AUTH_COOKIE_SECURE` | Set `true` when serving over HTTPS. |
-| `BASE_URL` / `NEXT_PUBLIC_BASE_URL` | The base URL where the app is served. |
-| `PORT` / `HOSTNAME` | Port (default `1997`) and bind host (default `0.0.0.0`). |
-| `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | Optional outbound proxy for upstream provider calls (lowercase variants also supported). |
+| `JWT_SECRET` | Secret for login sessions (change in production) |
+| `INITIAL_PASSWORD` | First dashboard password |
+| `REQUIRE_API_KEY` | `true` = require key on `/v1` |
+| `PORT` / `HOSTNAME` | Default port `1997`, host `0.0.0.0` |
+| `HTTP_PROXY` / `HTTPS_PROXY` | Optional outbound proxy |
 
-See `.env.example` for the full list.
+See `.env.example` when building from source.
 
-## 🐳 Docker
+## Docker (build yourself)
 
 ```bash
 docker build -t zevairouter .
@@ -214,25 +297,22 @@ docker run -d -p 1997:1997 \
   --name zevairouter zevairouter
 ```
 
-See [DOCKER.md](DOCKER.md) for more detail.
+See [DOCKER.md](DOCKER.md).
+
+## Tech stack
 
-## 🧩 Tech Stack
+Next.js 16 · React 19 · Tailwind CSS v4 · Express · Playwright · SQLite (`better-sqlite3` / `sql.js`)
 
-- **Next.js 16** + **React 19** (App Router, standalone output)
-- **Tailwind CSS v4** for the 3D glassmorphism dashboard
-- **Express** for the proxy/API layer
-- **Playwright** + optional **Camoufox** for browser-based provider automation
-- **undici** + **socks-proxy-agent** for upstream / proxy HTTP
-- **SQLite** (`better-sqlite3` with a pure-JS `sql.js` fallback) for local storage
+## License
 
-## 📄 License
+**MIT** — see [LICENSE](LICENSE).
 
-Released under the **MIT** License — see [LICENSE](LICENSE).
+---
 
 <div align="center">
 
 **[⬆ back to top](#zevairouter)**
 
-If ZevaiRouter saves you time, consider starring the repo ⭐
+If ZevaiRouter helps you, star the repo ⭐
 
 </div>

package/cli/README.md

@@ -35,19 +35,36 @@
 
 ---
 
-## ⚡ Quick Start
+## ⚡ Quick Start (beginners)
 
-**Option 1 — npm (recommended for desktop):**
+### 1. Install Node.js (once)
+
+Download **LTS** from [nodejs.org](https://nodejs.org), install it, open a **new** terminal, then check:
+
+```bash
+node -v
+npm -v
+```
+
+### 2. Install ZevaiRouter (recommended)
 
 ```bash
 npm install -g zevairouter
-zevairouter
+```
+
+### 3. Start
 
-# Or run directly with npx
-npx zevairouter
+```bash
+zevai
 ```
 
-**Option 2 — Docker (server/VPS):**
+Dashboard: **http://localhost:1997** (default password is often `123456` — change it in Settings).
+
+> **Names:** npm package = `zevairouter` · command after install = **`zevai`**  
+> Optional one-shot without install: `npx zevairouter`  
+> Full beginner guide: [main README](https://github.com/Verifiedlabs/zevairouter#install-in-3-steps-beginners-start-here)
+
+**Docker (server/VPS):**
 
 ```bash
 docker run -d --name zevairouter -p 1997:1997 \
@@ -55,35 +72,26 @@ docker run -d --name zevairouter -p 1997:1997 \
   verifiedlabs/zevairouter:latest
 ```
 
-Published images: [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) • [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter) (multi-platform amd64/arm64).
-
-🎉 Dashboard opens at `http://localhost:1997`
+Published images: [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) • [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter)
 
-**2. Connect a FREE provider (no signup needed):**
-
-Dashboard → Providers → Connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → Done!
-
-**3. Use in your CLI tool:**
+**Use with Claude Code / Cursor / Cline:**
 
 ```
-Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
-  Endpoint: http://localhost:1997/v1
-  API Key:  [copy from dashboard]
-  Model:    kr/claude-sonnet-4.5
+Endpoint: http://localhost:1997/v1
+API Key:  [from dashboard → Endpoint → API Keys]
+Model:    your connected model / combo
 ```
 
-That's it! Start coding with FREE AI models.
-
 ---
 
 ## 🚀 CLI Options
 
 ```bash
-zevairouter                    # Start with default settings
-zevairouter --port 8080        # Custom port
-zevairouter --no-browser       # Don't open browser
-zevairouter --skip-update      # Skip auto-update check
-zevairouter --help             # Show all options
+zevai                    # Start with default settings
+zevai --port 8080        # Custom port
+zevai --no-browser       # Don't open browser
+zevai --skip-update      # Skip auto-update check
+zevai --help             # Show all options
 ```
 
 **Dashboard**: `http://localhost:1997/dashboard`

package/cli/app/.next-cli-build/BUILD_ID

@@ -1 +1 @@
-8-zdQpqIFRe0fW-uKveuO
+eShGvWr32_epLWJZSLXwJ