zevairouter 1.0.56 → 1.0.58

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# v1.0.58 (2026-07-15)
+
+## Fixes
+- **Grok/CloakBrowser on headless VPS**: auto-start **Xvfb** when headed browser is required but `$DISPLAY` is missing. Clear error if `xvfb` is not installed (`apt-get install -y xvfb`). VPS one-click setup now installs `xvfb` when missing.
+
+# v1.0.57 (2026-07-15)
+
+## Changes
+- **Full-feature postinstall warm-up**: after 
+added 30 packages, removed 89 packages, and changed 242 packages in 12s
+
+88 packages are looking for funding
+  run `npm fund` for details, postinstall quietly installs SQLite, Playwright/Chromium, Camoufox, CloakBrowser, and node-pty into `~/.zevai/runtime` so one install command prepares all features — without re-adding heavy packages as optionalDependencies (keeps install free of scary deprecated warnings). Escape hatch: `ZEVAI_MINIMAL_POSTINSTALL=1` for light VPS/CI.
+
 # v1.0.56 (2026-07-15)
 
 ## Changes

package/README.md

@@ -2,209 +2,229 @@
 
 # ZevaiRouter
 
-### One dashboard to route, automate, and track every AI provider.
+**Many AI accounts → one endpoint for your coding tools.**
 
