levix-bot 2.0.1 → 2.1.0

package/README.md

@@ -14,8 +14,13 @@ levix
 The npm package is named `levix-bot`; the installed CLI command stays `levix`.
 
 On a desktop that opens the panel in your browser by itself. Pick a password,
-scan the QR, done — see [SETUP.md](SETUP.md) for the longer version, Docker,
-and running it as a service.
+go to **Connection**, press **Start session** and scan the QR — see
+[SETUP.md](SETUP.md) for the longer version, Docker, and running it as a
+service.
+
+Starting Levix does not connect it to WhatsApp. The panel, the database and the
+commands come up on their own, and the WhatsApp session is started from the
+Connection screen when you want it.
 
 ```
   levix                    start Levix with the web panel
@@ -41,7 +46,9 @@ warnings with auto-kick, rules and notes, plus the usual `!group kick`,
 **An AI agent, not a chat box** — `!gemini` can search the web, open a page and
 read it, save something to its long-term memory and hand out bot roles, across
 several tool rounds, narrating the whole run inside a single message it keeps
-editing. Its personality is a Markdown file you can edit from the panel.
+editing. Gemini's own Google Search is available to it too, so questions about
+current things get grounded answers with their sources listed. Its personality
+is a Markdown file you can edit from the panel.
 
 **Long-term memory** — "remember that…" writes to `memory/global.md` or a
 per-chat file. Plain Markdown, hand-editable, injected into every prompt.
@@ -49,9 +56,20 @@ per-chat file. Plain Markdown, hand-editable, injected into every prompt.
 **Scheduled messages** — one-off (`!schedule`) or recurring (`!autoschedule`),
 stored in the database and listed in the panel.
 
+**Optional proxy** — Settings → WhatsApp proxy routes the WhatsApp connection
+through an HTTP, HTTPS or SOCKS5 proxy, including the media it sends and
+receives. Nothing else changes: the control panel and the AI still connect
+directly.
+
+**A connection you control** — the panel starts, stops and unlinks the
+WhatsApp session, and shows what it is actually doing: waiting for a scan,
+connected, reconnecting (5s, 10s, 15s, 20s, 25s), or stopped. Reconnects happen
+in the bot whether or not a browser is open, and a WhatsApp connection that will
+not come back never takes the panel down with it.
+
 **A panel you can also do without** — `levix headless` runs the bot with no
-Express, no socket.io and no port open at all; an unpaired install prints its
-QR straight to the terminal.
+Express, no socket.io and no port open at all; having no screen to press Start
+on, it connects by itself and prints its QR straight to the terminal.
 
 **A domain, without a takeover** — `levix domain bot.example.com` looks at what
 the server already runs and works with it: it adds one nginx or Caddy site and

package/SETUP.md

@@ -40,10 +40,15 @@ The terminal prints something like:
   Data:  ~/.levix
 
   First run — that link asks you to pick a password.
-  Opening it from another machine also needs this code: 43CB5162
+  Opening it from another machine also needs this code:
+
+  [Setup] Setup code: 43CB5162
 
   Opening Levix in your browser...
 
+  Not linked to WhatsApp yet? Open the panel, go to Connection and
+  press Start session.
+
   Press Ctrl+C to stop.
 ```
 
@@ -51,8 +56,9 @@ The terminal prints something like:
 2. Choose a password. (Opening the page from a *different* machine also asks
    for the setup code above — that's what stops a stranger from claiming your
    bot before you do.)
-3. You land on the control panel. Go to **Connection** and scan the QR with
-   WhatsApp → Settings → Linked devices → Link a device.
+3. You land on the control panel. Go to **Connection**, press **Start session**,
+   and scan the QR with WhatsApp → Settings → Linked devices → Link a device.
+   Levix does not connect to WhatsApp until you ask it to.
 4. Send `!ping` in any chat. The bot answers.
 
 Levix only opens a browser when there is one to open: over SSH, under systemd,
@@ -76,7 +82,7 @@ docker compose up -d
 Then open <http://localhost:3001>. The setup code is in the logs:
 
 ```bash
-docker compose logs levix | grep -A3 "Setup code"
+docker compose logs levix | grep -F '[Setup] Setup code:' | tail -1
 ```
 
 Everything the bot owns lives in the `levix-data` volume.
@@ -166,6 +172,13 @@ Closing the terminal stops the bot. Pick one:
 curl -fsSL https://levix.leviro.net/install.sh | bash
 ```
 
+Opening the panel from your laptop counts as another machine, so it asks for
+the setup code. Print it with:
+
+```bash
+journalctl -u levix --no-pager | grep -F '[Setup] Setup code:' | tail -1
+```
+
 Read the script first if you like — it is short, and it explains each step.
 
 That always installs the newest stable Levix. To stay on one version — the same
@@ -175,6 +188,13 @@ script, pinned — use its own URL:
 curl -fsSL https://levix.leviro.net/install/v2.0.0.sh | bash
 ```
 
