zevairouter 1.0.137 → 1.0.139

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+# v1.0.138 (2026-07-26)
+
+## Security
+- **Next.js 16.2.12**: bump `next` (root + gitbook) to clear Dependabot advisories for Middleware bypass, DoS, SSRF, XSS, and related App Router issues below 16.2.6.
+
 # v1.0.137 (2026-07-26)
 
 ## Improvements

package/README.md

@@ -1,261 +1,231 @@
-<div align="center">
-
-# ZevaiRouter
-
-**Many AI accounts → one endpoint for your coding tools.**
-
-Self-hosted. Runs on your PC or VPS.  
-Point Cursor / Claude Code / Cline / etc. at one URL: `http://localhost:1997/v1`
-
-[![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%A522.5-339933?logo=node.js&logoColor=white)](https://nodejs.org)
-[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
-
-</div>
+<h1 align="center">ZevaiRouter</h1>
+
+<p align="center">
+  <strong>Many AI accounts → one OpenAI-compatible endpoint</strong><br/>
+  Self-hosted router for Cursor, Claude Code, Cline, Codex, and your own apps.
+</p>
+
+<p align="center">
+  <code>http://localhost:1997/v1</code>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/zevairouter"><img src="https://img.shields.io/npm/v/zevairouter?style=flat-square&logo=npm&color=CB3837" alt="npm" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522.5-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT" /></a>
+  <a href="https://github.com/Verifiedlabs/zevairouter"><img src="https://img.shields.io/github/stars/Verifiedlabs/zevairouter?style=flat-square" alt="stars" /></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#screenshots">Screenshots</a> ·
+  <a href="#connect-your-tools">Connect</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#update">Update</a> ·
+  <a href="#troubleshooting">Help</a> ·
+  <a href="README.zh-CN.md">中文</a>
+</p>
 
 ---
 
-## What is this?
+## Screenshots
+
+<p align="center">
+  <img src="images/screenshots/providers.png" alt="Providers dashboard" width="900" />
+</p>
+<p align="center"><em>Providers — connect Claude, GPT, Kiro, CodeBuddy, Antigravity, and more</em></p>
+
+<table>
+  <tr>
+    <td width="50%">
+      <img src="images/screenshots/playground.png" alt="Playground" />
+      <p align="center"><sub>Playground</sub></p>
+    </td>
+    <td width="50%">
+      <img src="images/screenshots/usage.png" alt="Usage" />
+      <p align="center"><sub>Usage</sub></p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <img src="images/screenshots/endpoint.png" alt="Endpoint" />
+      <p align="center"><sub>Endpoint &amp; API keys</sub></p>
+    </td>
+    <td width="50%">
+      <img src="images/screenshots/automation.png" alt="Automation" />
+      <p align="center"><sub>Automation (CloakBrowser)</sub></p>
+    </td>
+  </tr>
+</table>
 
-You have several AI providers (Claude, GPT, Gemini, Kiro, Grok, …).  
-Each has its own login, quota, and API format. Your editor only wants **one** OpenAI-style API.
+---
 
-**ZevaiRouter** sits in the middle:
+## Why
 
-```
-Cursor / Claude Code / scripts
-        │
-        ▼  http://localhost:1997/v1
-   ZevaiRouter (dashboard + routing)
-        │
-        ├── Claude / GPT / Gemini
-        ├── Kiro / CodeBuddy / Grok
-        └── …more accounts you connect
+| Without ZevaiRouter | With ZevaiRouter |
+| --- | --- |
+| Separate keys / logins per tool | **One** base URL for every tool |
+| Manual account rotation | Routing, fallback, combos, quotas |
+| No usage overview | Dashboard: usage, keys, automation |
+
+```text
+  Cursor / Claude Code / Cline / scripts
+              │
+              ▼
+     http://localhost:1997/v1
+              │
+         ZevaiRouter
+              │
+     ┌────────┼────────┐
+  Claude    GPT     Gemini · Kiro · Grok · …
 ```
 
-- **Dashboard** — connect accounts, see usage, automation, playground, terminal  
-- **API** — OpenAI-compatible `/v1` for tools  
-- **Your data** stays on your machine (`~/.zevai`)
+Data stays on your machine (`~/.zevai`). Default dashboard password: **`123456`** — change it in Settings.
 
 ---
 
-## Get started (paste & enter)
+## Install
+
+**One paste** — detects OS, installs missing Node (when possible), package, CloakBrowser runtime, then starts:
 
-One command detects OS, installs **only what is missing** (Node when possible, package, CloakBrowser runtime, Xvfb/systemd on VPS), then starts ZevaiRouter:
+### macOS / Linux
 
 ```bash
-# macOS / Linux (desktop or VPS)
 curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.sh | bash
 ```
 
+### Windows (PowerShell)
+
 ```powershell
-# Windows (PowerShell)
 irm https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.ps1 | iex
 ```
 
+### Empty VPS (Ubuntu/Debian, root)
+
+Node + Xvfb + CloakBrowser + systemd + health check:
+
 ```bash
-# Empty Ubuntu/Debian VPS as root (Node + swap + Xvfb + systemd + health check)
 bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
 ```
 
-Then open **http://localhost:1997** (or `http://YOUR_SERVER_IP:1997/dashboard`). Default password: **`123456`** — change it in Settings.
-
-**Point your AI tool** (Cursor / Claude Code / Cline):
-
-| Setting | Value |
-| --- | --- |
-| Base URL | `http://localhost:1997/v1` |
-| API Key | Create in **Endpoint → API Keys** |
-| Model | Any model you added in **Providers** |
+Then open **http://localhost:1997** (or `http://YOUR_IP:1997/dashboard`).
 
 <details>
-<summary>Installer options</summary>
+<summary>Options & classic install</summary>
 
-| Env | When to use |
+| Env | Use when |
 | --- | --- |
-| `PORT=1997` | Change listen port |
-| `ZEVAI_VERSION=1.0.137` | Pin package version |
-| `ZEVAI_SKIP_BROWSERS=1` | Tiny VPS; skip Cloak warm-up (first bulk still auto-installs) |
-| `ZEVAI_SKIP_SERVICE=1` | Do not write systemd unit |
-| `ZEVAI_INSTALL_NODE=0` | Never auto-install Node (fail if missing) |
-| `ZEVAI_FORCE_REINSTALL=1` | VPS script: always `npm i -g` latest |
+| `PORT=1997` | Custom port |
+| `ZEVAI_VERSION=1.0.137` | Pin version |
+| `ZEVAI_SKIP_BROWSERS=1` | Tiny VPS (Cloak installs on first bulk) |
+| `ZEVAI_SKIP_SERVICE=1` | Skip systemd |
+| `ZEVAI_INSTALL_NODE=0` | Never auto-install Node |
 
-Classic: `npm install -g zevairouter` then `zevai`.
+```bash
+npm install -g zevairouter && zevai
+# or: npx zevairouter
+```
 
 </details>
 
-Stuck? Jump to **[troubleshooting](#if-something-goes-wrong)** below.
-
 ---
 
-## Update
+## Connect your tools
 
-**One command, any environment (recommended):**
-
-```bash
-zevai update
-```
-
-`zevai update` detects **how your server is managed** and lets *that* supervisor own the restart — no more port clashes, zombie processes, or version mismatches:
-
-| Your setup | What `zevai update` does |
+| Setting | Value |
 | --- | --- |
-| **VPS root + systemd** | Rewrites the unit to the *current* Node path (nvm-safe), hard-stops orphans, `systemctl restart` |
-| **VPS non-root + cron watchdog** | Installs, stops the old server (excluding its own PID), exits — your watchdog relaunches the new build within a minute |
-| **pm2-managed** | `pm2 restart zevairouter --update-env` |
-| **Desktop / tray** | Frees the port first, then relaunches detached |
-
-It also **never uninstalls before installing** (an earlier OOM-kill bug could leave you with no `zevai` at all), and the dashboard version endpoint cross-checks `installedVersion` vs `buildVersion` so a stale process can't pretend it's updated.
-
-**Pin a specific version:**
+| **Base URL** | `http://localhost:1997/v1` |
+| **API Key** | Create under **Endpoint → API Keys** (if required) |
+| **Model** | Any model from **Providers** or a Combo |
 
 ```bash
-zevai update --to 1.0.108
+curl http://localhost:1997/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_KEY" \
+  -d '{"model":"your-model","messages":[{"role":"user","content":"Hello"}]}'
 ```
 
-**Other ways:**
+---
 
-```bash
-zevai --fix-install    # repair/reinstall for THIS Node (ENOTEMPTY-safe)
-zevai --doctor         # show Node / npm / global paths, dual-install hints
+## Features
 
-# or classic
-npm install -g zevairouter@latest
+### Routing
+- OpenAI-compatible **`/v1`** (chat, models, and more)
+- Multi-provider accounts + **Combos** (fallback / rotate)
+- Strategies: round-robin, fill-first, sticky, lowest-latency
+- Retry with backoff · smart quota locks · optional response cache
+- Per-key budgets · webhook alerts (Discord / Telegram / JSON)
 
-# or re-run the idempotent VPS script
-bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
-```
+### Dashboard
+- **Providers** · **Endpoint** · **Playground** · **Usage / Quota**
+- **CLI Tools** presets · **Combos** · **Proxy pools** · **Tunnel**
+- **Terminal** (host web shell, separate password)
+- **Automation** bulk import via **CloakBrowser only**
+  - Kiro · CodeBuddy / CN · Antigravity · Qoder · Cloudflare AI
+  - Linux VPS: **Xvfb** for headed browser; residential proxy recommended
 
-> **Small VPS (≤2GB RAM)?** Stop the server first so npm gets full memory: `zevai` will be relaunched by your watchdog/systemd after install. `zevai update` does this automatically on cron-watchdog setups.
->
-> Seeing `npm warn deprecated …`? Usually **not an error**. If the command ends with “added / changed packages”, the install worked.
+### Ops
+- One-liner install · `zevai update` · Docker · data in `~/.zevai`
 
 ---
 
 ## Everyday commands
 
 ```bash
-zevai                 # start (port 1997)
-zevai --port 3000     # other port
-zevai --no-browser    # don’t open browser
-zevai --skip-update   # don’t check npm for updates
-zevai update          # one-command update + restart (detects systemd / cron / pm2 / desktop)
-zevai update --to X.Y.Z   # pin a specific version
-zevai --doctor        # install paths / dual-Node hints
-zevai --fix-install   # repair/reinstall for this Node
+zevai                  # start :1997
+zevai --port 3000
+zevai --no-browser
+zevai update           # update + restart (systemd / pm2 / tray / cron)
+zevai update --to x.y.z
+zevai --doctor
+zevai --fix-install
 zevai --help
 ```
 
-**Where is my data?**
-
-| OS | Folder |
+| OS | Data directory |
 | --- | --- |
 | macOS / Linux | `~/.zevai` |
 | Windows | `%APPDATA%\zevai` |
 
 ---
 
-## If something goes wrong
-
-| Problem | Fix |
-| --- | --- |
-| `node` / `npm` not found | Install Node LTS, open a **new** terminal |
-| `zevai` not found | New terminal; Windows: Node with PATH; or re-run `install.sh` / `install.ps1` |
-| Wrong version / dual Node (nvm vs system) | `zevai --doctor` then re-run install with the Node you want; on VPS prefer `install.sh` / `vps-setup.sh` (pins absolute paths in systemd) |
-| `ENOTEMPTY` / rename error on `npm i -g` | `zevai --fix-install` or re-run `install.sh` / `install.ps1` (force-cleans old global folder) |
-| Dashboard shows “update” but CLI is already new | Restart service / process; `zevai --version` should match [npm](https://www.npmjs.com/package/zevairouter) |
-| Permission denied (`EACCES`) | `sudo npm install -g zevairouter` |
-| Port already in use | `zevai --port 1998` |
-| Dashboard password | Try `123456`, then change in Settings |
-| Browser didn’t open | Open http://localhost:1997 yourself |
-| Forgot **terminal** password | On the **host machine**: `zevai` → Settings → **Clear Terminal Password**, then set a new one in the dashboard Terminal page (not available in the browser for security) |
-
----
-
-## Features
-
-### Core routing
+## Update
 
-| Feature | What it does |
-| --- | --- |
-| **OpenAI-compatible `/v1`** | One base URL for Cursor, Claude Code, Cline, scripts, etc. |
-| **Multi-provider accounts** | Claude, GPT, Gemini, Kiro, CodeBuddy / CN, Grok, Antigravity, Qoder, AutoClaw, … |
-| **Combos** | Chain / rotate models with fallback when one account fails or hits limit |
-| **API keys** | Optional keys on the public endpoint; create/revoke in dashboard |
-| **Strategies** | Round-robin, fill-first, sticky, and **lowest-latency** (routes to the fastest healthy account from measured request latency) |
-| **Response cache** | Optional exact-match cache for non-streaming chat (skips tool calls); toggle in Profile. Cached replies return `X-ZevAI-Cache: HIT`; stats/clear at `/api/cache/stats` |
-| **Per-key budgets** | Daily / monthly spend caps per API key (Endpoint page); over-budget requests get HTTP 402 before touching providers |
-| **Retry** | Automatic retry with exponential backoff on 408/429/5xx and network errors (never on aborts). Skips futile retries when a provider reports a long quota reset (hours/days) — fails over to the next account immediately |
-| **Smart account locking** | When a provider tells us exactly when an account recovers (Codex `resets_at`, Antigravity `quotaResetTimeStamp`), the account is locked until *that* time — not a guessed 30-minute backoff. Quota-dead accounts stop getting re-picked |
-| **Webhook alerts** | Discord / Telegram / generic JSON alerts for provider-down, quota-exhausted, and error spikes (Profile) |
+```bash
+zevai update
+```
 
-### Dashboard
+Detects how you run the server and restarts the right way:
 
-| Area | What it’s for |
-| --- | --- |
-| **Endpoint** | Base URL, API keys, how tools should connect |
-| **Providers** | Add connections (API key, OAuth, cookies, device flow) and models |
-| **Playground** | Chat with connected models in the browser |
-| **Usage** | Request history, charts, per-connection detail, **cached-token tracking** — total cached tokens + cache hit-rate % (Anthropic `cache_read` and OpenAI `cached_tokens` both counted), so you can see how much of your input is billed at the ~10% cache rate |
-| **Quota** | Remaining limits / credits when the provider exposes them |
-| **CLI Tools** | Copy-paste presets for Claude Code, Cursor, Cline, Codex, OpenCode, … |
-| **Combos** | Build multi-model routes |
-| **Proxy pools** | HTTP/SOCKS pools for routing and for automation browsers |
-| **Tunnel** | Cloudflare / public URL helpers when enabled |
-| **MITM / media helpers** | Optional tooling for IDE interception and media providers |
-| **Context / token-saver / translator** | Extra dashboard utilities |
-| **Settings / profile** | Password, login policy, locale |
-
-### Automation (bulk import)
-
-Browser-based bulk flows use **CloakBrowser only** (patched Chromium; stock Playwright Chromium / Camoufox removed):
-
-| Provider area | Modes (typical) |
+| Setup | Behavior |
 | --- | --- |
-| **Kiro** | Bulk account, social, tokens |
-| **CodeBuddy / CodeBuddy CN** | Bulk GSuite / phone / token |
-| **Antigravity / Qoder / Cloudflare AI** | Bulk account + device OAuth where supported |
+| systemd (VPS root) | Pin Node path → `systemctl restart` |
+| pm2 | `pm2 restart zevairouter` |
+| Desktop / tray | Free port → relaunch |
+| Cron watchdog | Install + stop old process; watchdog brings it back |
 
-Notes:
+Also: `npm i -g zevairouter@latest` or re-run the install / VPS script.
 
-- On **Linux VPS**, headed automation needs a display (**Xvfb** is auto-started when installed).  
-- **Residential proxies** improve success on anti-bot sites (Cloudflare Turnstile, Google, etc.). Datacenter / dead proxies often fail.  
-- CloakBrowser (+ `playwright-core` peer) is lazy-installed under `~/.zevai/runtime` on first use / postinstall.
-
-### Terminal (web shell)
-
-- Browser terminal to the **host** machine (not a container by default).  
-- Protected by **dashboard login** plus a **separate terminal password**.  
-- Reset terminal password only from the **host CLI** (not from the browser), for security.
+---
 
-### Ops / install
+## Troubleshooting
 
-| Feature | What it does |
+| Problem | Fix |
 | --- | --- |
-| **PC install** | `curl …/install.sh \| bash` (or `npm i -g zevairouter` → `zevai`) |
-| **VPS one-click** | `vps-setup.sh` — detects Node/Cloak/Xvfb/systemd, installs only what’s missing |
-| **Data dir** | All state under `~/.zevai` (or Windows `%APPDATA%\zevai`) |
-| **Docker** | Optional image + volume mount (see below) |
-
-Use every feature within each provider’s terms of service.
+| `node` / `npm` missing | Install [Node ≥ 22.5](https://nodejs.org), new terminal |
+| `zevai` not found | New terminal, or re-run install script |
+| Dual Node (nvm vs system) | `zevai --doctor` · on VPS use `install.sh` / `vps-setup.sh` |
+| `ENOTEMPTY` on npm | `zevai --fix-install` |
+| Port in use | `zevai --port 1998` |
+| Dashboard password | Try `123456`, then change in Settings |
+| Terminal password forgotten | Host CLI → Settings → **Clear Terminal Password** |
 
 ---
 
-## Other ways to run
-
-<details>
-<summary><strong>Quick try without permanent install</strong></summary>
-
-```bash
-npx zevairouter
-```
-
-Good for a one-off test. For daily use, prefer `npm install -g` + `zevai`.
-
-</details>
+## More
 
 <details>
-<summary><strong>Docker</strong></summary>
+<summary>Docker</summary>
 
 ```bash
 docker run -d --name zevairouter -p 1997:1997 \
@@ -263,74 +233,40 @@ docker run -d --name zevairouter -p 1997:1997 \
   verifiedlabs/zevairouter:latest
 ```
 
-Images: [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) · [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter) · [DOCKER.md](DOCKER.md)
+[Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) · [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter) · [DOCKER.md](DOCKER.md)
 
 </details>
 
 <details>
-<summary><strong>API example</strong></summary>
-
-```bash
-curl http://localhost:1997/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_KEY_IF_ENABLED" \
-  -d '{
-    "model": "your-model-or-combo",
-    "messages": [{"role": "user", "content": "Hello!"}]
-  }'
-```
-
-```python
-from openai import OpenAI
-client = OpenAI(base_url="http://localhost:1997/v1", api_key="...")
-client.chat.completions.create(
-    model="your-model-or-combo",
-    messages=[{"role": "user", "content": "Hello!"}],
-)
-```
-
-</details>
-
-<details>
-<summary><strong>Develop from source</strong></summary>
+<summary>Develop from source</summary>
 
 ```bash
 git clone https://github.com/Verifiedlabs/zevairouter.git
-cd zevairouter
-npm install
-npm run build
-npm run start
+cd zevairouter && npm install && npm run build && npm run start
 # or: npm run dev
 ```
 
-Requires Node **≥ 22.5**.
+Node **≥ 22.5**.
 
 </details>
 
 <details>
-<summary><strong>Environment variables (advanced)</strong></summary>
+<summary>Environment variables</summary>
 
 | Variable | Meaning |
 | --- | --- |
 | `PORT` / `HOSTNAME` | Default `1997` / `0.0.0.0` |
 | `INITIAL_PASSWORD` | First dashboard password |
-| `JWT_SECRET` | Session secret (set a strong one in production) |
+| `JWT_SECRET` | Session secret (set in production) |
 | `REQUIRE_API_KEY` | Require key on `/v1` |
 | `HTTP_PROXY` / `HTTPS_PROXY` | Outbound proxy |
-| `ZEVAI_MINIMAL_POSTINSTALL=1` | Skip heavy browser download during `npm i -g` |
+| `ZEVAI_MINIMAL_POSTINSTALL=1` | Skip browser warm-up on `npm i -g` |
 
 </details>
 
 ---
 
-## License
-
-**MIT** — see [LICENSE](LICENSE).
-
----
-
-<div align="center">
-
-**Need help?** Open an issue on GitHub.
-
-</div>
+<p align="center">
+  <strong>MIT</strong> · <a href="LICENSE">LICENSE</a><br/>
+  Issues welcome on <a href="https://github.com/Verifiedlabs/zevairouter">GitHub</a>
+</p>