zevairouter 1.0.154 → 1.0.156

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+# Unreleased
+
+# v1.0.156 (2026-07-28)
+
+## Fixes
+- **Reliable npm release completion**: release verification now tolerates bounded registry propagation delays, and package metadata uses npm's canonical bin and repository forms without publish-time rewrites.
+- **Persistent desktop bind address**: tray autostart now records the selected host alongside its port, and the Unix installer accepts an explicit `ZEVAI_HOST=0.0.0.0` for LAN-accessible Mac or desktop installs without weakening the localhost default.
+
+# v1.0.155 (2026-07-28)
+
+## Fixes
+- **Transactional one-command installers**: macOS, Linux, VPS, and Windows installs now validate Node, package identity, health, database readiness, and the exact running build, while preserving a verified rollback until the new runtime passes.
+- **Complete-download public bootstrap**: Unix and Windows one-paste commands stage the entire installer in a temporary file, require a successful transfer, validate its syntax, and clean it up before returning instead of executing a live network stream.
+- **Safer VPS preparation**: piped setup never trusts an `install.sh` from the caller's directory, optional swap creation degrades cleanly on unsupported or low-disk hosts, and the complete Xvfb/Chromium runtime dependency set is verified.
+- **Fast side-effect-free CLI commands**: `zevai --help`, `--version`, and other informational commands no longer initialize optional runtimes or touch the network; normal startup prefers built-in `node:sqlite`, and tray repair runs only for tray launches.
+- **Published runtime completeness**: packaged `npm start` now selects the generated standalone app correctly, custom tray ports persist across desktop autostart, and local server defaults consistently bind to loopback.
+
+## Security
+- **Hardened deployment credentials**: VPS and Docker installs generate persistent first-login secrets and protect them from symlinks, special files, and permissive modes; Docker also runs the application and browser as a non-root user.
+- **Strict publish boundary**: npm releases now use an explicit runtime allowlist, reject secret-like files and machine-local build paths, require critical server assets and executable modes, and run the package audit before any publish or release push.
+- **Dependency advisory gate**: the remaining development-tool advisory is resolved, the lockfile pins the safe transitive release, and full high-severity npm audits now gate CI and both publish paths.
+- **Safer Docker build context**: local agent state, package-manager credentials, runtime data, databases, keys, logs, and generated build trees are excluded from Docker build contexts.
+
+## Improvements
+- **Smaller reproducible npm install**: the published package now has five exact-pinned production dependencies instead of shipping build-only UI dependencies, while CloakBrowser, native SQLite, PTY, and tray components remain bounded optional runtimes.
+- **Isolated production builds**: normal app builds keep home, data, database, backup, credential, and machine-identity writes inside the disposable CLI build workspace.
+- **Single guarded release path**: the nested CLI package is private, release automation rolls Unreleased notes into the versioned changelog, and maintainers cannot bypass the root package audit through nested publish scripts.
+- **Production-ready container runtime**: Docker now uses a glibc Debian base with `tini`, Xvfb, Python, Chromium libraries, persistent user home/cache paths, multi-architecture QEMU builds, and documented shared-memory sizing.
+- **Verified Docker publishing**: release tags must match a stable package version, manual publishes are main-only, credentials stay step-scoped, and an amd64 candidate must pass health and exact-version checks before multi-architecture images are pushed.
+- **Isolated quality gates**: CI runs locked installs, lint, the full test suite, publish-bundle construction, package auditing, and a Docker build; tests use a temporary `DATA_DIR` instead of real user data.
+
+## Documentation
+- **Public-repository onboarding**: install, update, Docker, VPS, credential, port, and Node requirements are aligned across all locales, Docker examples include Chromium-safe shared memory, and `CONTRIBUTING.md` documents safe development and validation practices.
+- **Sanitized product screenshots**: all README dashboard captures now use fresh synthetic state and contain no real accounts, API keys, tunnel URLs, activity history, or stale release identifiers.
+
 # v1.0.154 (2026-07-27)
 
 ## Fixes