+**Behind a proxy** — if this server reaches the internet through a proxy, the
+panel has a **WhatsApp proxy** section under Settings: protocol (HTTP, HTTPS or
+SOCKS5), host, port, and a username and password if yours needs them. It applies
+to the WhatsApp connection only — the panel itself and the AI keep connecting
+directly. Saving it never interrupts a working session; the Connection screen
+offers **Reconnect to apply** when a change is waiting.
+
 **Your own machine** — `pm2` works well:
 
 ```bash

package/deploy/install.sh

@@ -11,16 +11,20 @@
 # What it does, in order — read it before you pipe it into a shell, as you
 # should with any script that asks for sudo:
 #
-#   1. checks for Node 24+ and stops with instructions if it isn't there
+#   1. makes sure Node 24+ is available (bootstraps it on Debian/Ubuntu)
 #   2. installs the `levix` command globally from the `levix-bot` npm package
 #   3. creates a `levix` system user and /var/lib/levix for its data
 #   4. installs the systemd unit, pointed at the levix it just installed
 #   5. enables it, starts it, and prints where to go next
 #   6. offers — but never assumes — to connect a domain
 #
-# It writes exactly three things outside npm's own prefix: the system user,
-# /var/lib/levix, and /etc/systemd/system/levix.service. It never touches an
-# existing installation's data, and it can be re-run to upgrade.
+# On a machine that already has Node 24+, the installer does not touch the
+# system package manager. On a fresh Debian/Ubuntu machine it also installs
+# Node.js from NodeSource, which adds its signing key and APT source.
+#
+# Levix itself writes exactly three things outside npm's own prefix: the system
+# user, /var/lib/levix, and /etc/systemd/system/levix.service. It never touches
+# an existing installation's data, and it can be re-run to upgrade.
 
 set -euo pipefail
 
@@ -48,15 +52,97 @@ sudo_if_needed() {
 
 # --- 1. Node ---------------------------------------------------------------
 
-command -v node >/dev/null 2>&1 ||
-  die "Node is not installed. Get Node ${MIN_NODE_MAJOR} LTS from https://nodejs.org"
+node_major() {
+  if ! command -v node >/dev/null 2>&1; then
+    printf '0\n'
+    return
+  fi
 
-NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
-if [ "$NODE_MAJOR" -lt "$MIN_NODE_MAJOR" ]; then
-  die "Node ${MIN_NODE_MAJOR}+ is required (found $(node -v)). Levix stores everything in SQLite, which Node only ships with itself from ${MIN_NODE_MAJOR} on."
+  local major
+  major="$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)"
+  case "$major" in
+    ''|*[!0-9]*) printf '0\n' ;;
+    *) printf '%s\n' "$major" ;;
+  esac
+}
+
+install_node24() {
+  [ -r /etc/os-release ] ||
+    die "Node ${MIN_NODE_MAJOR}+ is required. Automatic Node installation is supported on Debian and Ubuntu only."
+
+  # shellcheck disable=SC1091
+  . /etc/os-release
+  case "${ID:-}" in
+    debian|ubuntu) ;;
+    *)
+      die "Node ${MIN_NODE_MAJOR}+ is required. Automatic Node installation is supported on Debian and Ubuntu only (found ${ID:-unknown}). Install Node ${MIN_NODE_MAJOR}+ and run this installer again."
+      ;;
+  esac
+
+  command -v apt-get >/dev/null 2>&1 ||
+    die "This looks like ${ID}, but apt-get is unavailable. Install Node ${MIN_NODE_MAJOR}+ and run this installer again."
+
+  say "Installing Node ${MIN_NODE_MAJOR} from NodeSource…"
+
+  sudo_if_needed apt-get update
+  sudo_if_needed apt-get install -y ca-certificates curl
+  sudo_if_needed install -d -m 0755 /etc/apt/keyrings
+
+  local key_tmp repo_tmp
+  key_tmp="$(mktemp)"
+  repo_tmp="$(mktemp)"
+
+  # Download the signing key as data; do not execute a second remote setup
+  # script inside the Levix installer.
+  if ! curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key -o "$key_tmp"; then
+    rm -f "$key_tmp" "$repo_tmp"
+    die "Could not download the NodeSource signing key."
+  fi
+
+  printf '%s\n' \
+    "deb [signed-by=/etc/apt/keyrings/nodesource.asc] https://deb.nodesource.com/node_${MIN_NODE_MAJOR}.x nodistro main" \
+    > "$repo_tmp"
+
+  sudo_if_needed install -m 0644 "$key_tmp" /etc/apt/keyrings/nodesource.asc
+  sudo_if_needed install -m 0644 "$repo_tmp" /etc/apt/sources.list.d/nodesource.list
+  rm -f "$key_tmp" "$repo_tmp"
+
+  sudo_if_needed apt-get update
+  sudo_if_needed apt-get install -y nodejs
+
+  # A pre-existing nvm/asdf installation can leave an older Node earlier in
+  # PATH even after the system package is upgraded. Prefer the freshly installed
+  # NodeSource binary for the rest of this installer when it is suitable.
+  if [ -x /usr/bin/node ]; then
+    local system_major
+    system_major="$(/usr/bin/node -p 'process.versions.node.split(".")[0]' 2>/dev/null || printf '0')"
+    case "$system_major" in
+      ''|*[!0-9]*) system_major=0 ;;
+    esac
+    if [ "$system_major" -ge "$MIN_NODE_MAJOR" ]; then
+      PATH="/usr/bin:$PATH"
+      export PATH
+      hash -r
+    fi
+  fi
+}
+
+NODE_MAJOR="$(node_major)"
+if [ "$NODE_MAJOR" -lt "$MIN_NODE_MAJOR" ] || ! command -v npm >/dev/null 2>&1; then
+  if [ "$NODE_MAJOR" -eq 0 ]; then
+    say "Node ${MIN_NODE_MAJOR}+ was not found; bootstrapping it for you."
+  else
+    say "Node $(node -v) is too old; upgrading to Node ${MIN_NODE_MAJOR}."
+  fi
+  install_node24
+  NODE_MAJOR="$(node_major)"
 fi
 
-command -v npm >/dev/null 2>&1 || die "npm is not installed."
+if [ "$NODE_MAJOR" -lt "$MIN_NODE_MAJOR" ]; then
+  die "Node ${MIN_NODE_MAJOR}+ is required, but the automatic installation did not provide it (found $(node -v 2>/dev/null || printf 'no Node'))."
+fi
+command -v npm >/dev/null 2>&1 ||
+  die "Node $(node -v) is installed, but npm is missing. Install npm and run this installer again."
 command -v systemctl >/dev/null 2>&1 ||
   die "This script installs a systemd service, and systemd isn't here. Run 'npm i -g ${PACKAGE}' and start 'levix' yourself."
 
@@ -151,7 +237,7 @@ cat <<EOF
   Open the panel and pick a password. Opening it from another machine also
   asks for a setup code — this prints it:
 
-    journalctl -u ${SERVICE} -n 40 | grep -A3 'Setup code'
+    journalctl -u ${SERVICE} --no-pager | grep -F '[Setup] Setup code:' | tail -1
 
   Then scan the QR from the Connection screen with WhatsApp.
 

package/deploy/levix.service

@@ -4,6 +4,9 @@
 #   sudo systemctl enable --now levix
 #   journalctl -u levix -f          # the setup code is printed here on first run
 #
+# The first-run setup code is one line on stdout, so the journal has it:
+#   journalctl -u levix --no-pager | grep -F '[Setup] Setup code:' | tail -1
+#
 # deploy/install.sh installs this and rewrites ExecStart with the real path of
 # the `levix` command it just installed — `/usr/bin/env levix` only works when
 # npm's global bin is on systemd's own PATH, which it is not under nvm and not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "levix-bot",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A self-hosted personal WhatsApp bot with an AI agent, group moderation and a web control panel.",
   "main": "src/index.js",
   "scripts": {
@@ -26,27 +26,32 @@
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "@google/generative-ai": "^0.24.1",
+    "@google/genai": "^2.19.0",
     "@sefinek/google-tts-api": "^2.1.15",
     "@whiskeysockets/baileys": "7.0.0-rc14",
     "axios": "^1.9.0",
-    "ejs": "^3.1.10",
+    "ejs": "^6.0.1",
     "express": "^5.1.0",
     "express-session": "^1.18.1",
     "ffmpeg-static": "^5.3.0",
+    "https-proxy-agent": "^9.1.0",
     "node-cache": "^5.1.2",
     "node-cron": "^4.1.0",
-    "pino": "^9.7.0",
+    "pino": "^10.3.1",
     "pino-pretty": "^13.0.0",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
-    "socket.io": "^4.8.1"
+    "socket.io": "^4.8.1",
+    "socks": "^2.8.9",
+    "socks-proxy-agent": "^10.1.0",
+    "undici": "^8.10.0"
   },
   "allowScripts": {
     "@whiskeysockets/baileys": true,
     "esbuild": true,
     "ffmpeg-static": true,
-    "protobufjs": true
+    "protobufjs": true,
+    "@google/genai": true
   },
   "repository": {
     "type": "git",

package/public/dashboard.css

@@ -302,6 +302,15 @@ kbd {
 .pill.off .dot {
   background: var(--danger);
 }
+/* Connecting / waiting for a scan / reconnecting: neither linked nor dead. */
+.pill.warn {
+  color: var(--warn);
+  border-color: color-mix(in srgb, var(--warn) 40%, transparent);
+}
+.pill.warn .dot {
+  background: var(--warn);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--warn) 22%, transparent);
+}
 
 .btn {
   display: inline-flex;