windscout 0.5.8 → 0.6.1

package/README.md

@@ -13,6 +13,7 @@ WindScout drives the official `windscribe-cli`: it connects to each country × p
 - Linux, macOS or Windows 10/11
 - Node.js 20+
 - The [Windscribe desktop app](https://windscribe.com/download) installed, running and logged in. It includes `windscribe-cli`, which WindScout uses to control the app. Check with `windscribe-cli status`, which should show `Logged in`. On Windows the app doesn't put the CLI on `PATH`, so run `"C:\Program Files\Windscribe\windscribe-cli.exe" status` instead. WindScout finds it there on its own.
+- Optional, for [parallel scans](#parallel-scan-with-docker): Docker. WindScout offers to install it.
 
 ## Install
 
@@ -53,6 +54,7 @@ Run `windscout` with no arguments to open the interactive picker:
 | `s` | toggle the speed test (off = connect-only mode) |
 | `f` | toggle "block internet while scanning" (firewall) |
 | `r` | toggle random order: scan the selected countries shuffled, a new order each run |
+| `d` | toggle the [parallel scan in docker containers](#parallel-scan-with-docker) (installs or starts docker first, after asking) |
 | `u` | update to the newer version and restart (only when the picker shows one is out) |
 | `enter` | start scanning |
 | `q` | quit (during a scan: stop and show partial results; press again to force quit) |
@@ -61,7 +63,7 @@ Run `windscout` with no arguments to open the interactive picker:
 
 Your selection is saved to `~/.config/windscout/config.json` (`%USERPROFILE%\.config\windscout\config.json` on Windows) and preselected next time.
 
-While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command; type a number at the prompt to connect to it.
+While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command. At the prompt, press enter to connect to the best one, type another one's number to connect to that, or `q` to quit.
 
 ### Non-interactive
 
@@ -82,6 +84,7 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | `-n, --no-speed` | connect-only mode: skip the download test, rank by latency | picker: saved, or connect-only on first run; with `-c`: speed test on |
 | `-f, --firewall` | block internet while scanning, except through the VPN | picker: saved, or off; with `-c`: off |
 | `-r, --random` | scan the countries in a random order | picker: saved, or off; with `-c`: off |
+| `-d, --docker` | [scan in parallel, in docker containers](#parallel-scan-with-docker) | picker: saved, or off; with `-c`: off |
 | `-v, --version` | print the installed version; if a newer one is on npm, show the update command (with `sudo` when needed) and ask (y/n) to run it | |
 
 ## Connect-only mode
@@ -109,6 +112,48 @@ While scanning, press `tab` to switch between the availability grid and the spee
 
 Between attempts the VPN is disconnected for a moment, and apps on your computer (browser, messengers, updates) can go online over your real connection. Turn on **block internet while scanning** with `f` in the picker or `--firewall`, and WindScout switches on the Windscribe app's firewall for the scan: nothing gets online except through the VPN. When the scan ends or you stop it, the firewall goes back off (if you already had it on, WindScout leaves it on). While a scan is paused, the firewall keeps blocking.
 
+## Parallel scan with Docker
+
+A normal scan tries one location at a time, because your computer has one VPN connection. Turn on **parallel scan** with `d` in the picker or `--docker`, and each attempt runs in its own docker container instead. Each container has its own Windscribe app (Windscribe's Linux CLI app) and so its own VPN connection, and several locations are tried at once. The results come back to the scan screen, which shows a line per container.
+
+**How many containers:** one per attempt, as many as docker's CPUs allow and three quarters of its memory (at 250 MB each), at most 8. The picker shows the number (`8 at a time`) and the estimate that goes with it.
+
+**First time:** if docker isn't installed or isn't running, `d` (or a scan with `--docker`) opens a dialog that says what WindScout will do, and does it once you agree:
+
+- **macOS:** downloads Docker Desktop from docker.com (about 600 MB), installs it in `/Applications` with its license accepted, and starts it.
+- **Linux:** runs Docker's install script from get.docker.com (or, where docker.com refuses, installs your distribution's own docker package), adds you to the `docker` group and starts docker. The group takes effect in a new login session: log out and back in (or run `newgrp docker`), then start WindScout again. Members of the `docker` group can control docker, which is as good as root.
+- **Windows:** installs Docker Desktop with winget, with its license accepted and its WSL 2 engine, and starts it. Windows asks for permission, and may want a restart. Docker Desktop may also ask to install or update WSL: do what it asks, then try again. If Docker Desktop is set to Windows containers, switch it to Linux containers (right-click its icon by the clock).
+
+Steps that need root ask for your password in the dialog. WindScout checks it with `sudo` once, so a typo counts as one failed try. It keeps the password in memory until the steps are done and never saves it. Docker Desktop is free for personal use, education and small businesses; bigger companies need a [paid plan](https://www.docker.com/pricing/).
+
+Then the first parallel scan builds a local image, `windscout-worker`, with Node and Windscribe's Linux CLI app (the latest stable release on [GitHub](https://github.com/Windscribe/Desktop-App/releases)). That takes a few minutes. Later scans reuse it until WindScout updates.
+
+**In Iran (and other places docker.com refuses):** Docker Hub and docker.com refuse Iranian addresses (US sanctions), so every download falls back to mirrors in Iran when the official source refuses or doesn't answer. Everywhere else, the official sources are used as before:
+
+- **The image's base** (`node:22-bookworm-slim`) comes from Docker Hub, else from the first mirror of it that answers: `registry.docker.ir`, `docker.iranserver.com`, `docker.kernel.ir`, `mirror2.chabokan.net`, `docker-mirror.liara.ir`, `hub.hamdocker.ir`, `docker.arvancloud.ir`, `focker.ir`, `docker.mobinhost.com`, `mirror-docker.runflare.com`. It's pinned by digest, so a mirror can only hand over that exact image. To try other mirrors first, list them in `WINDSCOUT_REGISTRY_MIRRORS` (comma-separated hosts).
+- **Debian's packages** in the image come from deb.debian.org, else `mirror.shatel.ir`, `mirror.iranserver.com`, `mirror.mobinhost.com` or `mirror2.chabokan.net`. apt checks Debian's signatures, whichever mirror serves them.
+- **Windscribe's app** in the image comes from GitHub, which Iran can reach.
+- **Docker on Linux:** where get.docker.com refuses, your distribution's own docker package is installed instead, from the mirrors your system already uses.
+- **Docker Desktop on macOS and Windows** has no mirror anywhere: when docker.com refuses the download, the dialog says so. Connect a VPN (Windscribe will do), then press Retry. That's needed once, for the install.
+
+The mirrors come from [Mirava](https://github.com/MiravaOrg/Mirava)'s list of mirrors in Iran; they come and go, and that's where to look for new ones.
+
+**Kernel check:** each container first checks that docker's Linux kernel gives it what Windscribe needs: a tunnel device (tun) and a firewall (nftables). If not, the scan stops and says so, rather than showing every location as blocked. Windscribe's WireGuard also needs nftables' `fib` in its firewall table, which Docker Desktop's own Linux VM lacks (on macOS, and on Windows without WSL 2). There, WireGuard runs on this computer instead (see below).
+
+**Login:** the containers' Windscribe apps log in with the session that the Windscribe app on this computer is logged in with, so they never log in with your password. Windscribe locks an account that logs in many times at once, and a login per container would do that. WindScout reads the session from the app's settings (`~/.config/Windscribe/Windscribe2.conf` on Linux, the `com.windscribe.Windscribe2` defaults on macOS, `HKEY_CURRENT_USER\Software\Windscribe\Windscribe2` in the registry on Windows) and hands it to each container on its standard input, not on a command line, where other programs could see it. Each container's docker volume (`windscout-1`, `windscout-2`, …) keeps its app's settings for the next scans, with the WireGuard keys it registered with your account. A volume that another account used starts over. If you log out of the Windscribe app, the containers' session ends too, and the next scan gives them the new one.
+
+WindScout 0.6.0 asked for your username and password instead, and could save them in `~/.config/windscout/login.json`. WindScout now deletes that file.
+
+**Measuring:** the containers share your internet connection, so they take turns measuring latency and speed while the connecting happens in parallel. Numbers stay comparable with a normal scan. Most of the time saved comes from attempts that hang until the timeout, which overlap now.
+
+**Differences from a normal scan:**
+
+- IKEv2, and WireGuard when the kernel check finds it can't run in the containers, are tried on this computer once the containers are done, one at a time like a normal scan. The scan screen shows them on a line of their own (`this computer`), and the picker's estimate counts them. Windscribe's Linux app has no IKEv2.
+- This computer's own Windscribe connection is disconnected at the start and stays off while the containers scan, since it would carry their traffic too.
+- No firewall: "block internet while scanning" isn't used, since it would block the containers' traffic too.
+
+The containers are removed after the scan. To remove their settings too (and the session in them), run `docker volume rm windscout-1 windscout-2 …`. To remove the image, run `docker rmi windscout-worker`.
+
 ## Output
 
 While scanning:
@@ -144,7 +189,7 @@ At the end, the results, a per-protocol summary and the best pick are printed to
 - **The country list is built in.** On v2.24, `windscribe-cli locations` returns nothing, so WindScout uses a fixed list of country codes. Codes Windscribe doesn't serve are skipped quickly.
 - **A full scan takes a while.** The worst case is countries × protocols × timeout. Narrow it with `-c` and `-p`.
 - **No flags in macOS Terminal.** Terminal.app draws flag emoji wider than their space, which pushes table borders out of line, so WindScout leaves them out there (as on Windows). iTerm2 and other terminals show them.
-- **Your connection changes during the scan.** WindScout connects and disconnects the VPN repeatedly, so don't run it while you need a stable connection.
+- **Your connection changes during the scan.** WindScout connects and disconnects the VPN repeatedly, so don't run it while you need a stable connection. A [parallel scan](#parallel-scan-with-docker) does that inside its containers instead, and your computer's own VPN stays off.
 
 ## Development
 
@@ -153,6 +198,7 @@ The source is TypeScript in `src/`. It compiles to `dist/`, which is what gets p
 ```sh
 npm install
 npm run build       # compile src/ to dist/ (the windscout command is dist/cli.js)
+npm test            # build, then check the scan's scheduling (no VPN, no docker)
 node dist/cli.js    # run your build; takes the same options as windscout
 ./publish.sh        # build, install the packed tarball to check it runs, publish to npm (bump the version first)
 ```

package/dist/cli.js

@@ -5,8 +5,11 @@
 import { createInterface } from "node:readline";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
-import { CONFIG, DEFAULT_TIMEOUT, loadConfig, MIN_TIMEOUT } from "./config.js";
+import { CONFIG, DEFAULT_TIMEOUT, forgetLogin, loadConfig, loadDockerWireGuard, MIN_TIMEOUT, saveDockerWireGuard } from "./config.js";
+import { notInContainers, stopWorkers } from "./docker.js";
+import { probe } from "./probe.js";
 import { Scan } from "./scan.js";
+import { startParallel } from "./tui/docker.js";
 import { pick } from "./tui/picker.js";
 import { logProgress, showProgress } from "./tui/progress.js";
 import { command, report, target } from "./tui/report.js";
@@ -15,6 +18,7 @@ import { cyan, green, yellow } from "./tui/text.js";
 import { now, sleep } from "./time.js";
 import { canUpdate, checkUpdate, runUpdate, updateNotice, versionLines } from "./update.js";
 import { blockInternet, CLI, connectState, isFirewallOn, PROTOCOLS, restoreFirewall, waitForLogin, windscribe } from "./windscribe.js";
+import { worker } from "./worker.js";
 const HELP = `Usage: windscout [options]
 
 Find which Windscribe locations and protocols work from your network, ranked by speed.
@@ -28,6 +32,7 @@ Options:
   -n, --no-speed        connect-only: skip the download test, rank by latency (faster scan)
   -f, --firewall        block internet while scanning, except through the VPN (turned back off afterwards)
   -r, --random          scan the countries in a random order
+  -d, --docker          scan in parallel, in docker containers (as many as docker's CPUs and memory allow, up to 8)
   -v, --version         show the installed version (and offer to update if a newer one is out)
   -h, --help            show this help
 
@@ -37,18 +42,18 @@ Example: windscout -c DE,NL,TR -p stealth,tcp:443`;
 const list = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 const ask = (question) => new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: out });
-    rl.on("SIGINT", () => rl.close()); // Ctrl-C / Ctrl-D: same as enter
-    rl.on("close", () => resolve(""));
+    rl.on("SIGINT", () => rl.close()); // Ctrl-C / Ctrl-D: no answer, null
+    rl.on("close", () => resolve(null));
     rl.question(question, (a) => (resolve(a.trim()), rl.close()));
 });
-/** Asks which numbered connection to make, then runs its command and waits for it to connect */
+/** Asks which numbered connection to make (enter: the best), then runs its command and waits for it to connect */
 async function offerConnect(choices, timeout) {
-    const others = choices.length > 1 ? `, 1-${choices.length - 1} = other` : "";
+    const others = choices.length > 2 ? `, 1-${choices.length - 1} = other` : choices.length > 1 ? ", 1 = other" : "";
     for (;;) {
-        const a = await ask(`\nconnect to # (0 = best${others}, enter to quit): `);
-        if (!a)
+        const a = await ask(`\nconnect to # (enter or 0 = best${others}, q = quit): `);
+        if (a === null || /^q(uit)?$/i.test(a))
             return;
-        const r = /^\d+$/.test(a) ? choices[Number(a)] : undefined;
+        const r = a === "" ? choices[0] : /^\d+$/.test(a) ? choices[Number(a)] : undefined;
         if (!r) {
             console.log(yellow(`no #${a} in the tables`));
             continue;
@@ -85,15 +90,22 @@ async function main() {
             "no-speed": { type: "boolean", short: "n", default: false },
             firewall: { type: "boolean", short: "f", default: false },
             random: { type: "boolean", short: "r", default: false },
+            docker: { type: "boolean", short: "d", default: false },
+            worker: { type: "boolean", default: false }, // in a parallel scan's container
         },
     });
+    if (a.worker) {
+        await worker();
+        process.exit(); // its stdin may still be open: its app didn't log in
+    }
+    forgetLogin();
     if (a.help)
         return console.log(HELP);
     checkUpdate(); // runs while the app starts and the user picks, before the VPN starts switching
     if (a.version) {
         await checkUpdate();
         console.log(versionLines().join("\n"));
-        if (canUpdate() && process.stdin.isTTY && out.isTTY && /^y(es)?$/i.test(await ask("update now? (y/n) ")))
+        if (canUpdate() && process.stdin.isTTY && out.isTTY && /^y(es)?$/i.test((await ask("update now? (y/n) ")) ?? ""))
             process.exitCode = runUpdate();
         return;
     }
@@ -107,6 +119,7 @@ async function main() {
     let speedTest = !a["no-speed"];
     let firewall = a.firewall;
     let random = a.random;
+    let docker = a.docker;
     if (!countries) {
         if (!tty)
             throw new Error("no terminal for the picker: pass countries with -c");
@@ -119,6 +132,7 @@ async function main() {
             // already on in the app: show it on, since the scan won't turn it off
             firewall: firewall || isFirewallOn(status) || (saved?.firewall ?? false),
             random: random || (saved?.random ?? false),
+            docker: docker || (saved?.docker ?? false),
         });
         if (!choice)
             return;
@@ -130,17 +144,35 @@ async function main() {
         firewall = choice.firewall;
         random = choice.random;
         timeout = choice.timeout;
+        docker = choice.docker;
     }
     protocols ??= PROTOCOLS;
     timeout ??= DEFAULT_TIMEOUT;
     if (random)
         countries = countries.map((c) => [Math.random(), c]).sort(([x], [y]) => x - y).map(([, c]) => c);
-    const scan = new Scan(countries, protocols, { timeout, speedTest });
-    const blocking = firewall && (await blockInternet());
+    let probers = [probe], after; // after: what runs here once the containers are done
+    const later = notInContainers(protocols, loadDockerWireGuard()); // as far as the last parallel scan knows
+    const inContainers = countries.length * protocols.filter((p) => !later.has(p)).length;
+    if (docker && inContainers) {
+        const started = await startParallel(inContainers);
+        if (!started)
+            return leaveScreen();
+        saveDockerWireGuard(started.wireguard);
+        probers = started.probers;
+        after = { prober: probe, protocols: notInContainers(protocols, started.wireguard), name: "this computer" };
+        await windscribe("disconnect"); // a VPN connection here would carry the containers' traffic too
+    }
+    const scan = new Scan(countries, protocols, { timeout, speedTest }, probers, after);
+    // not with containers: their traffic goes out through this computer, and the firewall would block it
+    const blocking = firewall && !after && (await blockInternet());
     const view = tty ? showProgress(scan, blocking) : logProgress(scan);
     await scan.run(view);
+    if (after)
+        await stopWorkers();
     await restoreFirewall();
     view.close();
+    for (const e of new Set(scan.errors))
+        console.error(yellow(e));
     if (scan.stopping)
         console.log(yellow("interrupted, showing partial results"));
     const choices = report(scan.results, protocols, { all: a.all, speedTest });

package/dist/config.js

@@ -1,11 +1,12 @@
-// The picker's selection, remembered between runs.
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+// The picker's selection, and what the last parallel scan found its containers can do, remembered between runs.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { COUNTRIES, PROTOCOLS } from "./windscribe.js";
 export const DEFAULT_TIMEOUT = 15;
 export const MIN_TIMEOUT = 10; // seconds; shorter cuts off connections that would have worked
 export const CONFIG = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "windscout", "config.json");
+const DOCKER_FILE = join(dirname(CONFIG), "docker.json"); // what the last parallel scan found its containers can do
 /** The saved choice, minus anything this version doesn't offer; null on first run or an unreadable file */
 export function loadConfig() {
     try {
@@ -17,6 +18,7 @@ export function loadConfig() {
             firewall: c.firewall === true,
             random: c.random === true,
             timeout: c.timeout >= MIN_TIMEOUT ? c.timeout : DEFAULT_TIMEOUT,
+            docker: c.docker === true,
         };
     }
     catch {
@@ -30,3 +32,26 @@ export function saveConfig(c) {
     }
     catch { } // not being able to remember isn't worth failing the scan
 }
+/** Whether WireGuard worked in the docker containers last time (yes until a scan finds otherwise), for the picker's estimate */
+export function loadDockerWireGuard() {
+    try {
+        return JSON.parse(readFileSync(DOCKER_FILE, "utf8")).wireguard !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export function saveDockerWireGuard(wireguard) {
+    try {
+        mkdirSync(dirname(DOCKER_FILE), { recursive: true });
+        writeFileSync(DOCKER_FILE, JSON.stringify({ wireguard }) + "\n");
+    }
+    catch { } // not being able to remember isn't worth failing the scan
+}
+/** Deletes the Windscribe username and password that 0.6.0 saved for the docker containers: they log in with this computer's session now */
+export function forgetLogin() {
+    try {
+        rmSync(join(dirname(CONFIG), "login.json"), { force: true });
+    }
+    catch { } // not being able to delete it isn't worth failing the scan
+}

package/dist/docker.js

@@ -0,0 +1,330 @@
+// Parallel scans: a docker container per slot, each with its own Windscribe app, so each has its own tunnel.
+// The apps log in with the session this computer's app is logged in with.
+// A container runs `windscout --worker` (worker.ts) and takes attempts from here one at a time:
+// a JSON object per line on its stdin, answered the same way on its stdout.
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { sleep } from "./time.js";
+const IMAGE = "windscout-worker";
+const ROOT = new URL("..", import.meta.url); // this package: its package.json and dist/ go into the image
+// The image's base, node:22-bookworm-slim pinned by digest: whichever registry serves it, it's exactly this image.
+// ponytail: pinned; refresh it now and then (docker buildx imagetools inspect node:22-bookworm-slim) for Node and Debian fixes
+const BASE = "library/node@sha256:3ed98443660ff48413b5af19ecefce3b9d50845a901a43420d47cc63a9fddbe9";
+const BASE_TAG = "windscout-base:node22-3ed98443"; // BASE once pulled, from wherever
+// Docker Hub, then mirrors of it in Iran, where Docker Hub refuses to serve (US sanctions). From github.com/MiravaOrg/Mirava:
+// the first six after Docker Hub served BASE on 2026-10-21. WINDSCOUT_REGISTRY_MIRRORS (comma-separated hosts) go first.
+// ponytail: mirrors come and go; refresh the list from Mirava when they do
+const REGISTRIES = [...(process.env.WINDSCOUT_REGISTRY_MIRRORS?.split(",").map((h) => h.trim()).filter(Boolean) ?? []),
+    "docker.io", "registry.docker.ir", "docker.iranserver.com", "docker.kernel.ir", "mirror2.chabokan.net", "docker-mirror.liara.ir",
+    "hub.hamdocker.ir", "docker.arvancloud.ir", "focker.ir", "docker.mobinhost.com", "mirror-docker.runflare.com"];
+// Debian's packages: deb.debian.org, else its mirrors in Iran (from Mirava; apt checks Debian's signatures, whoever serves them).
+// Over http: the base image has no CA certificates yet.
+// Windscribe's Linux CLI app: its latest stable release on GitHub, found through the releases/latest redirect, not GitHub's API,
+// whose 60 requests an hour per address run out behind shared addresses (as on Iran's mobile networks).
+// openresolv: the app sets the tunnel's DNS through resolvconf; without it, DNS goes nowhere once connected.
+// The CMD first checks the kernel (WSL's builds tun and parts of nftables as modules): no tun or nftables, no tunnel, so
+// the container stops saying so instead of scanning. The helper's WireGuard routing also puts a fib rule in an inet table,
+// which Docker Desktop's own kernel (macOS, Windows without WSL) can't run: WS_WIREGUARD=0 then, and it runs on this computer.
+// No systemd in a container: start the helper (root) like its unit would; the worker starts the app once it has the session
+const DOCKERFILE = `FROM ${BASE_TAG}
+ENV LANG=C.UTF-8
+RUN for m in deb.debian.org mirror.shatel.ir mirror.iranserver.com mirror.mobinhost.com mirror2.chabokan.net; do \\
+   sed -i -E "s#^URIs: [a-z]+://[^/]+/#URIs: http://$m/#" /etc/apt/sources.list.d/debian.sources; \\
+   apt-get -o Acquire::http::Timeout=20 update --error-on=any && break; \\
+ done \\
+ && apt-get install -y --no-install-recommends ca-certificates curl openresolv \\
+ && v=$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/Windscribe/Desktop-App/releases/latest | sed 's#.*/v##') \\
+ && curl -fsSL -o /tmp/windscribe.deb "https://github.com/Windscribe/Desktop-App/releases/download/v$v/windscribe-cli_"$v"_$(dpkg --print-architecture).deb" \\
+ && apt-get install -y --no-install-recommends /tmp/windscribe.deb \\
+ && rm -rf /tmp/windscribe.deb /var/lib/apt/lists/* \\
+ && useradd -m ws && mkdir -p /home/ws/.config/Windscribe && chown -R ws: /home/ws
+COPY package.json /app/
+COPY dist /app/dist
+CMD mkdir -p /dev/net && { [ -c /dev/net/tun ] || mknod /dev/net/tun c 10 200; } \\
+  && ip tuntap add mode tun dev wscheck && ip link del wscheck \\
+  && nft 'add table inet wscheck; add chain inet wscheck o { type filter hook output priority 0; }; add rule inet wscheck o ct mark 1 reject; delete table inet wscheck' \\
+  || { echo "this docker's Linux kernel can't give a container a VPN tunnel (tun) and firewall (nftables)" >&2; exit 1; }; \\
+  nft 'add table inet wscheck; add chain inet wscheck p { type filter hook prerouting priority 0; }; add rule inet wscheck p fib saddr type != local drop; delete table inet wscheck' 2>/dev/null \\
+  && wg=1 || wg=0; \\
+  /opt/windscribe/helper >/dev/null 2>&1 & \\
+  exec runuser -u ws -- env HOME=/home/ws WS_WIREGUARD=$wg node /app/dist/cli.js --worker
+`;
+const user = userInfo().username;
+// Docker Desktop, and the docker CLI in it: used when docker isn't on PATH (a fresh install on Windows isn't, for this process)
+const DD = join(process.env.ProgramFiles || "C:\\Program Files", "Docker", "Docker");
+const [DESKTOP, DESKTOP_CLI] = {
+    darwin: ["/Applications/Docker.app", "/Applications/Docker.app/Contents/Resources/bin/docker"],
+    win32: [join(DD, "Docker Desktop.exe"), join(DD, "resources", "bin", "docker.exe")],
+}[process.platform] ?? [];
+/** Where to install docker by hand, when installing it from here didn't work */
+export const INSTALL_DOCS = {
+    darwin: "https://docs.docker.com/desktop/setup/install/mac-install/",
+    win32: "https://docs.docker.com/desktop/setup/install/windows-install/",
+}[process.platform] ?? "https://docs.docker.com/engine/install/";
+const lastLine = (s) => s.trim().split("\n").at(-1)?.trim() ?? "";
+/** Runs a command (a shell line when args is null); onLine gets its output as it comes, curl's progress too. code -1: not installed */
+function exec(cmd, args, { input, onLine = () => { }, timeout } = {}) {
+    return new Promise((resolve) => {
+        const p = args ? spawn(cmd, args, { timeout }) : spawn(cmd, { shell: true, timeout });
+        let out = "";
+        const take = (d) => {
+            out = (out + d).slice(-20_000);
+            String(d).split(/[\r\n]+/).map((l) => l.trim()).filter(Boolean).forEach(onLine);
+        };
+        p.stdout.on("data", take);
+        p.stderr.on("data", take);
+        p.stdin.on("error", () => { });
+        p.stdin.end(input);
+        p.on("error", (e) => resolve({ code: -1, out: e.message }));
+        p.on("close", (code) => resolve({ code: code ?? 1, out }));
+    });
+}
+/** Runs the docker CLI. Not on PATH: Docker Desktop's folder goes on it, for the CLI and the credential helper beside it */
+async function docker(args, options) {
+    const r = await exec("docker", args, options);
+    if (r.code !== -1 || !DESKTOP_CLI || !existsSync(DESKTOP_CLI) || process.env.PATH?.split(delimiter).includes(dirname(DESKTOP_CLI)))
+        return r;
+    process.env.PATH = dirname(DESKTOP_CLI) + delimiter + process.env.PATH;
+    return exec("docker", args, options);
+}
+let info = { cpus: 0, memory: 0, os: "linux" }; // docker's, from the last dockerState() that found it ready
+/** ready: the daemon answers us. denied: it runs, but this user may not use it (Linux: not in the docker group yet) */
+export async function dockerState() {
+    const r = await docker(["info", "--format", "{{.NCPU}} {{.MemTotal}} {{.OSType}}"], { timeout: 30_000 });
+    if (r.code === -1)
+        return DESKTOP && existsSync(DESKTOP) ? "stopped" : "missing";
+    if (r.code)
+        return /permission denied/i.test(r.out) ? "denied" : "stopped";
+    const [cpus, memory, os] = r.out.trim().split(/\s+/);
+    info = { cpus: Number(cpus), memory: Number(memory), os };
+    return "ready";
+}
+const WORKER_MEMORY = 250e6; // bytes per container: Windscribe's app and helper, a tunnel and node take ~120 MB
+const MAX_WORKERS = 8; // ponytail: past this, more containers mostly add load on the one uplink; raise if real scans say so
+/** Protocols the containers can't do, which a parallel scan runs on this computer after them: IKEv2 (Windscribe's Linux app
+ * has none), and WireGuard when their kernel can't run its routing (see DOCKERFILE) */
+export const notInContainers = (protocols, wireguard) => new Set(protocols.filter((p) => p === "ikev2" || (p === "wireguard" && !wireguard)));
+/** Containers for a scan of this many attempts: one per attempt, within docker's CPUs and 3/4 of its memory */
+export const workerCount = (attempts) => Math.max(1, Math.min(attempts, MAX_WORKERS, info.cpus, Math.floor((info.memory * 0.75) / WORKER_MEMORY)));
+const DMG = `https://desktop.docker.com/mac/main/${process.arch === "arm64" ? "arm64" : "amd64"}/Docker.dmg`;
+const START_DESKTOP = process.platform === "win32"
+    ? { label: "start Docker Desktop", cmd: () => `start "" "${DESKTOP}"` }
+    : { label: "start Docker Desktop", cmd: () => "open -a Docker" };
+// docker.com refuses some countries (Iran: US sanctions): then the distribution's own docker package, from the mirrors it uses.
+// get.docker.com may have left its repository behind: without that gone, the package manager would fail on it
+const DISTRO_DOCKER = "rm -f /etc/apt/sources.list.d/docker.list /etc/apt/sources.list.d/docker.sources /etc/yum.repos.d/docker-ce.repo; "
+    + "if command -v apt-get >/dev/null; then apt-get update; apt-get install -y docker.io && { apt-get install -y docker-buildx || true; }; "
+    + "elif command -v dnf >/dev/null; then dnf install -y moby-engine; "
+    + "elif command -v pacman >/dev/null; then pacman -Sy --noconfirm docker docker-buildx; "
+    + "elif command -v zypper >/dev/null; then zypper --non-interactive install docker; "
+    + "else echo 'no package manager WindScout knows here: install docker yourself' >&2; false; fi";
+// Linux: members of the docker group control docker, root-equivalent; that's what lets us run it without sudo
+const JOIN = { label: "add you to the docker group, and start docker", root: true,
+    cmd: () => `usermod -aG docker "${user}" && (systemctl enable --now docker || service docker start)` };
+/** What it takes to get docker answering, from this state */
+export function steps(state) {
+    if (process.platform === "linux")
+        return state === "missing" ? [
+            { label: "install docker from get.docker.com, or else your distribution's package", root: true,
+                cmd: (d) => `{ curl -fsSL --max-time 60 -o "${d}/get-docker.sh" https://get.docker.com && sh "${d}/get-docker.sh"; } || { ${DISTRO_DOCKER}; }` },
+            JOIN,
+        ] : state === "denied" ? [JOIN] : [{ label: "start docker", root: true, cmd: () => "systemctl start docker || service docker start" }];
+    if (state !== "missing")
+        return [START_DESKTOP];
+    return process.platform === "win32" ? [
+        { label: "install Docker Desktop with winget (Windows asks for permission, and may want a restart)",
+            cmd: () => "winget install -e --id Docker.DockerDesktop --accept-package-agreements --accept-source-agreements" },
+        START_DESKTOP,
+    ] : [
+        { label: "download Docker Desktop from docker.com (about 600 MB)", cmd: (d) => `curl -fL -o "${d}/Docker.dmg" ${DMG}` },
+        { label: "install it in /Applications, accepting its license", root: true,
+            cmd: (d) => `hdiutil attach -nobrowse -quiet -mountpoint "${d}/mnt" "${d}/Docker.dmg"`
+                + ` && "${d}/mnt/Docker.app/Contents/MacOS/install" --accept-license --user="${user}"; s=$?; hdiutil detach -quiet "${d}/mnt"; exit $s` },
+        START_DESKTOP,
+    ];
+}
+/** sudo runs without asking right now (a recent password, or NOPASSWD) */
+export const sudoReady = async () => (await exec("sudo", ["-n", "true"])).code === 0;
+/** Gives sudo the password, so the root steps can run with sudo -n; "" when it took it, else why not */
+export async function sudoLogin(password) {
+    // -S: the password from stdin, -v: only validate. One line, so a typo counts as one failed try, not three
+    const r = await exec("sudo", ["-S", "-p", "", "-v"], { input: password + "\n" });
+    return !r.code ? "" : /incorrect|sorry/i.test(r.out) ? "wrong password, try again" : lastLine(r.out) || "sudo refused";
+}
+/** Runs the steps; root ones with sudo -n, after sudoLogin() (password: to log in again if that ran out meanwhile) */
+export async function runSteps(todo, password, onStep, onLine) {
+    const dir = mkdtempSync(join(tmpdir(), "windscout-"));
+    try {
+        for (const s of todo) {
+            onStep(s.label);
+            if (s.root && !(await sudoReady()) && (!password || (await sudoLogin(password))))
+                throw new Error(`sudo wants your password again: try again`);
+            const r = await (s.root ? exec("sudo", ["-n", "sh", "-c", s.cmd(dir)], { onLine }) : exec(s.cmd(dir), null, { onLine }));
+            if (r.code)
+                throw new Error(`${s.label} failed: ${lastLine(r.out) || `exit ${r.code}`}`);
+        }
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { } // a leftover temp folder isn't worth failing over
+    }
+}
+/** Waits for the daemon after starting it; Docker Desktop can take a minute or two the first time */
+export async function waitReady() {
+    for (let i = 0; i < 90; i++) {
+        const state = await dockerState();
+        if (state === "ready")
+            return;
+        if (state === "denied")
+            throw new Error("docker runs now, but your user can't use it yet: try again to fix that");
+        await sleep(2000);
+    }
+    throw new Error("docker didn't start within 3 minutes. If Docker Desktop asks for something (on Windows: a restart, or WSL), do that, then try again");
+}
+/** Hash of what goes into the image (dist/ holds this file, so the Dockerfile too): another build of windscout gets a new image */
+function fingerprint() {
+    const h = createHash("sha256");
+    const files = ["package.json", ...readdirSync(new URL("dist", ROOT), { recursive: true, encoding: "utf8" }).map((f) => `dist/${f}`)].sort();
+    for (const f of files)
+        if (statSync(new URL(f, ROOT)).isFile())
+            h.update(f).update(readFileSync(new URL(f, ROOT)));
+    return h.digest("hex").slice(0, 16);
+}
+/** Whether a registry answers at all: 200 or 401 from its API (Docker Hub says 403 to Iran) */
+const answers = (registry) => fetch(`https://${registry === "docker.io" ? "registry-1.docker.io" : registry}/v2/`, { signal: AbortSignal.timeout(8000) })
+    .then((r) => r.status === 200 || r.status === 401, () => false);
+/** Gets the image's base: from the first registry in REGISTRIES that answers and serves it */
+async function pullBase(onLine) {
+    if (!(await docker(["image", "inspect", BASE_TAG])).code)
+        return;
+    const up = await Promise.all(REGISTRIES.map(answers)); // asking them all at once: dead ones would each take the timeout
+    // Docker Hub last even if it didn't answer: docker may reach it through a proxy that this process doesn't use
+    const order = [...REGISTRIES.filter((_, i) => up[i]), ...(up[REGISTRIES.indexOf("docker.io")] ? [] : ["docker.io"])];
+    let why = "none answered";
+    for (const registry of order) {
+        onLine(`the base image, from ${registry}`);
+        const ref = `${registry}/${BASE}`;
+        const r = await docker(["pull", ref], { onLine, timeout: 15 * 60_000 });
+        if (!r.code)
+            return void (await docker(["tag", ref, BASE_TAG]));
+        why = `${registry}: ${lastLine(r.out)}`;
+    }
+    throw new Error(`couldn't get the containers' base image from Docker Hub or its mirrors (${why}). A VPN may help`);
+}
+/** Builds the containers' image, unless this windscout's is there already; onLine gets the build's output */
+export async function buildImage(onLine) {
+    if (info.os === "windows")
+        throw new Error("Docker Desktop runs Windows containers: switch it to Linux containers (right-click its icon by the clock), then try again");
+    const tag = fingerprint();
+    const have = await docker(["image", "inspect", "-f", '{{index .Config.Labels "windscout"}}', IMAGE]);
+    if (!have.code && have.out.trim() === tag)
+        return;
+    await pullBase(onLine);
+    // no --progress=plain: when piped, BuildKit prints plain anyway, and a distribution's docker may have only the old builder
+    const r = await docker(["build", "--label", `windscout=${tag}`, "-t", IMAGE, "-f", "-", fileURLToPath(ROOT).replace(/[\\/]$/, "")], { input: DOCKERFILE, onLine });
+    if (r.code)
+        throw new Error(`building the containers' image failed: ${lastLine(r.out)}`);
+}
+// one at a time: `await lock()` resolves to the function that lets the next one in
+function mutex() {
+    let last = Promise.resolve();
+    return () => new Promise((enter) => {
+        last = last.then(() => new Promise((leave) => enter(leave)));
+    });
+}
+const running = new Map(); // container name → its `docker run`, until the container stops
+// a crash or a force quit leaves them running: remove them
+const removeAll = () => running.size && spawnSync("docker", ["rm", "-f", ...running.keys()], { stdio: "ignore" });
+process.on("exit", removeAll);
+/** Starts n containers, their apps logged in with this computer's session; resolves to a prober for each container that got
+ * ready, and whether WireGuard works in them */
+export async function startWorkers(n, session, onStatus) {
+    const measuring = mutex();
+    let wireguard = true;
+    let ready = 0;
+    const start = (i) => new Promise((resolve) => {
+        const name = `windscout-${process.pid}-${i + 1}`;
+        // its own volume keeps its app's settings for the next scans: its WireGuard keys, registered with Windscribe once
+        // it makes /dev/net/tun itself: Docker's Linux VM may have none (WSL loads tun as a module), and --device needs one there
+        const p = spawn("docker", ["run", "-i", "--rm", "--init", "--name", name, "--cap-add", "NET_ADMIN", "--device-cgroup-rule", "c 10:200 rwm",
+            "--sysctl", "net.ipv4.conf.all.src_valid_mark=1", "-v", `windscout-${i + 1}:/home/ws/.config/Windscribe`, IMAGE], { detached: process.platform !== "win32" }); // its own process group, so ctrl-c reaches only us (Windows would open a window)
+        running.set(name, p);
+        const send = (m) => p.stdin.write(JSON.stringify(m) + "\n");
+        p.stdin.on("error", () => { }); // it stopped: "close" deals with that
+        send({ session }); // on stdin, not in the command line or the environment, where ps and docker inspect show it
+        let on = (_) => { }; // the current phase's message handler
+        let fail = (_) => { }; // and what it does when the container stops
+        let dead = "", err = "";
+        p.stderr.on("data", (d) => (err = (err + d).slice(-2000)));
+        createInterface({ input: p.stdout }).on("line", (l) => {
+            let m;
+            try {
+                m = JSON.parse(l);
+            }
+            catch {
+                return; // not ours
+            }
+            on(m);
+        });
+        const gone = (why) => {
+            if (dead)
+                return;
+            dead = why;
+            running.delete(name);
+            fail(why);
+        };
+        p.on("error", (e) => gone(e.message));
+        p.on("close", (code) => gone(lastLine(err) || `exited (${code})`));
+        const prober = (query, protocol, { timeout, speedTest, stopped = () => false, onStep = () => { } }) => new Promise((done, reject) => {
+            if (dead)
+                return reject(new Error(`container ${i + 1} stopped: ${dead}`));
+            let leave = null, over = false;
+            const tick = setInterval(() => stopped() && send({ stop: true }), 1000);
+            const end = () => ((over = true), clearInterval(tick), leave?.());
+            fail = (why) => (end(), reject(new Error(`container ${i + 1} stopped: ${why}`)));
+            on = async (m) => {
+                if (m.step)
+                    onStep(m.step);
+                else if (m.measure) {
+                    onStep("waiting for the other containers to measure");
+                    const l = await measuring();
+                    if (over)
+                        l();
+                    else
+                        (leave = l), send({ go: true });
+                }
+                else if (m.measured)
+                    leave?.(), (leave = null);
+                else if (m.result)
+                    end(), done(m.result);
+            };
+            send({ probe: { query, protocol, timeout, speedTest } });
+        });
+        fail = (why) => (onStatus(`container ${i + 1}: ${why}`), resolve(null));
+        on = (m) => {
+            if (!m.ready)
+                return;
+            wireguard &&= m.wireguard !== false;
+            fail = () => { };
+            onStatus(`${++ready} of ${n} ready`);
+            resolve(prober);
+        };
+    });
+    const probers = (await Promise.all(Array.from({ length: n }, (_, i) => start(i)))).filter((p) => p !== null);
+    return { probers, wireguard };
+}
+/** Ends the containers once the scan is over: a worker exits when its stdin closes, and docker removes its container */
+export async function stopWorkers() {
+    for (const p of running.values())
+        p.stdin?.end();
+    for (let i = 0; running.size && i < 40; i++)
+        await sleep(250);
+    removeAll(); // stuck ones: their docker run would keep us from exiting
+}