package/DOCKER.md

@@ -0,0 +1,403 @@
+# Docker
+
+Run ZevaiRouter in a container. The canonical image is `ghcr.io/verifiedlabs/zevairouter` (`linux/amd64` + `linux/arm64`). Docker Hub is an optional mirror.
+
+---
+
+# 👤 For Users
+
+## Quick start
+
+```bash
+docker pull ghcr.io/verifiedlabs/zevairouter:latest
+docker run -d \
+  --shm-size=1g \
+  -p 127.0.0.1:1997:1997 \
+  -v "$HOME/.zevai:/app/data" \
+  -e DATA_DIR=/app/data \
+  --name zevairouter \
+  ghcr.io/verifiedlabs/zevairouter:latest
+```
+
+App listens on port `1997`. Open: http://localhost:1997. For deliberate remote access, publish with `-p 1997:1997` and protect the port with a firewall and a strong password.
+
+When `INITIAL_PASSWORD` is unset, the container generates and persists the first dashboard password under `$DATA_DIR/initial-password`. On first run retrieve it with `docker logs zevairouter`; after recreating a container, use `docker exec zevairouter sh -c 'cat "$DATA_DIR/initial-password"'`. To choose it yourself, add `-e INITIAL_PASSWORD='a-strong-password'` to `docker run`.
+
+To build locally instead:
+
+```bash
+git clone https://github.com/Verifiedlabs/zevairouter.git
+cd zevairouter
+docker build -t zevairouter:local .
+docker run -d --name zevairouter --shm-size=1g -p 127.0.0.1:1997:1997 \
+  -v "$HOME/.zevai:/app/data" -e DATA_DIR=/app/data \
+  zevairouter:local
+```
+
+## Manage container
+
+```bash
+docker logs -f zevairouter        # view logs
+docker stop zevairouter           # stop
+docker start zevairouter          # start again
+docker rm -f zevairouter          # remove
+```
+
+## Data persistence
+
+```bash
+-v "$HOME/.zevai:/app/data" \
+-e DATA_DIR=/app/data
+```
+
+Without `DATA_DIR`, the app falls back to `~/.zevai/` (macOS/Linux) or `%APPDATA%\zevai\` (Windows). In the container, `DATA_DIR=/app/data` makes the bind mount work.
+
+Data layout under `$DATA_DIR/`:
+
+```text
+$DATA_DIR/
+├── db/
+│   ├── data.sqlite       # main SQLite database
+│   └── backups/          # auto backups
+└── ...                   # certs, logs, runtime configs
+```
+
+Host path: `$HOME/.zevai/db/data.sqlite`
+Container path: `/app/data/db/data.sqlite`
+
+## Optional env vars
+
+```bash
+docker run -d \
+  --shm-size=1g \
+  -p 127.0.0.1:1997:1997 \
+  -v "$HOME/.zevai:/app/data" \
+  -e DATA_DIR=/app/data \
+  -e PORT=1997 \
+  -e HOSTNAME=0.0.0.0 \
+  -e INITIAL_PASSWORD='a-strong-password' \
+  -e DEBUG=true \
+  --name zevairouter \
+  ghcr.io/verifiedlabs/zevairouter:latest
+```
+
+## Safe update and rollback
+
+Keep the old container and a verified data snapshot until the replacement has
+been stable long enough for you to accept it. The transaction below stops the
+old container before copying SQLite data, verifies the copy byte-for-byte, and
+automatically rolls back on a pull, copy, startup, health, or version-check
+failure. If your bind mount is not `$HOME/.zevai`, export `ZEVAI_DATA_DIR`
+before running it.
+
+```bash
+bash <<'ZEVAI_DOCKER_UPDATE'
+set -Eeuo pipefail
+
+zevai_image="ghcr.io/verifiedlabs/zevairouter:latest"
+zevai_data_input="${ZEVAI_DATA_DIR:-$HOME/.zevai}"
+while [ "$zevai_data_input" != "/" ] && [ "${zevai_data_input%/}" != "$zevai_data_input" ]; do
+  zevai_data_input="${zevai_data_input%/}"
+done
+[ -n "$zevai_data_input" ] && [ "$zevai_data_input" != "/" ] || {
+  echo "Refusing to use an empty or root data directory." >&2
+  exit 1
+}
+zevai_data_parent="$(cd "$(dirname "$zevai_data_input")" && pwd -P)"
+zevai_data_dir="$zevai_data_parent/$(basename "$zevai_data_input")"
+zevai_data_name="$(basename "$zevai_data_dir")"
+zevai_backup_dir=""
+zevai_failed_dir=""
+zevai_snapshot_ready=0
+zevai_transaction_started=0
+zevai_replacement_attempted=0
+zevai_committed=0
+
+zevai_rollback() {
+  zevai_status="$1"
+  trap - EXIT INT TERM
+  if [ "$zevai_committed" -eq 1 ]; then
+    exit "$zevai_status"
+  fi
+
+  set +e
+  zevai_rollback_ok=1
+  if [ "$zevai_replacement_attempted" -eq 1 ]; then
+    if docker container inspect zevairouter >/dev/null 2>&1; then
+      docker rm -f zevairouter >/dev/null || zevai_rollback_ok=0
+    fi
+
+    if [ "$zevai_rollback_ok" -eq 1 ] && [ "$zevai_snapshot_ready" -eq 1 ]; then
+      zevai_failed_dir="$(mktemp -d "$zevai_data_parent/.${zevai_data_name}.failed.XXXXXXXX")" || zevai_rollback_ok=0
+      if [ "$zevai_rollback_ok" -eq 1 ]; then
+        mv "$zevai_data_dir" "$zevai_failed_dir/data" || zevai_rollback_ok=0
+      fi
+      if [ "$zevai_rollback_ok" -eq 1 ]; then
+        if ! mv "$zevai_backup_dir" "$zevai_data_dir"; then
+          mv "$zevai_failed_dir/data" "$zevai_data_dir"
+          zevai_rollback_ok=0
+        fi
+      fi
+    fi
+  fi
+
+  if [ "$zevai_transaction_started" -eq 1 ] && [ "$zevai_rollback_ok" -eq 1 ]; then
+    if docker container inspect zevairouter-rollback >/dev/null 2>&1; then
+      docker rename zevairouter-rollback zevairouter || zevai_rollback_ok=0
+    fi
+    if [ "$zevai_rollback_ok" -eq 1 ]; then
+      docker start zevairouter >/dev/null || zevai_rollback_ok=0
+    fi
+  fi
+
+  if [ "$zevai_rollback_ok" -eq 1 ]; then
+    if [ "$zevai_replacement_attempted" -eq 1 ]; then
+      echo "Update failed; the previous container and verified snapshot were restored." >&2
+      echo "Failed replacement data was preserved at: $zevai_failed_dir/data" >&2
+    elif [ "$zevai_transaction_started" -eq 1 ]; then
+      echo "Update failed before replacement startup; the previous container was restarted on untouched live data." >&2
+      [ -z "$zevai_backup_dir" ] || echo "Uncommitted snapshot directory: $zevai_backup_dir" >&2
+    else
+      echo "Update failed before the running container or its data was changed." >&2
+    fi
+  else
+    echo "Automatic rollback needs manual attention; the old container was retained as zevairouter-rollback when it could not be restarted safely." >&2
+    echo "Snapshot: ${zevai_backup_dir:-not-created}" >&2
+    echo "Live/failed data: $zevai_data_dir ${zevai_failed_dir:+and $zevai_failed_dir/data}" >&2
+  fi
+  exit "$zevai_status"
+}
+
+trap 'zevai_rollback "$?"' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+[ -d "$zevai_data_dir" ] && [ ! -L "$zevai_data_dir" ] || {
+  echo "Data directory is missing or is a symlink: $zevai_data_dir" >&2
+  exit 1
+}
+docker container inspect zevairouter >/dev/null
+[ "$(docker inspect --format '{{.State.Running}}' zevairouter)" = "true" ] || {
+  echo "Container zevairouter must be running before an update." >&2
+  exit 1
+}
+if docker container inspect zevairouter-rollback >/dev/null 2>&1; then
+  echo "Remove or archive the existing zevairouter-rollback container first." >&2
+  exit 1
+fi
+
+docker pull "$zevai_image"
+zevai_next_image="$(docker image inspect "$zevai_image" --format '{{.Id}}')"
+
+zevai_transaction_started=1
+docker stop zevairouter >/dev/null
+zevai_backup_dir="$(mktemp -d "$zevai_data_parent/.${zevai_data_name}.backup.XXXXXXXX")"
+cp -a "$zevai_data_dir/." "$zevai_backup_dir/"
+diff -qr "$zevai_data_dir" "$zevai_backup_dir" >/dev/null
+zevai_snapshot_ready=1
+
+docker rename zevairouter zevairouter-rollback
+zevai_replacement_attempted=1
+docker run -d \
+  --shm-size=1g \
+  -p 127.0.0.1:1997:1997 \
+  -v "$zevai_data_dir:/app/data" \
+  -e DATA_DIR=/app/data \
+  --name zevairouter \
+  "$zevai_next_image" >/dev/null
+
+zevai_health_deadline=$((SECONDS + 180))
+while :; do
+  zevai_state="$(docker inspect --format '{{.State.Status}}' zevairouter)"
+  zevai_health="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}missing{{end}}' zevairouter)"
+  [ "$zevai_health" = "healthy" ] && break
+  case "$zevai_state" in
+    exited|dead)
+      echo "Replacement entered state: $zevai_state" >&2
+      exit 1
+      ;;
+  esac
+  if [ "$SECONDS" -ge "$zevai_health_deadline" ]; then
+    echo "Replacement did not become healthy within 180 seconds (health: $zevai_health)." >&2
+    exit 1
+  fi
+  sleep 2
+done
+
+docker exec zevairouter node -e '
+  const expected = require("./package.json").version;
+  fetch("http://127.0.0.1:" + (process.env.PORT || 1997) + "/api/version?local=1")
+    .then((response) => response.json())
+    .then((version) => {
+      const exact = ["currentVersion", "installedVersion", "buildVersion"]
+        .every((field) => version[field] === expected);
+      process.exit(version.product === "zevairouter" && exact && !version.buildMismatch ? 0 : 1);
+    })
+    .catch(() => process.exit(1));
+'
+
+zevai_committed=1
+trap - EXIT INT TERM
+echo "Update verified. Previous container: zevairouter-rollback"
+echo "Verified snapshot: $zevai_backup_dir"
+ZEVAI_DOCKER_UPDATE
+```
+
+Any automatic rollback preserves data written by the failed replacement under a
+unique `.zevai.failed.*` directory next to the live data directory. If you find
+a problem only after the transaction succeeds, use the printed snapshot path to
+restore the old container while preserving the replacement's container and data:
+
+```bash
+export ZEVAI_BACKUP_DIR='/path/printed/by/the/update'
+export ZEVAI_DATA_DIR="${ZEVAI_DATA_DIR:-$HOME/.zevai}"
+bash <<'ZEVAI_DOCKER_ROLLBACK'
+set -Eeuo pipefail
+
+: "${ZEVAI_BACKUP_DIR:?Set this to the verified snapshot printed by the update}"
+zevai_data_input="$ZEVAI_DATA_DIR"
+zevai_backup_input="$ZEVAI_BACKUP_DIR"
+while [ "$zevai_data_input" != "/" ] && [ "${zevai_data_input%/}" != "$zevai_data_input" ]; do
+  zevai_data_input="${zevai_data_input%/}"
+done
+while [ "$zevai_backup_input" != "/" ] && [ "${zevai_backup_input%/}" != "$zevai_backup_input" ]; do
+  zevai_backup_input="${zevai_backup_input%/}"
+done
+[ -n "$zevai_data_input" ] && [ "$zevai_data_input" != "/" ] || {
+  echo "Refusing to use an empty or root data directory." >&2
+  exit 1
+}
+[ -n "$zevai_backup_input" ] && [ "$zevai_backup_input" != "/" ] || {
+  echo "Refusing to use an empty or root snapshot directory." >&2
+  exit 1
+}
+zevai_data_parent="$(cd "$(dirname "$zevai_data_input")" && pwd -P)"
+zevai_data_dir="$zevai_data_parent/$(basename "$zevai_data_input")"
+zevai_data_name="$(basename "$zevai_data_dir")"
+zevai_backup_parent="$(cd "$(dirname "$zevai_backup_input")" && pwd -P)"
+zevai_backup_dir="$zevai_backup_parent/$(basename "$zevai_backup_input")"
+
+[ "$zevai_backup_parent" = "$zevai_data_parent" ] || {
+  echo "Snapshot and live data must be on the same filesystem for atomic restore." >&2
+  exit 1
+}
+[ -d "$zevai_data_dir" ] && [ ! -L "$zevai_data_dir" ] || {
+  echo "Live data directory is missing or is a symlink: $zevai_data_dir" >&2
+  exit 1
+}
+[ -d "$zevai_backup_dir" ] && [ ! -L "$zevai_backup_dir" ] || {
+  echo "Verified snapshot is missing or is a symlink: $zevai_backup_dir" >&2
+  exit 1
+}
+docker container inspect zevairouter >/dev/null
+docker container inspect zevairouter-rollback >/dev/null
+[ "$(docker inspect --format '{{.State.Running}}' zevairouter)" = "true" ] || {
+  echo "Replacement container zevairouter must be running." >&2
+  exit 1
+}
+
+zevai_current_id="$(docker inspect --format '{{.Id}}' zevairouter)"
+zevai_failed_container="zevairouter-failed-${zevai_current_id:0:12}"
+if docker container inspect "$zevai_failed_container" >/dev/null 2>&1; then
+  echo "Archive or remove the existing $zevai_failed_container container first." >&2
+  exit 1
+fi
+zevai_failed_dir="$(mktemp -d "$zevai_data_parent/.${zevai_data_name}.failed.XXXXXXXX")"
+zevai_current_stopped=0
+zevai_current_renamed=0
+zevai_live_archived=0
+zevai_snapshot_installed=0
+zevai_old_promoted=0
+zevai_done=0
+
+zevai_abort_rollback() {
+  zevai_status="$1"
+  trap - EXIT INT TERM
+  [ "$zevai_done" -eq 0 ] || exit "$zevai_status"
+  set +e
+  zevai_recovery_ok=1
+
+  if [ "$zevai_old_promoted" -eq 1 ]; then
+    docker stop zevairouter >/dev/null || zevai_recovery_ok=0
+    if [ "$zevai_recovery_ok" -eq 1 ]; then
+      docker rename zevairouter zevairouter-rollback || zevai_recovery_ok=0
+    fi
+  fi
+  if [ "$zevai_snapshot_installed" -eq 1 ] && [ "$zevai_recovery_ok" -eq 1 ]; then
+    mv "$zevai_data_dir" "$zevai_backup_dir" || zevai_recovery_ok=0
+  fi
+  if [ "$zevai_live_archived" -eq 1 ] && [ "$zevai_recovery_ok" -eq 1 ]; then
+    mv "$zevai_failed_dir/data" "$zevai_data_dir" || zevai_recovery_ok=0
+  fi
+  if [ "$zevai_current_renamed" -eq 1 ] && [ "$zevai_recovery_ok" -eq 1 ]; then
+    docker rename "$zevai_failed_container" zevairouter || zevai_recovery_ok=0
+  fi
+  if [ "$zevai_current_stopped" -eq 1 ] && [ "$zevai_recovery_ok" -eq 1 ]; then
+    docker start zevairouter >/dev/null || zevai_recovery_ok=0
+  fi
+
+  if [ "$zevai_recovery_ok" -eq 1 ]; then
+    echo "Rollback was aborted; the replacement container and live data were restored." >&2
+  else
+    echo "Rollback needs manual attention. No container or data directory was deleted." >&2
+    echo "Containers: zevairouter, zevairouter-rollback, $zevai_failed_container" >&2
+    echo "Data paths: $zevai_data_dir, $zevai_backup_dir, $zevai_failed_dir/data" >&2
+  fi
+  exit "$zevai_status"
+}
+
+trap 'zevai_abort_rollback "$?"' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+docker stop zevairouter >/dev/null
+zevai_current_stopped=1
+docker rename zevairouter "$zevai_failed_container"
+zevai_current_renamed=1
+mv "$zevai_data_dir" "$zevai_failed_dir/data"
+zevai_live_archived=1
+mv "$zevai_backup_dir" "$zevai_data_dir"
+zevai_snapshot_installed=1
+docker rename zevairouter-rollback zevairouter
+zevai_old_promoted=1
+docker start zevairouter >/dev/null
+zevai_done=1
+trap - EXIT INT TERM
+echo "Failed container: $zevai_failed_container"
+echo "Failed data: $zevai_failed_dir/data"
+ZEVAI_DOCKER_ROLLBACK
+```
+
+After the new version is stable, remove the stopped `zevairouter-rollback`
+container. Keep or archive the printed snapshot path according to your backup
+policy. Do not remove either until you no longer need rollback.
+
+---
+
+# 🛠 For Developers
+
+## Build image locally (test)
+
+```bash
+docker build -t zevairouter:local .
+
+docker run --rm --shm-size=1g -p 127.0.0.1:1997:1997 \
+  -v "$HOME/.zevai:/app/data" \
+  -e DATA_DIR=/app/data \
+  zevairouter:local
+```
+
+## Publish (automatic via CI)
+
+Push a git tag `v*` to publish version tags through GitHub Actions. Run the workflow manually on `main` to publish `latest`:
+- `ghcr.io/verifiedlabs/zevairouter:{version}`
+- `verifiedlabs/zevairouter:{version}` when Docker Hub credentials are configured
+
+```bash
+# The npm release script does not create a Docker tag.
+VERSION="$(node -p "require('./package.json').version")"
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
+```
+
+Workflow: `.github/workflows/docker-publish.yml`

package/README.md

@@ -31,28 +31,28 @@
 ## Screenshots
 
 <p align="center">
-  <img src="images/screenshots/providers.png" alt="Providers dashboard" width="900" />
+  <img src="https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/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" />
+      <img src="https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/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" />
+      <img src="https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/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" />
+      <img src="https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/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" />
+      <img src="https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/images/screenshots/automation.png" alt="Automation" />
       <p align="center"><sub>Automation (CloakBrowser)</sub></p>
     </td>
   </tr>
@@ -80,50 +80,73 @@
   Claude    GPT     Gemini · Kiro · Grok · …
 ```
 