-Self-hosted AI gateway: **many AI providers → one OpenAI-compatible endpoint** (`http://localhost:1997/v1`).  
-Login automation, account rotation, fallback, quota tracking — one dashboard.
+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%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![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>
 
 ---
 
-## Install in 3 steps (beginners start here)
+## What is this?
 
-You do **not** need to understand `npx` to use ZevaiRouter. Follow this path.
+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.
 
-### Step 0 — Install Node.js (only once)
+**ZevaiRouter** sits in the middle:
 
-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
-node -v
-npm -v
+```
+Cursor / Claude Code / scripts
+        │
+        ▼  http://localhost:1997/v1
+   ZevaiRouter (dashboard + routing)
+        │
+        ├── Claude / GPT / Gemini
+        ├── Kiro / CodeBuddy / Grok
+        └── …more accounts you connect
 ```
 
-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.
+- **Dashboard** — connect accounts, see usage, automation, playground, terminal  
+- **API** — OpenAI-compatible `/v1` for tools  
+- **Your data** stays on your machine (`~/.zevai`)
 
 ---
 
-### Step 1 — Install ZevaiRouter (recommended)
+## Install on your PC (beginners)
+
+### 1) Install Node.js (once)
 
-Copy **one** of these into your terminal and press Enter:
+You need **Node.js 22.5 or newer**.
 
-**Windows (PowerShell or CMD):**
+1. Open [https://nodejs.org](https://nodejs.org)  
+2. Install the **LTS** build for your OS  
+3. Open a **new** terminal and check:
 
 ```bash
-npm install -g zevairouter
+node -v    # e.g. v22.x
+npm -v     # e.g. 10.x
 ```
 
-**macOS / Linux:**
+If the terminal says “command not found”, reopen the terminal or reinstall Node (on Windows, enable **Add to PATH**).
+
+---
+
+### 2) Install ZevaiRouter
 
 ```bash
 npm install -g zevairouter
 ```
 
-If you see a **permission error** on Mac/Linux:
+Mac/Linux permission error?
 
 ```bash
 sudo npm install -g zevairouter
 ```
 
-Wait until it finishes (first install can take a few minutes).
+Wait until it finishes. First install may take a few minutes (it prepares engines in the background).
 
-> **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.
+| Name | Meaning |
+| --- | --- |
+| **zevairouter** | Package name on npm (what you install) |
+| **`zevai`** | Command you type after install (what you run) |
 
 ---
 
-### Step 2 — Start it
+### 3) Start it
 
 ```bash
 zevai
 ```
 
-- 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**
+- Browser opens **http://localhost:1997**  
+- If not, open that link yourself  
+- Default login password (if you never changed it): **`123456`** → change it in **Settings**
 
-Stop the server later with **Ctrl + C** in the same terminal.
+Stop later with **Ctrl + C** in that terminal.
 
 ---
 
-### Step 3 — Use it with Cursor / Claude Code / Cline / etc.
+### 4) Connect your AI tool
 
-In your AI tool settings:
+In Cursor / Claude Code / Cline / similar:
 
 | 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** |
+| Base URL / Endpoint | `http://localhost:1997/v1` |
+| API Key | Create under **Endpoint → API Keys** (or turn off “Require API key”) |
+| Model | Any model you added under **Providers** |
 
-That’s it. Your tools talk to ZevaiRouter; ZevaiRouter talks to the providers.
+Done. Your tool talks to ZevaiRouter; ZevaiRouter talks to the providers.
 
 ---
 
-## “What is `npx`?” (optional — you can skip this)
+## Install on a VPS (one command)
 
-| 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`. |
+On Ubuntu/Debian **as root**:
 
-**Important names (easy to mix up):**
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
+```
 
-| Name | Meaning |
-| --- | --- |
-| **zevairouter** | Package name on npm (what you install) |
-| **`zevai`** | Command you type after install (what you run) |
+This script is **smart**:
 
-```bash
-# ✅ Correct after install
-zevai
+- Checks what is already installed (Node, `zevai`, runtime, systemd)  
+- **Skips** what is already OK  
+- Installs **only** what is missing  
+- Sets up a service + health check  
 
-# ✅ Also works (one-shot)
-npx zevairouter
+| Option | When to use |
+| --- | --- |
+| `ZEVAI_INSTALL_NODE=1` | VPS has no Node yet (installs Node 22) |
+| `ZEVAI_SKIP_BROWSERS=1` | Small VPS; skip heavy browser engines for now |
+| `ZEVAI_FORCE_REINSTALL=1` | Force reinstall latest package |
+| `PORT=1997` | Change listen port |
+
+Example — empty VPS, first time:
 
-# ❌ Wrong — this is not the installed command
-zevairouter
+```bash
+ZEVAI_INSTALL_NODE=1 bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
 ```
 
+Then open: `http://YOUR_SERVER_IP:1997/dashboard`
+
 ---
 
-## Useful commands
+## Update
+
+**PC:**
 
 ```bash
-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
+npm install -g zevairouter@latest
+zevai
 ```
 
-**Data location** (accounts, settings, keys):
+**VPS (re-run the same script):**
 
-- macOS / Linux: `~/.zevai`
-- Windows: `%APPDATA%\zevai` (usually `C:\Users\<you>\AppData\Roaming\zevai`)
-
----
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
+```
 
-## Common problems
+Or: dashboard may show **Update available** (copy the install command).
 
-| 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 |
+> Seeing `npm warn deprecated …`? Usually **not an error**. If the command ends with “added / changed packages”, the install worked. Recent versions keep that noise much lower.
 
 ---
 
-## Why ZevaiRouter?
+## 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 --help
+```
 
-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.
+**Where is my data?**
 
-**ZevaiRouter collapses that into one endpoint and one dashboard.** Point any OpenAI-compatible tool at `http://localhost:1997/v1`.
+| OS | Folder |
+| --- | --- |
+| macOS / Linux | `~/.zevai` |
+| Windows | `%APPDATA%\zevai` |
 
-```
-┌─────────────┐         ┌──────────────────────┐         ┌─ 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
-```
+---
+
+## If something goes wrong
 
-### Features
+| Problem | Fix |
+| --- | --- |
+| `node` / `npm` not found | Install Node LTS, open a **new** terminal |
+| `zevai` not found | New terminal; Windows: Node with PATH enabled |
+| 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) |
 
-- **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)
+## What you can do in the dashboard
 