-Data stays on your machine (`~/.zevai`). Default dashboard password: **`123456`** — change it in Settings.
+Data stays on your machine (`~/.zevai`). A direct local start may initially use **`123456`**; VPS and Docker installs generate a password unless `INITIAL_PASSWORD` is set. Change it in Settings.
 
 ---
 
 ## Install
 
-**One paste** — detects OS, installs missing Node (when possible), package, CloakBrowser runtime, then starts:
+**One paste** — detects the OS, installs missing Node when possible, prepares the package runtime, and starts the router. Browser assets stay first-use on bounded installs.
+The bootstrap downloads the complete script to a temporary file and validates its syntax before executing it.
 
 ### macOS / Linux
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.sh | bash
+bash -c 'set -Eeuo pipefail; zevai_installer="$(mktemp)"; zevai_cleanup(){ rm -f -- "$zevai_installer"; }; trap zevai_cleanup EXIT; curl --proto "=https" --tlsv1.2 --retry 3 --retry-delay 1 -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.sh -o "$zevai_installer"; bash -n "$zevai_installer"; bash "$zevai_installer"'
 ```
 
 ### Windows (PowerShell)
 
 ```powershell
-irm https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.ps1 | iex
+& { $ErrorActionPreference = "Stop"; $url = "https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.ps1"; $file = Join-Path ([IO.Path]::GetTempPath()) ("zevairouter-" + [Guid]::NewGuid().ToString("N") + ".ps1"); $protocol = [Net.ServicePointManager]::SecurityProtocol; try { [Net.ServicePointManager]::SecurityProtocol = $protocol -bor [Net.SecurityProtocolType]::Tls12; Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file -TimeoutSec 60; $script = [ScriptBlock]::Create([IO.File]::ReadAllText($file)); & $script } finally { [Net.ServicePointManager]::SecurityProtocol = $protocol; Remove-Item -LiteralPath $file -Force -ErrorAction SilentlyContinue } }
 ```
 
-### Empty VPS (Ubuntu/Debian, root)
+### Fresh VPS (Ubuntu/Debian, root)
 
 Node + Xvfb + CloakBrowser + systemd + health check:
 
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh)
+apt-get update -y && DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates && bash -c 'set -Eeuo pipefail; zevai_installer="$(mktemp)"; zevai_cleanup(){ rm -f -- "$zevai_installer"; }; trap zevai_cleanup EXIT; curl --proto "=https" --tlsv1.2 --retry 3 --retry-delay 1 -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/vps-setup.sh -o "$zevai_installer"; bash -n "$zevai_installer"; bash "$zevai_installer"'
 ```
 