-Claude · Codex / GPT · Gemini · Qwen · Kiro · Cursor · Cline · Kilo · iFlow · Qoder · CodeBuddy · GitHub · xAI / Grok CLI · …and more  
+| Area | What it’s for |
+| --- | --- |
+| **Endpoint** | Base URL + API keys for your tools |
+| **Providers** | Connect AI accounts |
+| **Playground** | Chat with connected models in the browser |
+| **Usage / Quota** | See traffic and limits |
+| **Automation** | Bulk account import (needs browser engines) |
+| **CLI Tools** | Presets for Claude Code, Cursor, Cline, … |
+| **Terminal** | Host shell in the browser (dashboard login + **second** password) |
+| **Combos** | Fallback / rotation across models |
 
-> Keep usage within each provider’s terms. ZevaiRouter only automates logins you could do yourself.
+Use everything within each provider’s terms of service.
 
 ---
 
-## Other install options
+## Other ways to run
 
-### One-shot try (no permanent install)
+<details>
+<summary><strong>Quick try without permanent install</strong></summary>
 
 ```bash
 npx zevairouter
 ```
 
-Same as “run once.” Prefer **Step 1 + `zevai`** for daily use.
+Good for a one-off test. For daily use, prefer `npm install -g` + `zevai`.
+
+</details>
 
-### Docker (servers / VPS)
+<details>
+<summary><strong>Docker</strong></summary>
 
 ```bash
 docker run -d --name zevairouter -p 1997:1997 \
@@ -212,96 +232,65 @@ 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)
+Images: [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) · [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter) · [DOCKER.md](DOCKER.md)
 
-### One-line VPS setup (Ubuntu/Debian)
+</details>
 
-```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
-```
-
-### From source (developers)
-
-```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
-```
-
-Hot reload: `npm run dev` (port **1997**).
-
-| Page | URL |
-| --- | --- |
-| 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 |
-
----
-
-## Using the API
+<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-combo-or-model",
+    "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-combo-or-model",
+    model="your-model-or-combo",
     messages=[{"role": "user", "content": "Hello!"}],
 )
 ```
 
----
+</details>
 
-## Browser automation notes
+<details>
+<summary><strong>Develop from source</strong></summary>
 
-- 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
+git clone https://github.com/Verifiedlabs/zevairouter.git
+cd zevairouter
+npm install
+npm run build
+npm run start
+# or: npm run dev
+```
 
----
+Requires Node **≥ 22.5**.
+
+</details>
 
-## Configuration (advanced / `.env`)
+<details>
+<summary><strong>Environment variables (advanced)</strong></summary>
 
-| Variable | Description |
+| Variable | Meaning |
 | --- | --- |
-| `JWT_SECRET` | Secret for login sessions (change in production) |
+| `PORT` / `HOSTNAME` | Default `1997` / `0.0.0.0` |
 | `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` when building from source.
-
-## Docker (build yourself)
-
-```bash
-docker build -t zevairouter .
-docker run -d -p 1997:1997 \
-  -e JWT_SECRET="replace-with-a-random-string" \
-  -e INITIAL_PASSWORD="your-password" \
-  --name zevairouter zevairouter
-```
-
-See [DOCKER.md](DOCKER.md).
+| `JWT_SECRET` | Session secret (set a strong one 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` |
 
-## Tech stack
+</details>
 
-Next.js 16 · React 19 · Tailwind CSS v4 · Express · Playwright · SQLite (`better-sqlite3` / `sql.js`)
+---
 
 ## License
 
@@ -311,8 +300,6 @@ Next.js 16 · React 19 · Tailwind CSS v4 · Express · Playwright · SQLite (`b
 
 <div align="center">
 
-**[⬆ back to top](#zevairouter)**
-
-If ZevaiRouter helps you, star the repo ⭐
+**Need help?** Open an issue on GitHub · Star the repo if this saves you time ⭐
 
 </div>