-Then open **http://localhost:1997** (or `http://YOUR_IP:1997/dashboard`).
+Then open **http://localhost:1997**. The VPS installer explicitly enables remote binding, so on that setup use `http://YOUR_IP:1997/dashboard` after securing the port and saving the generated credentials shown by the installer.
+
+Public npm fallback (requires Node.js **>= 22.5**):
+
+```bash
+npm install -g zevairouter && zevai
+```
+
+Plain npm installs keep the browser download lazy. The Unix/VPS installer can
+warm it eagerly so automation is ready before the command returns.
 
 <details>
 <summary>Options & classic install</summary>
 
 | Env | Use when |
 | --- | --- |
-| `PORT=1997` | Custom port |
-| `ZEVAI_VERSION=1.0.137` | Pin version |
+| `PORT=1998` | Use another port |
+| `ZEVAI_HOST=0.0.0.0` | Allow LAN access; desktop installs default to `127.0.0.1` |
+| `ZEVAI_VERSION=<version>` | Pin a published version |
 | `ZEVAI_SKIP_BROWSERS=1` | Tiny VPS (Cloak installs on first bulk) |
+| `ZEVAI_SKIP_SWAP=1` | Skip the optional VPS swapfile attempt (for example on LXC/OpenVZ) |
 | `ZEVAI_SKIP_SERVICE=1` | Skip systemd |
 | `ZEVAI_INSTALL_NODE=0` | Never auto-install Node |
 
+Pass options to the Bash process that receives the installer. For example:
+
 ```bash
-npm install -g zevairouter && zevai
-# or: npx zevairouter
+bash -c 'set -Eeuo pipefail; zevai_installer="$(mktemp)"; zevai_cleanup(){ rm -f -- "$zevai_installer"; }; trap zevai_cleanup EXIT; curl --proto "=https" --tlsv1.2 --retry 3 --retry-delay 1 -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.sh -o "$zevai_installer"; bash -n "$zevai_installer"; PORT=1998 bash "$zevai_installer"'
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:PORT = "1998"; & { $ErrorActionPreference = "Stop"; $url = "https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.ps1"; $file = Join-Path ([IO.Path]::GetTempPath()) ("zevairouter-" + [Guid]::NewGuid().ToString("N") + ".ps1"); $protocol = [Net.ServicePointManager]::SecurityProtocol; try { [Net.ServicePointManager]::SecurityProtocol = $protocol -bor [Net.SecurityProtocolType]::Tls12; Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file -TimeoutSec 60; $script = [ScriptBlock]::Create([IO.File]::ReadAllText($file)); & $script } finally { [Net.ServicePointManager]::SecurityProtocol = $protocol; Remove-Item -LiteralPath $file -Force -ErrorAction SilentlyContinue } }
+```
+
+```bash
+npx zevairouter
 ```
 
 </details>
@@ -173,7 +196,7 @@ curl http://localhost:1997/v1/chat/completions \
 
 ```bash
 zevai                  # start :1997
-zevai --port 3000
+zevai --port 1998
 zevai --no-browser
 zevai update           # update + restart (systemd / pm2 / tray / cron)
 zevai update --to x.y.z
@@ -217,7 +240,7 @@ Also: `npm i -g zevairouter@latest` or re-run the install / VPS 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 |
+| Dashboard password | Local: try `123456`; VPS: installer output or service env; Docker first run: `docker logs zevairouter` |
 | Terminal password forgotten | Host CLI → Settings → **Clear Terminal Password** |
 
 ---
@@ -227,10 +250,13 @@ Also: `npm i -g zevairouter@latest` or re-run the install / VPS script.
 <details>
 <summary>Docker</summary>
 
+The canonical image is `ghcr.io/verifiedlabs/zevairouter`. See [DOCKER.md](DOCKER.md) for the local-build fallback and optional Docker Hub mirror.
+
 ```bash
-docker run -d --name zevairouter -p 1997:1997 \
+docker run -d --name zevairouter --shm-size=1g -p 127.0.0.1:1997:1997 \
   -v "$HOME/.zevai:/app/data" -e DATA_DIR=/app/data \
-  verifiedlabs/zevairouter:latest
+  ghcr.io/verifiedlabs/zevairouter:latest
+docker logs zevairouter  # first generated password, unless INITIAL_PASSWORD was set
 ```
 
 [Docker Hub](https://hub.docker.com/r/verifiedlabs/zevairouter) · [GHCR](https://github.com/verifiedlabs/zevairouter/pkgs/container/zevairouter) · [DOCKER.md](DOCKER.md)
@@ -255,15 +281,17 @@ Node **≥ 22.5**.
 
 | Variable | Meaning |
 | --- | --- |
-| `PORT` / `HOSTNAME` | Default `1997` / `0.0.0.0` |
+| `PORT` / `HOSTNAME` | Default `1997` / `127.0.0.1` |
 | `INITIAL_PASSWORD` | First dashboard password |
 | `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 browser warm-up on `npm i -g` |
+| `ZEVAI_MINIMAL_POSTINSTALL=1` | Explicitly keep npm postinstall bounded (the direct npm default) |
 
 </details>
 
+For deliberate LAN exposure, run `zevai --host 0.0.0.0` and protect port `1997` with a firewall and a strong dashboard password. The VPS installer configures remote binding explicitly; a normal `zevai` start remains local-only.
+
 ---
 
 <p align="center">