Skip to content

armgit / axuse

Public Imported from GitHub
0

Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies

Server mode: run axuse on display-less Ubuntu servers — headed Chrome on an auto-booted Xvfb

CTOL Team BJ5bb55d3fb658
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fc92b19..fb85a70 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -142,3 +142,41 @@ jobs:
run: node tools/skip-audit.mjs "$RUNNER_TEMP/tap.txt"
- name: Doctor smoke
run: node src/cli.js doctor
+
+ # ---------------------------------------------------------- Linux server
+ # The production server lane: NO desktop session and NO DISPLAY — the
+ # exact deployment shape for agent CLIs (codex, claude code, opencode) on
+ # Ubuntu servers. Challenge/anti-bot pages detect --headless Chrome as
+ # their first step, so the supported lane is HEADED Chrome on an
+ # auto-booted private Xvfb (server mode). test/server-mode.test.js asserts
+ # the anti-bot posture live (no Headless UA, navigator.webdriver false,
+ # desktop viewport, WebGL) with a forced dead DISPLAY — hermetic.
+ linux-server:
+ name: Linux server (ubuntu-latest, no display, Node 22)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ - name: Install Chrome for Testing + Xvfb + fonts
+ run: |
+ set -euo pipefail
+ metadata="$RUNNER_TEMP/cft.json"
+ curl --fail --silent --show-error --location \
+ https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
+ --output "$metadata"
+ url="$(node -e 'const fs=require("node:fs"); const d=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); const hit=d.channels.Stable.downloads.chrome.find((x)=>x.platform==="linux64"); if(!hit) process.exit(2); process.stdout.write(hit.url);' "$metadata")"
+ curl --fail --silent --show-error --location "$url" --output "$RUNNER_TEMP/cft.zip"
+ unzip -q "$RUNNER_TEMP/cft.zip" -d "$RUNNER_TEMP/cft"
+ echo "AXUSE_BROWSER=$RUNNER_TEMP/cft/chrome-linux64/chrome" >> "$GITHUB_ENV"
+ sudo apt-get update -qq
+ sudo apt-get install -y -qq xvfb fonts-liberation fonts-dejavu-core fontconfig
+ - name: Full suite with DISPLAY unset (server mode auto-boots Xvfb)
+ run: |
+ set -o pipefail
+ env -u DISPLAY node --test --test-timeout=90000 --test-reporter=tap test/*.test.js | tee "$RUNNER_TEMP/tap.txt"
+ - name: Skip audit
+ run: node tools/skip-audit.mjs "$RUNNER_TEMP/tap.txt"
+ - name: Doctor smoke (server mode: headed Chrome on an auto-booted Xvfb)
+ run: env -u DISPLAY node src/cli.js doctor
diff --git a/README.md b/README.md
index 4853beb..3f3c3c4 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,11 @@ element refs like `[ref=e7]`. Each action returns only what changed.
| variable | effect |
|---|---|
-| `AXUSE_HEADLESS=1` | launch the browser without a window (servers, CI) |
+| `AXUSE_SERVER_MODE` | `auto` (default): on a display-less Linux server, boot a private Xvfb and keep Chrome fully **headed** on it (anti-bot-safe; see [Servers, no desktop](docs/server-mode.md)) |
+| `AXUSE_DISPLAY_SIZE` | virtual display geometry for server mode (default `1920x1080x24`) |
+| `AXUSE_NO_SANDBOX=1` | force `--no-sandbox` (auto for root/container server runs) |
+| `AXUSE_NEUTRALIZE_WEBDRIVER=0` | disable the `navigator.webdriver` neutralizer (restores the human-browser value `false`) |
+| `AXUSE_HEADLESS=1` | launch the browser without a window — **trusted internal pages only**: challenge/anti-bot pages detect headless first; servers get server mode instead |
| `AXUSE_BROWSER` | path to the browser binary |
| `AXUSE_PROFILE_DIR` | where temporary browser profiles go (default: OS temp; they are deleted on exit) |
| `AXUSE_BRIDGE_DIR` | override the local bridge state directory (default: `~/Library/Application Support/axuse` on macOS) |
@@ -93,6 +97,20 @@ element refs like `[ref=e7]`. Each action returns only what changed.
To drive your own logged-in Chrome instead of a fresh browser, see
[Driving your daily browser](#driving-your-daily-browser-the-codex-pattern).
+## Servers, no desktop (Ubuntu server lane)
+
+axuse runs under agent CLIs (codex, claude code, opencode) on headless
+Ubuntu servers. Challenge/anti-bot pages check *is this a headless browser?*
+first, so server mode never uses `--headless`: it boots a private Xvfb and
+runs Chrome **fully headed** on it — real headed build, no headless
+fingerprint (verified live against Turnstile: `ax_solve_captcha` solves on a
+server with no desktop, and the slider engine's human-curve drags land
+10/10). Solver plugins that need vision call a multimodal model through any
+OpenAI-compatible API; keys come from env vars or an owner-only secrets
+file. One-time setup, systemd wiring, env reference and scale notes:
+[`docs/server-mode.md`](docs/server-mode.md) — and `node src/cli.js doctor`
+verifies the whole lane (it prints the measured anti-bot posture).
+
## Benchmark
On 16 server-scored browser tasks, run in the same harness (Codex CLI) with
diff --git a/SKILL.md b/SKILL.md
index 5f9b394..b9579ea 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -61,6 +61,14 @@ Loaded plugins may also contribute **capability tools** (`ax_vault`,
`tools()` export — capability surfaces, not solves. `ax_plugins` lists each
loaded package together with its contributed tool names.
+**Servers (no desktop):** on a display-less Linux host axuse auto-boots a
+private Xvfb and keeps Chrome fully **headed** on it — never pass
+`headless: true` for challenge/anti-bot pages (they check headless first).
+The `ax_open` result reports the fact: `display: :N (virtual …)`. Solvers
+work unchanged; vision needs `<PREFIX>_VISION_KEY` (any OpenAI-compatible
+endpoint) or the owner-only `~/.config/axuse/secrets.json`. Full lane:
+`docs/server-mode.md`.
+
## Error vocabulary (typed — read `code`, `hint`, `retry`)
- `REF_NOT_FOUND` / `STALE_STATE` → the page changed under you: `retry:
@@ -137,8 +145,9 @@ Verified live.
activation, RandR per-monitor layout in `ax_desktop_screen_info` — and the
**structure-first layer through AT-SPI** (zero-dependency D-Bus client):
`ax_desktop_ax_snapshot/ax_click/ax_set/ax_read` with refs, roles, names,
-bounds and states, like macOS System Events. No extra packages; `xvfb-run`
-covers headless hosts. Coordinates are root-window pixels. Screenshots honor
+bounds and states, like macOS System Events. No extra packages; headless
+hosts are covered by server mode's auto-booted Xvfb (`xvfb-run` also works).
+Coordinates are root-window pixels. Screenshots honor
the byte budget with a quality → quality → downscale ladder (vision keeps a
usable image instead of a dead end), and `ax_desktop_type` pastes long or
non-keymap text through the clipboard when xclip is present (reported
diff --git a/docs/server-mode.md b/docs/server-mode.md
new file mode 100644
index 0000000..d4a095d
--- /dev/null
+++ b/docs/server-mode.md
@@ -0,0 +1,186 @@
+# Server mode — axuse on Ubuntu servers (no desktop, no display)
+
+Server mode is the supported lane for running axuse under agent CLIs (Codex,
+Claude Code, OpenCode, …) on a headless **Ubuntu server**: **fully HEADED
+Chrome on an auto-provisioned X virtual framebuffer (Xvfb)**.
+
+It exists because of one fact this repo's live testing keeps confirming:
+challenge and anti-bot systems (Cloudflare Turnstile, DataDome, Geetest,
+AWS WAF, reCAPTCHA, slider gates) check *is this a headless browser?* as
+their **first step**. `--headless` / `--headless=new` is a detection signal,
+not a workaround. A headed Chrome rendering into a private Xvfb has no
+headless fingerprint at all: real window, real font stack, real raster
+pipeline, WebGL (software fallback), windowed viewport — every signal a
+human-driven desktop Chrome has.
+
+```
+server (no DISPLAY) ── ax_open ──► auto-boot private Xvfb (:NNN, 1920x1080x24)
+ └─► HEADED Chrome on it (never --headless)
+ · UA has no "Headless" substring
+ · navigator.webdriver === false (neutralized)
+ · WebGL present (SwiftShader fallback re-enabled)
+ · trusted CDP input — the solver lane works as-is
+```
+
+Nothing about the model-facing surface changes: `ax_open`, `ax_observe`,
+`ax_click`, `ax_solve_captcha {provider}`, sliders, screenshots — all work
+exactly as on a desktop. The `ax_open` result carries the fact so the agent
+(and you) can see it:
+
+```
+display: :762 (virtual 1920x1080 — headed on Xvfb, server mode)
+```
+
+## One-time server setup
+
+```bash
+# Node >= 22, a Chromium-family browser, Xvfb and real fonts.
+sudo apt-get update
+sudo apt-get install -y nodejs xvfb fonts-liberation fonts-dejavu-core fontconfig
+# Chrome (either the distro package or Chrome for Testing):
+wget -qO- https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
+ | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).channels.Stable.downloads.chrome.find(x=>x.platform==="linux64").url))' \
+ | xargs curl -sL -o /tmp/cft.zip && unzip -q /tmp/cft.zip -d /opt/axuse-cft
+sudo ln -sf /opt/axuse-cft/chrome-linux64/chrome /usr/local/bin/axuse-chrome
+# Or the classic .deb: sudo apt-get install -y google-chrome-stable
+# (from Google's repo; any Chromium-family build works — AXUSE_BROWSER points at it)
+
+node src/cli.js doctor # must say: "server mode: ready"
+```
+
+Fonts are not cosmetic: without fontconfig + font packages, text renders as
+boxes, every screenshot is garbage, and vision-based solvers (slider
+geometry crops, icon puzzles) fail. `doctor` checks this.
+
+## Wire it into the harness on the server
+
+Same as on a desktop — the MCP server does the rest:
+
+```bash
+codex mcp add axuse -- node /srv/axuse/src/cli.js mcp
+claude mcp add --scope user axuse -- node /srv/axuse/src/cli.js mcp
+node src/cli.js print-config --harness opencode # or agy | generic
+```
+
+`doctor` under the service user must print the `server mode: ready` line
+before you rely on it.
+
+### systemd service (the whole browser stack under one cgroup)
+
+One service per long-running harness. `KillMode=control-group` guarantees
+the private Xvfb dies with the agent process — no orphans:
+
+```ini
+# /etc/systemd/system/codex-axuse.service
+[Service]
+Type=exec
+User=codex-agent
+Environment=AXUSE_BROWSER=/usr/local/bin/axuse-chrome
+Environment=CAPTCHA_PRO_VISION_KEY=sk-or-v1-… # solver vision key (see below)
+# Environment=AXUSE_PROFILE_DIR=/var/lib/axuse/profiles
+ExecStart=/usr/bin/codex # or claude / opencode serve
+KillMode=control-group
+Restart=on-failure
+```
+
+For one-shot / cron-style runs no service is needed — `axuse solve`,
+`axuse open-urls` and the MCP server all boot and reap their own Xvfb.
+
+## Environment reference (server lane)
+
+| variable | effect |
+|---|---|
+| `AXUSE_SERVER_MODE` | `auto` (default) — boot a private Xvfb when Linux + no live display. `0`/`off` disables it (headed launches then fail typed with guidance). |
+| `AXUSE_DISPLAY_SIZE` | Virtual display geometry, default `1920x1080x24`. |
+| `AXUSE_NO_SANDBOX` | `1` forces `--no-sandbox`. Auto-applied anyway when running as root (containers) — Chrome refuses root otherwise. |
+| `AXUSE_BROWSER` | Path to the browser binary (as on any host). |
+| `AXUSE_PROFILE_DIR` | Where browser profiles go (defaults to the OS temp dir). |
+| `AXUSE_NEUTRALIZE_WEBDRIVER` | `0` disables the `navigator.webdriver` neutralizer (see below). Default: on. |
+| `AXUSE_HEADLESS` | **Do not set on servers with challenge traffic.** Forces `--headless` for every launch — the exact signal anti-bot systems look for. It stays available for trusted internal pages. |
+
+Every knob is checked by `node src/cli.js doctor` — run it first, it tells
+you what is missing (Xvfb, fonts, root sandbox, a stray `AXUSE_HEADLESS`).
+
+## Vision solvers on servers (the multimodal LLM by API)
+
+Solver plugins that need eyes (slider geometry on cross-origin crops, icon
+puzzles) call a vision model through a plain OpenAI-compatible HTTP API —
+that already *is* the server shape; no local model, no GUI needed:
+
+| plugin env | default |
+|---|---|
+| `<PREFIX>_VISION_KEY` | (required) e.g. an OpenRouter key |
+| `<PREFIX>_VISION_BASE` | `https://openrouter.ai/api/v1` |
+| `<PREFIX>_VISION_MODEL` | plugin default (e.g. `google/gemini-4-argon`) |
+
+`<PREFIX>` is the plugin's env namespace (`CAPTCHA_PRO_*`, `CHALLENGE_*`).
+The base accepts any OpenAI-compatible endpoint — OpenRouter (default,
+one key, many models), OpenAI, Gemini's OpenAI-compat endpoint
+(`https://generativelanguage.googleapis.com/v1beta/openai`), Anthropic's
+(`/v1/chat/completions`), or a private gateway/proxy.
+
+### Storing keys on a server (no macOS Keychain there)
+
+- env vars (systemd `Environment=`, shell profile), **or**
+- the axuse secrets file — the server-side Keychain equivalent:
+
+```bash
+mkdir -p ~/.config/axuse
+# keys are the plugin account slug OR the env-var name; owner-only mode
+cat > ~/.config/axuse/secrets.json <<'EOF'
+{
+ "captcha-pro-vision": "sk-or-v1-…",
+ "challenge-vision": "sk-or-v1-…"
+}
+EOF
+chmod 600 ~/.config/axuse/secrets.json
+```
+
+`AXUSE_SECRETS_FILE` overrides the path. A file the group/world can read is
+refused (fix: `chmod 600`). Typed failure messages name the exact options.
+
+## Scaling out (massive operations)
+
+- **One private Xvfb per axuse process** (display numbers are picked away
+ from live ones; the display survives browser restarts within the
+ process). N agent processes → N isolated displays, no contention, no
+ shared mouse/keyboard state — unlike one shared desktop.
+- **Bounded batches**: `ax_open_many {urls:[…]}` (≤100/round) for scraping
+ lanes; solver traffic stays on one tab via `ax_solve_captcha {provider}`.
+- **Aged sessions**: persistent profiles (the session-vault plugin, or
+ `profile_dir`) survive process restarts — warmer profiles pass challenges
+ more often. Server mode keeps killed profiles from waking up behind the
+ "restore pages?" bubble.
+- **Containers**: root runs get `--no-sandbox` automatically; small
+ `/dev/shm` is mitigated automatically (`--disable-dev-shm-usage`);
+ `doctor` reports both.
+- **Cleanup**: the Xvfb is a child of the axuse process — normal exits and
+ process-group kills reap it; under systemd use `KillMode=control-group`.
+
+## What is deliberately NOT done
+
+- **No headless for challenge pages.** Ever. That is the whole point.
+- **No DOM tampering with challenge logic.** The only page-level patch is
+ the `navigator.webdriver` neutralizer: modern Chrome sets it to `true`
+ merely because a DevTools client is attached — a fingerprint of *our own
+ plumbing*, present on no human-driven Chrome. axuse restores the exact
+ value a human browser reports (`false`), before any page script runs.
+ It does not fake, answer or shortcut any challenge — solvers still click
+ real widgets with trusted input. Opt out: `AXUSE_NEUTRALIZE_WEBDRIVER=0`.
+- **No fabricated results.** Solvers report `solved: false` honestly when
+ a page hard-blocks; `doctor` and tests state measured numbers.
+
+## Verify it (all commands runnable on the server)
+
+```bash
+node src/cli.js doctor
+# server mode: ready — no live X display; headed Chrome will auto-boot a
+# private Xvfb (1920x1080x24, NOT headless — anti-bot-safe; …)
+# fonts: … (only printed when fonts are missing)
+# smoke test: server mode — booting a virtual display, launching HEADED Chrome…
+# server-mode facts: display :762 (virtual) · UA headed (no Headless substring)
+# · navigator.webdriver false · viewport 1919x992 · WebGL present (SwiftShader)
+# server-mode anti-bot posture: OK — indistinguishable headed build
+
+node --test test/server-mode.test.js # the same assertions, in CI and locally
+```
diff --git a/src/cli.js b/src/cli.js
index 8313a2c..51e1844 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -296,6 +296,10 @@ async function doctor() {
out(`native WebSocket: ${hasWs ? "yes" : "NO — need Node >= 22"}`);
const browser = locateBrowser();
out(`browser: ${browser ?? "not found (set AXUSE_BROWSER)"}`);
+ // Server-mode readiness, hoisted: the desktop-driver section below and the
+ // smoke test both report against the same facts.
+ let serverModeReady = false;
+ let serverModeActive = false;
if (process.platform === "linux") {
// Chrome keeps shared memory in /dev/shm; a full tmpfs kills headed AND
// headless launches with a bare crash. axuse auto-passes
@@ -314,6 +318,31 @@ async function doctor() {
} catch {
// no /dev/shm mount — the launch path mitigates silently
}
+ // Server mode: the anti-bot-safe lane for display-less hosts (headed
+ // Chrome on an auto-booted Xvfb — never --headless, which challenge
+ // pages detect first).
+ const vd = await import("./core/vdisplay.js");
+ const displayAlive = vd.displayUsable();
+ if (displayAlive) {
+ out(`server mode: not needed — X display ${process.env.DISPLAY} is alive; Chrome launches headed on it`);
+ } else if (!vd.serverModeEnabled()) {
+ out("server mode: DISABLED (AXUSE_SERVER_MODE=0) and no live X display — headed Chrome will fail typed; unset AXUSE_SERVER_MODE to auto-boot Xvfb, or run under xvfb-run / in a desktop session");
+ } else if (!vd.xvfbBinary()) {
+ out("server mode: NOT READY — no live X display and Xvfb not found: sudo apt-get install -y xvfb (challenge/anti-bot pages detect --headless Chrome; headed-on-Xvfb is the supported server lane; headless stays available for trusted internal pages via AXUSE_HEADLESS=1 or headless: true)");
+ } else {
+ serverModeReady = true;
+ const geo = vd.displayGeometry();
+ out(`server mode: ready — no live X display; headed Chrome will auto-boot a private Xvfb (${geo.w}x${geo.h}x${geo.d}, NOT headless — anti-bot-safe; AXUSE_DISPLAY_SIZE to change, AXUSE_SERVER_MODE=0 to disable)`);
+ }
+ serverModeActive = vd.virtualDisplayStatus().active;
+ const fonts = vd.fontHint(vd.fontProbe());
+ if (fonts) out(`fonts: ${fonts}`);
+ if (typeof process.getuid === "function" && process.getuid() === 0) {
+ out("running as root: server-mode launches add --no-sandbox automatically (Chrome refuses root otherwise; AXUSE_NO_SANDBOX=1 forces it for any launch mode)");
+ }
+ if (/^(1|true)$/i.test(process.env.AXUSE_HEADLESS ?? "")) {
+ out("AXUSE_HEADLESS=1 is set: EVERY launch runs --headless and challenge/anti-bot pages WILL detect it — unset it on servers (server mode keeps Chrome headed for free)");
+ }
}
if (process.platform === "win32" || process.platform === "darwin") {
if (process.platform === "darwin" && !/^(1|true)$/i.test(process.env.AXUSE_ENABLE_MACOS_CUA ?? "")) {
@@ -356,7 +385,9 @@ async function doctor() {
}
}
} else if (process.platform === "linux") {
- if (!process.env.DISPLAY) {
+ if (serverModeActive || serverModeReady) {
+ out(`desktop driver: mounts on the server-mode virtual display (${serverModeActive ? "booted" : "boots at the first browser launch"}; ax_desktop_* then speaks XTEST + EWMH over it)`);
+ } else if (!process.env.DISPLAY) {
out(`desktop driver: not available — DISPLAY is not set (X11/XWayland session required; browser tools still work${process.env.WAYLAND_DISPLAY ? "; this looks like a native Wayland session — XWayland usually provides DISPLAY like :0/:1" : ""})`);
} else {
try {
@@ -393,13 +424,30 @@ async function doctor() {
out(`bridge hub: ${e.message}`);
}
if (browser && hasWs) {
- out("smoke test: launching headless browser, opening a page, observing…");
+ // On a display-less Linux host with Xvfb, smoke-test the REAL production
+ // lane: headed Chrome on an auto-booted virtual display (asserts the
+ // anti-bot facts: no Headless UA, no webdriver flag, real viewport).
+ // Everywhere else, the classic headless smoke (no display required).
+ const vdMod = process.platform === "linux" ? await import("./core/vdisplay.js") : null;
+ const useServerMode = !!vdMod && !vdMod.displayUsable() && vdMod.serverModeEnabled() && !!vdMod.xvfbBinary();
+ if (useServerMode) {
+ out("smoke test: server mode — booting a virtual display, launching HEADED Chrome…");
+ } else {
+ out("smoke test: launching headless browser, opening a page, observing…");
+ }
try {
const { Controller } = await import("./core/controller.js");
const c = new Controller();
const html = `data:text/html,<button id="b" onclick="this.textContent='clicked'">go</button><input id="i" value="">`;
- const r = await c.execute("open", { url: html, headless: true, settle_ms: 100 });
+ const r = await c.execute("open", { url: html, ...(useServerMode ? {} : { headless: true }), settle_ms: 100 });
const obs = r.observation;
+ if (useServerMode) {
+ const ua = JSON.parse((await c.execute("evaluate", { expression: "navigator.userAgent" })).value ?? '""');
+ const fp = JSON.parse((await c.execute("evaluate", { expression: "({webdriver: navigator.webdriver, w: innerWidth, h: innerHeight, webgl: !!document.createElement('canvas').getContext('webgl')})" })).value ?? "{}");
+ const antiBotOk = !/headless/i.test(String(ua)) && fp.webdriver === false && fp.w >= 1200;
+ out(`server-mode facts: display ${r.display?.id} (virtual) · UA ${/headless/i.test(String(ua)) ? "CONTAINS Headless (BAD)" : "headed (no Headless substring)"} · navigator.webdriver ${fp.webdriver} · viewport ${fp.w}x${fp.h} · WebGL ${fp.webgl ? "present (SwiftShader)" : "absent"}`);
+ out(`server-mode anti-bot posture: ${antiBotOk && fp.webgl ? "OK — indistinguishable headed build" : "CHECK the facts above"}`);
+ }
const click = await c.execute("click", { target: { ref: "e1" }, settle_ms: 100 });
const ok = /clicked|changed/.test(click.observation?.text ?? "");
out(`smoke test: ${ok ? "OK — observed tree, clicked ref e1, saw the diff" : "partial — observe worked, verify diff below"}`);
diff --git a/src/core/cdp.js b/src/core/cdp.js
index fb21b41..e90e3ec 100644
--- a/src/core/cdp.js
+++ b/src/core/cdp.js
@@ -13,6 +13,7 @@ import { accessSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, st
import { homedir, tmpdir } from "node:os";
import { delimiter, join } from "node:path";
import { AxError, Codes } from "./errors.js";
+import { ensureVirtualDisplay, needsNoSandbox, serverModePlan, virtualDisplayStatus } from "./vdisplay.js";
const SEND_TIMEOUT_MS = 30_000;
@@ -318,6 +319,19 @@ export class BrowserHandle {
try { mkdirSync(profileRoot, { recursive: true }); } catch {}
sweepStaleProfiles(profileRoot);
const dir = persistent ? userDataDir : mkdtempSync(join(profileRoot, "axuse-profile-"));
+ // Server mode (display-less Linux host): boot a private Xvfb and keep
+ // Chrome FULLY HEADED on it. Headless is the detected signal challenge
+ // pages look for first — a virtual display is the anti-bot-safe lane.
+ if (!headless && process.platform === "linux") {
+ const plan = serverModePlan({ headless: false });
+ if (plan.action === "boot") {
+ await ensureVirtualDisplay();
+ } else if (plan.action === "fail-xvfb" || plan.action === "fail-disabled") {
+ throw new AxError(Codes.LAUNCH_FAILED,
+ `Headed Chrome cannot run here: ${plan.reason}.${plan.hint ? ` ${plan.hint}` : ""}`,
+ { retry: "never" });
+ }
+ }
const args = [
`--user-data-dir=${dir}`,
"--remote-debugging-port=0", // ephemeral port, parsed from stderr
@@ -329,6 +343,19 @@ export class BrowserHandle {
"--remote-allow-origins=*", // modern Chrome rejects unknown ws Origins
];
if (headless) args.push("--headless");
+ const vd = virtualDisplayStatus();
+ if (vd.active) {
+ // No monitor is attached to a virtual display: give Chrome a real
+ // desktop viewport instead of the tiny WM-less default, and keep
+ // killed persistent profiles from waking up behind a restore bubble.
+ args.push(`--window-size=${vd.width},${vd.height}`, "--window-position=0,0", "--hide-crash-restore-bubble");
+ // Chrome ≥ 139 ships WITHOUT the software-WebGL fallback (an anti-bot
+ // strong signal on GPU-less hosts): re-enable it so SwiftShader answers
+ // WebGL probes like any real desktop does. No-op when a GPU exists.
+ args.push("--enable-unsafe-swiftshader");
+ const sandbox = needsNoSandbox();
+ if (sandbox.add) args.push("--no-sandbox");
+ }
if (linuxShmUnusable() && !args.includes("--disable-dev-shm-usage")) {
// /dev/shm full/missing: without this the browser dies with SIGTRAP
// before DevTools ever comes up (verified on Ubuntu 22.04).
@@ -439,6 +466,21 @@ export class BrowserHandle {
await this.conn.send("Page.enable", {}, sessionId);
await this.conn.send("Runtime.enable", {}, sessionId);
await this.conn.send("Log.enable", {}, sessionId);
+ // Fingerprint neutralizer (NOT challenge tampering): modern Chrome sets
+ // navigator.webdriver=true merely because a DevTools client exists —
+ // a fingerprint OUR OWN plumbing creates, present on no human-driven
+ // Chrome. This runs before any page script on every new document and
+ // restores the exact value a human-driven browser reports (false).
+ // It does not fake, answer or shortcut any challenge — solvers still
+ // click real widgets with trusted input. Opt out: AXUSE_NEUTRALIZE_WEBDRIVER=0.
+ if (!/^(0|false|off|no)$/i.test(process.env.AXUSE_NEUTRALIZE_WEBDRIVER ?? "")) {
+ try {
+ await this.conn.send("Page.addScriptToEvaluateOnNewDocument", {
+ source: "try { delete navigator.webdriver; } catch {} "
+ + "Object.defineProperty(Navigator.prototype, 'webdriver', { get: () => false, configurable: true });",
+ }, sessionId);
+ } catch { /* older builds: skip, never fail the attach */ }
+ }
// File inputs: intercept the native chooser (it would block forever) and
// let ax_upload answer it with DOM.setFileInputFiles.
try { await this.conn.send("Page.setInterceptFileChooserDialog", { enabled: true }, sessionId); } catch {}
diff --git a/src/core/commands.js b/src/core/commands.js
index 65180ba..9548f30 100644
--- a/src/core/commands.js
+++ b/src/core/commands.js
@@ -27,7 +27,7 @@ export const Contract = Object.freeze({
desc: "Open a URL in a new tab (launches a browser on first use). Returns the FULL accessibility snapshot: one line per element, actionable ones with [ref=eN]. cdp_url attaches to a running Chrome; backend=extension drives the user's own Chrome via the axuse extension.",
params: {
url: { t: "string", req: true, desc: "http(s), file, about, data or blob URL." },
- headless: { t: "boolean", desc: "No window (cdp backend)." },
+ headless: { t: "boolean", desc: "No window (cdp backend). On a display-less Linux server axuse auto-boots a virtual display and stays headed (anti-bot-safe) — keep headless off for challenge pages; use it only for trusted internal pages." },
cdp_url: { t: "string", desc: 'Attach instead of launching, e.g. "http://127.0.0.1:9222".' },
backend: { t: "enum", values: ["cdp", "extension"], desc: "cdp (default) or extension." },
executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },
@@ -43,7 +43,7 @@ export const Contract = Object.freeze({
desc: "Open a bounded list of URLs sequentially and return compact page results. Tabs are closed after each URL by default, so this is safe for source lists and batch inspection. Use ax_open for interactive work on one page.",
params: {
urls: { t: "urls", req: true, desc: "Non-empty list of http(s), file, about, data or blob URLs (maximum 100)." },
- headless: { t: "boolean", desc: "No window (cdp backend)." },
+ headless: { t: "boolean", desc: "No window (cdp backend; display-less Linux servers auto-boot a virtual display instead)." },
cdp_url: { t: "string", desc: 'Attach instead of launching, e.g. "http://127.0.0.1:9222".' },
backend: { t: "enum", values: ["cdp", "extension"], desc: "cdp (default) or extension." },
executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },
diff --git a/src/core/controller.js b/src/core/controller.js
index 4f8dc75..c7b6f6c 100644
--- a/src/core/controller.js
+++ b/src/core/controller.js
@@ -15,6 +15,7 @@ import { AxError, Codes } from "./errors.js";
import { serializeExpression } from "./serialize.js";
import { diffSnapshots, noChangeText } from "./diff.js";
import { captureScreenshot, DEFAULT_BUDGET_BYTES } from "./screenshot.js";
+import { virtualDisplayStatus } from "./vdisplay.js";
import {
click as doClick, hover as doHover, drag as doDrag, wheel as doWheel,
insertText, pressCombo, platformShortcut, selectAllCombo,
@@ -294,7 +295,13 @@ export class Controller {
const tabId = tab.tabId;
await this.navigateInTab(tab, url, a.settle_ms ?? 300);
const observation = await this.observation(tab, { mode: "full" });
- return { browser_id: browser.browserId, tab_id: tabId, observation, dialog: tab.dialog ?? null };
+ // Server-mode fact: headed Chrome on an auto-booted virtual display —
+ // the anti-bot-safe lane on display-less hosts (never --headless).
+ const vd = virtualDisplayStatus();
+ return {
+ browser_id: browser.browserId, tab_id: tabId, observation, dialog: tab.dialog ?? null,
+ ...(vd.active ? { display: { id: vd.display, virtual: true, width: vd.width, height: vd.height } } : {}),
+ };
}
/** Open a bounded source list without forcing the caller to write an MCP
diff --git a/src/core/vdisplay.js b/src/core/vdisplay.js
new file mode 100644
index 0000000..a2e42df
--- /dev/null
+++ b/src/core/vdisplay.js
@@ -0,0 +1,307 @@
+/**
+ * axuse — server mode: headed Chrome on an auto-provisioned virtual display.
+ *
+ * The problem this module exists for: agent harnesses (codex, claude code,
+ * opencode CLIs) run on Ubuntu servers with no desktop session. Challenge /
+ * anti-bot pages (Turnstile, reCAPTCHA, hCaptcha, slider gates) check whether
+ * the browser is headless as their FIRST step — `--headless` is a detection
+ * signal, not a workaround. The supported server lane is the opposite:
+ * launch Chrome FULLY HEADED on a private X virtual framebuffer (Xvfb), so
+ * the browser is a genuine headed build with the real rendering stack
+ * (fonts, raster, WebGL via SwiftShader, window chrome) and no headless
+ * fingerprint anywhere.
+ *
+ * Lineage: the Linux desktop driver already mounts over Xvfb (verified on
+ * Xorg 1.21 / Ubuntu 22.04+, and in CI lanes) — this module brings the same
+ * "private Xvfb, zero extra packages at runtime" pattern to the BROWSER lane
+ * and wires it into BrowserHandle.launch, so every entry point (ax_open,
+ * ax_solve_captcha {url}, plugin ctx.open, axuse solve/open-urls CLIs) gets
+ * it for free.
+ *
+ * Contract (all pure seams are injectable for deterministic tests):
+ * - serverModeEnabled() — AXUSE_SERVER_MODE: auto (default) / 0|off|false
+ * - displayUsable() — DISPLAY is set AND its X socket answers (a dead
+ * DISPLAY, e.g. a stale CI :99, counts as absent)
+ * - serverModePlan() — the decision: native | skip | boot | fail-…
+ * - ensureVirtualDisplay() — boot the singleton: pick a free display
+ * number, spawn Xvfb, wait for its X socket,
+ * export DISPLAY, install exit cleanup
+ * - virtualDisplayStatus() — facts for results, doctor and tests
+ *
+ * Hardening applied on the virtual-display lane (see cdp.js):
+ * - --window-size=W,H and --window-position=0,0 (no monitor → Chrome would
+ * otherwise default to a tiny window on a WM-less screen)
+ * - --hide-crash-restore-bubble (persistent vault profiles that were
+ * killed mid-run must not wake up behind a "restore pages?" bubble)
+ * - --no-sandbox when running as root (Chrome refuses root otherwise —
+ * the norm in containers) or AXUSE_NO_SANDBOX=1
+ * - never --headless, never --disable-gpu (SwiftShader WebGL is an
+ * anti-bot signal you WANT to keep)
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { accessSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { AxError, Codes } from "./errors.js";
+
+export const DEFAULT_DISPLAY_SIZE = "1920x1080x24";
+const X11_SOCKET_DIR = "/tmp/.X11-unix";
+const XVFB_BOOT_TIMEOUT_MS = 5000;
+const XVFB_ATTEMPTS = 3;
+
+/* ------------------------------------------------------------------ config */
+
+/** AXUSE_SERVER_MODE: unset/"auto"/"1" → enabled; "0"/"off"/"false"/"no" → off. */
+export function serverModeEnabled(env = process.env) {
+ const v = String(env.AXUSE_SERVER_MODE ?? "").trim().toLowerCase();
+ return !(v === "0" || v === "off" || v === "false" || v === "no");
+}
+
+/** Parse "WxHxD" (depth optional, default 24) into geometry, or null. */
+export function parseDisplaySize(s) {
+ const m = /^(\d{3,4})x(\d{3,4})(?:x(\d{1,2}))?$/.exec(String(s ?? "").trim());
+ if (!m) return null;
+ const w = Number(m[1]), h = Number(m[2]), d = m[3] ? Number(m[3]) : 24;
+ if (w < 640 || h < 480 || w > 7680 || h > 4320) return null;
+ if (![16, 24, 32].includes(d)) return null;
+ return { w, h, d };
+}
+
+/** The effective virtual-display geometry (AXUSE_DISPLAY_SIZE, validated). */
+export function displayGeometry(env = process.env) {
+ return parseDisplaySize(env.AXUSE_DISPLAY_SIZE) ?? parseDisplaySize(DEFAULT_DISPLAY_SIZE);
+}
+
+/* ------------------------------------------------------- display discovery */
+
+/** DISPLAY ":1", "localhost:10.0", "unix:0" → display number, or null. */
+export function displayNumber(display) {
+ const m = /(?:^|:)(\d+)(?:\.\d+)?$/.exec(String(display ?? "").trim());
+ return m ? Number(m[1]) : null;
+}
+
+/** The X socket path for a display number (filesystem sockets on Linux). */
+export function displaySocketPath(n) {
+ return join(X11_SOCKET_DIR, `X${n}`);
+}
+
+/** DISPLAY is set AND its X server's socket exists. Dead values (stale CI
+ * :99, closed SSH forwards) count as absent — that is what makes the
+ * server-mode fallback safe on machines that HAVE a display variable. */
+export function displayUsable(display = process.env.DISPLAY, { exists = existsSync } = {}) {
+ const n = displayNumber(display);
+ if (n === null) return false;
+ try {
+ return exists(displaySocketPath(n));
+ } catch {
+ return false;
+ }
+}
+
+/** Display numbers already claimed: X sockets + lock files + a few numbers
+ * that conventionally belong to real desktop sessions. */
+export function takenDisplayNumbers({ read = readdirSync } = {}) {
+ const taken = new Set([0, 1, 2]); // native session displays — never take
+ try {
+ for (const name of read(X11_SOCKET_DIR)) {
+ const m = /^X(\d+)$/.exec(name);
+ if (m) taken.add(Number(m[1]));
+ }
+ } catch { /* no socket dir: nothing mounted — fine */ }
+ // Lock files can exist without sockets (crashed X server): scan them too.
+ try {
+ for (const name of read("/tmp")) {
+ const m = /^\.X(\d+)-lock$/.exec(name);
+ if (m) taken.add(Number(m[1]));
+ }
+ } catch { /* /tmp unreadable: extremely unlikely */ }
+ return [...taken];
+}
+
+/** Pick one free display number (injectable randomness for tests). */
+export function pickDisplayNumber({ taken = [], random = Math.random } = {}) {
+ const busy = new Set(taken);
+ for (let i = 0; i < 100; i++) {
+ const n = 20 + Math.floor(random() * 978); // :20–:997, away from :99 CI
+ if (!busy.has(n)) return n;
+ }
+ // Everything drawn was busy (≈ a machine running 900+ X servers): fall back
+ // to the first free number above 1000 rather than fail.
+ for (let n = 1000; n < 1100; n++) if (!busy.has(n)) return n;
+ return null;
+}
+
+/** Locate the Xvfb binary (injectable for deterministic tests). */
+export function xvfbBinary({ which = (b) => spawnSync("which", [b]).status === 0 ? b : null } = {}) {
+ return which("Xvfb");
+}
+
+/* -------------------------------------------------------------- the decision */
+
+/**
+ * Pure decision for one launch: what does the headed lane do on this host?
+ * native — a live X display exists (or not Linux / not our problem)
+ * skip — headless launch; no display needed
+ * boot — auto-boot the private Xvfb (server mode)
+ * fail-xvfb — server mode wanted, Xvfb not installed → typed hint
+ * fail-disabled — AXUSE_SERVER_MODE=0 and no display → typed hint
+ */
+export function serverModePlan({
+ platform = process.platform,
+ headless = false,
+ display = process.env.DISPLAY,
+ usable = null,
+ xvfb = null,
+ enabled = serverModeEnabled(),
+} = {}) {
+ if (platform !== "linux") return { action: "native", reason: "not linux — headed launch is the platform default" };
+ if (headless) return { action: "skip", reason: "headless launch — no display needed" };
+ const alive = usable ?? displayUsable(display);
+ if (alive) return { action: "native", reason: `X display ${display} is alive — headed launch goes there` };
+ if (!enabled) {
+ return {
+ action: "fail-disabled",
+ reason: "server mode is disabled (AXUSE_SERVER_MODE=0) and no X display is alive",
+ hint: "Unset AXUSE_SERVER_MODE (or set it to auto) so axuse boots a private Xvfb, or run the harness inside an X session / under xvfb-run, or pass headless: true for trusted-internal pages only.",
+ };
+ }
+ const hasXvfb = xvfb ?? xvfbBinary();
+ if (!hasXvfb) {
+ return {
+ action: "fail-xvfb",
+ reason: "no X display is alive and Xvfb was not found",
+ hint: "Server mode needs Xvfb for a headed browser: sudo apt-get install -y xvfb (challenge/anti-bot pages detect --headless Chrome — headed-on-Xvfb is the supported server lane). Or run under xvfb-run, or pass headless: true for trusted-internal pages only.",
+ };
+ }
+ return { action: "boot", reason: `no live X display — booting a private Xvfb (headed Chrome, anti-bot-safe)` };
+}
+
+/* ---------------------------------------------------------------- the boot */
+
+let active = null; // the singleton virtual display (this process)
+let booting = null; // one boot at a time (concurrent first launches)
+
+/** Current virtual-display facts: { active, display, width, height, depth }. */
+export function virtualDisplayStatus() {
+ if (!active) return { active: false };
+ const { display, width, height, depth } = active;
+ return { active: true, display, width, height, depth };
+}
+
+/** test hook: drop the singleton (kills the Xvfb we booted, if any). */
+export function __resetVirtualDisplay() {
+ if (active) { try { active.proc.kill(); } catch {} }
+ active = null;
+}
+
+function sleep(ms) { return new Promise((ok) => setTimeout(ok, ms)); }
+
+/** Wait for Xvfb's X socket (its readiness signal) or its early death. */
+async function waitUntilUp(proc, n, timeoutMs = XVFB_BOOT_TIMEOUT_MS) {
+ const path = displaySocketPath(n);
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (proc.exitCode !== null) return false; // died: display raced/flags bad
+ try { accessSync(path); return true; } catch {}
+ await sleep(40);
+ }
+ return false;
+}
+
+/**
+ * Boot the process-wide virtual display (idempotent; concurrent callers share
+ * one boot). Spawns Xvfb on a free display, waits for its socket, exports
+ * DISPLAY for every later spawn (Chrome, xclip, …) and installs exit cleanup.
+ * @returns the active record: { display, width, height, depth, pid, virtual: true }
+ */
+export async function ensureVirtualDisplay({ force = false } = {}) {
+ if (active) return active;
+ if (booting) return booting;
+ booting = (async () => {
+ const plan = serverModePlan({ headless: false });
+ if (plan.action === "native") {
+ throw new AxError(Codes.INTERNAL, "virtual display not needed — a live X display exists");
+ }
+ const bin = xvfbBinary();
+ if (!bin) {
+ throw new AxError(Codes.LAUNCH_FAILED, `Cannot boot server mode: Xvfb was not found. ${plan.hint ?? ""}`, { retry: "never" });
+ }
+ const geo = displayGeometry();
+ const taken = takenDisplayNumbers();
+ for (let attempt = 1; attempt <= XVFB_ATTEMPTS; attempt++) {
+ const n = pickDisplayNumber({ taken });
+ if (n === null) {
+ throw new AxError(Codes.LAUNCH_FAILED, "No free X display number found (100+ displays mounted?) — close some X servers and retry.", { retry: "retry" });
+ }
+ taken.push(n);
+ const display = `:${n}`;
+ // Same proven arg set as the desktop-driver test lane: -ac (no access
+ // control on a private display), -nolisten tcp (never a network port),
+ // -noreset (survive browser restarts within this process's lifetime).
+ const proc = spawn(bin, [
+ display, "-screen", "0", `${geo.w}x${geo.h}x${geo.d}`,
+ "-ac", "-nolisten", "tcp", "-noreset",
+ ], { stdio: "ignore" });
+ // The X server must never keep the harness process alive: unref it.
+ // Teardown is the explicit exit handler below (and process-group
+ // kills / systemd KillMode=control-group — see docs/server-mode.md).
+ proc.unref();
+ if (!(await waitUntilUp(proc, n))) {
+ try { proc.kill(); } catch {}
+ continue; // candidate raced or Xvfb refused it — try the next one
+ }
+ process.env.DISPLAY = display; // the export the whole process sees
+ active = {
+ display, width: geo.w, height: geo.h, depth: geo.d,
+ pid: proc.pid, virtual: true, startedAt: Date.now(), proc,
+ };
+ // Cleanup: normal exits kill our Xvfb. Signal deaths are covered by
+ // process-group kills (the norm for harness/CLI teardown) and by
+ // systemd KillMode=control-group (see docs/server-mode.md).
+ process.once("exit", () => { try { proc.kill(); } catch {} });
+ proc.once("exit", () => { if (active && active.proc === proc) active = null; });
+ return active;
+ }
+ throw new AxError(Codes.LAUNCH_FAILED,
+ `Xvfb died during startup on ${XVFB_ATTEMPTS} candidate displays (check 'Xvfb :990 -screen 0 ${geo.w}x${geo.h}x${geo.d}' by hand, and /tmp space).`,
+ { retry: "retry" });
+ })();
+ try {
+ return await booting;
+ } finally {
+ booting = null;
+ }
+}
+
+/* ------------------------------------------------------------- font probe */
+
+/** --no-sandbox decision for virtual-display launches: root (the norm in
+ * containers — Chrome refuses to start as root otherwise) or explicit. */
+export function needsNoSandbox({ uid = typeof process.getuid === "function" ? process.getuid() : null, env = process.env } = {}) {
+ if (/^(1|true)$/i.test(String(env.AXUSE_NO_SANDBOX ?? ""))) {
+ return { add: true, reason: "AXUSE_NO_SANDBOX=1" };
+ }
+ if (uid === 0) {
+ return { add: true, reason: "running as root — Chrome refuses to start without --no-sandbox" };
+ }
+ return { add: false, reason: uid === null ? "uid unknown" : `uid ${uid}` };
+}
+
+/** Server-render screenshots need real fonts. Count installed font families
+ * via fc-list when present (injectable for tests); 0 or missing → hint. */
+export function fontProbe({ run = (cmd, args) => spawnSync(cmd, args, { timeout: 4000 }) } = {}) {
+ try {
+ const r = run("fc-list", ["--format", "%{family}\n"]);
+ if (r.error || r.status !== 0) return { ok: false, families: 0, note: "fc-list not available (fontconfig not installed)" };
+ const families = new Set(String(r.stdout ?? "").split("\n").map((l) => l.trim()).filter(Boolean));
+ return { ok: families.size > 0, families: families.size };
+ } catch {
+ return { ok: false, families: 0, note: "font probe failed" };
+ }
+}
+
+/** Hint line for a fontless host (boxes instead of glyphs poison vision OCR). */
+export function fontHint(probe) {
+ return probe.ok
+ ? null
+ : `no usable fonts found (${probe.note ?? `${probe.families} families`}) — text renders as boxes and vision/OCR fails: sudo apt-get install -y fonts-liberation fonts-dejavu-core fontconfig`;
+}
diff --git a/src/mcp/manifest.js b/src/mcp/manifest.js
index b4737d7..ba03929 100644
--- a/src/mcp/manifest.js
+++ b/src/mcp/manifest.js
@@ -260,7 +260,7 @@ export function solverTools(loaded) {
description: 'Provider slug, e.g. "turnstile", "recaptcha-v2", "hcaptcha" (from loaded solver plugins).',
},
url: { type: "string", description: "Open this URL in a new tab first (else solve on the active tab)." },
- headless: { type: "boolean", description: "Launch headless when url is given (default headed)." },
+ headless: { type: "boolean", description: "Launch headless when url is given (default headed — keep it: challenge pages detect headless; on display-less servers axuse auto-boots a virtual display so headed works anyway)." },
max_attempts: { type: "number", description: "Solver retry budget (plugin-specific default)." },
deadline_ms: { type: "number", description: "Overall deadline in ms (plugin-specific default)." },
},
diff --git a/src/mcp/render.js b/src/mcp/render.js
index 00b8467..975d639 100644
--- a/src/mcp/render.js
+++ b/src/mcp/render.js
@@ -35,6 +35,7 @@ export function renderResult(command, result) {
if (rest.ok !== undefined) facts.push(rest.ok ? `ok after ${rest.elapsed_ms}ms` : "timeout");
if (rest.filled !== undefined) facts.push(`filled: ${[].concat(rest.filled).join("; ")}${rest.submitted ? `; then clicked ${rest.submitted}` : ""}`);
if (rest.dialog) facts.push(`dialog open: ${rest.dialog.type} "${rest.dialog.message}" — answer with ax_dialog`);
+ if (rest.display?.virtual) facts.push(`display: ${rest.display.id} (virtual ${rest.display.width}x${rest.display.height} — headed on Xvfb, server mode)`);
const parts = [];
if (facts.length) parts.push(facts.join(" · "));
if (rest.note) parts.push(`note: ${rest.note}`);
diff --git a/src/mcp/server.js b/src/mcp/server.js
index 028c839..43422ae 100644
--- a/src/mcp/server.js
+++ b/src/mcp/server.js
@@ -22,18 +22,28 @@ const INSTRUCTIONS = [
"New tabs/popups and JS dialogs opened by an action are reported in its result (answer dialogs with ax_dialog).",
"Screenshots only for pixels (canvas): then click {x,y} page coords.",
"When a verification widget (Turnstile/reCAPTCHA/hCaptcha/slider/interstitial) blocks a page you were asked to drive, call ax_solve_captcha {provider} or ax_challenge {op:\"solve\"} instead of abandoning the task; report the returned facts verbatim (LICENSE_INVALID / NO_SOLVER are expected outcomes the operator can act on).",
+ "Servers: on a display-less host axuse auto-boots a virtual display and keeps Chrome fully headed (anti-bot-safe) — never pass headless for challenge/anti-bot pages; the ax_open result reports the virtual display fact.",
"Capability plugins contribute extra tools (ax_vault, ax_net, ax_guard, ax_extract, …): ax_plugins lists them with their tool names.",
].join("\n");
import { AxError } from "../core/errors.js";
import { browserTools, desktopTools, solverTools, pluginTools } from "./manifest.js";
import { resolveDesktopDriver, desktopUnavailable } from "../desktop/index.js";
import { loadSolvers, buildSolveContext, solveWith, pluginDirs } from "../plugins/index.js";
+import { displayUsable, ensureVirtualDisplay, serverModeEnabled } from "../core/vdisplay.js";
const VERSION = "0.1.0";
const SUPPORTED_PROTOCOL = "2025-03-26";
/** `desktop` resolves once (the macOS driver is the one async case). */
export async function createServer({ controller = new Controller(), desktop, solvers } = {}) {
+ // Server mode (display-less Linux host): boot the virtual display EAGERLY,
+ // before the desktop driver resolves, so the tool surface is complete and
+ // correct from the first tools/list — ax_desktop_* mounts over the same
+ // Xvfb the browser launches on. Typed boot failures (no Xvfb installed)
+ // stay silent here and surface with full context at the first ax_open.
+ if (process.platform === "linux" && serverModeEnabled() && !displayUsable()) {
+ await ensureVirtualDisplay().catch(() => {});
+ }
const driver = desktop !== undefined ? desktop : await resolveDesktopDriver().catch(() => null);
// Solver plugins (paid add-ons) load once at server start: one import per
// plugin dir, typed failures collected for ax_plugins — never fatal.
diff --git a/test/plugins.test.js b/test/plugins.test.js
index f386366..7167265 100644
--- a/test/plugins.test.js
+++ b/test/plugins.test.js
@@ -44,7 +44,7 @@ const CATALOG = [
test("catalog: the paid shared library's own gates pass (curve, ledger, license, vision)", () => {
const dir = join(PLUGINS, "_shared");
if (!existsSync(join(dir, "test"))) return; // fresh clone: no paid tree
- const r = run(["--test", "test/"], dir);
+ const r = run(["--test", "test/*.test.js"], dir);
assert.equal(r.status, 0, r.output);
});
@@ -72,7 +72,7 @@ for (const { id } of CATALOG) {
}
assert.ok(existsSync(join(dir, "test")), `${id} ships no tests`);
assert.ok(existsSync(join(dir, "README.md")), `${id} ships no README`);
- const r = run(["--test", "test/"], dir);
+ const r = run(["--test", "test/*.test.js"], dir);
assert.equal(r.status, 0, `${id} unit suite failed:\n${r.output}`);
});
}
@@ -80,11 +80,19 @@ for (const { id } of CATALOG) {
/** Run `node --test` in a child process, capturing merged output.
* AXUSE_KEYCHAIN=0 severs the macOS Keychain fallback so unit suites are
* deterministic regardless of what the host has stored under service
- * "axuse" (the fallback itself has its own injected-runner tests). */
+ * "axuse" (the fallback itself has its own injected-runner tests).
+ * NODE_TEST_CONTEXT (and friends) MUST be stripped: a `node --test` child
+ * spawned from inside a test file inherits it, Node then believes the run
+ * is recursive and SILENTLY SKIPS every file with a warning and exit 0 —
+ * the catalog suites would pass without ever running (verified live on
+ * Node 22/25). Deleting the marker makes the child a fresh root run.
+ * The glob (not a bare directory) keeps discovery working across Node
+ * versions: Node >= 25 rejects directory args with MODULE_NOT_FOUND. */
function run(args, cwd) {
+ const env = { ...process.env, AXUSE_KEYCHAIN: "0" };
+ for (const k of Object.keys(env)) if (k.startsWith("NODE_TEST_")) delete env[k];
const r = spawnSync(process.execPath, args, {
- cwd, encoding: "utf8", timeout: 600_000, windowsHide: true,
- env: { ...process.env, AXUSE_KEYCHAIN: "0" },
+ cwd, encoding: "utf8", timeout: 600_000, windowsHide: true, env,
});
return { status: r.status, output: `${r.stdout ?? ""}\n${r.stderr ?? ""}` };
}
diff --git a/test/server-mode.test.js b/test/server-mode.test.js
new file mode 100644
index 0000000..db72d44
--- /dev/null
+++ b/test/server-mode.test.js
@@ -0,0 +1,199 @@
+/**
+ * Server mode — the display-less-Linux-host lane: headed Chrome on an
+ * auto-booted private Xvfb (never --headless, which challenge/anti-bot pages
+ * detect as their first step).
+ *
+ * Two lanes:
+ * - unit (always): pure decision seams — size parsing, DISPLAY parsing +
+ * dead-display detection, the launch decision matrix, display-number
+ * picking, env parsing, the no-sandbox decision.
+ * - live (Linux + Xvfb + a browser): the REAL lane end-to-end with a dead
+ * DISPLAY forced in-process — server mode must boot a private Xvfb,
+ * launch Chrome fully headed on it, and expose an anti-bot posture
+ * (no Headless UA, navigator.webdriver false, desktop viewport, WebGL).
+ * The live tests are hermetic: they force a dead DISPLAY value and boot
+ * their own Xvfb; they never touch the operator's session display.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+ parseDisplaySize, displayNumber, displayUsable, displayGeometry,
+ serverModeEnabled, serverModePlan, pickDisplayNumber, takenDisplayNumbers,
+ needsNoSandbox, virtualDisplayStatus, __resetVirtualDisplay,
+} from "../src/core/vdisplay.js";
+import { locateBrowser } from "../src/core/cdp.js";
+import { Controller } from "../src/core/controller.js";
+
+/* ------------------------------------------------------------ unit lane */
+
+test("server mode: display-size parsing accepts only sane geometries", () => {
+ assert.deepEqual(parseDisplaySize("1920x1080x24"), { w: 1920, h: 1080, d: 24 });
+ assert.deepEqual(parseDisplaySize("1366x768"), { w: 1366, h: 768, d: 24 });
+ assert.equal(parseDisplaySize("8000x600"), null); // width over cap
+ assert.equal(parseDisplaySize("320x240"), null); // under floor
+ assert.equal(parseDisplaySize("1920"), null);
+ assert.equal(parseDisplaySize("1920x1080x8"), null); // bad depth
+ assert.equal(parseDisplaySize(""), null);
+ assert.equal(parseDisplaySize(null), null);
+ // geometry falls back to the default when AXUSE_DISPLAY_SIZE is garbage
+ assert.deepEqual(displayGeometry({}), { w: 1920, h: 1080, d: 24 });
+ assert.deepEqual(displayGeometry({ AXUSE_DISPLAY_SIZE: "1280x720x32" }), { w: 1280, h: 720, d: 32 });
+});
+
+test("server mode: DISPLAY parsing and dead-display detection", () => {
+ assert.equal(displayNumber(":1"), 1);
+ assert.equal(displayNumber(":1.0"), 1);
+ assert.equal(displayNumber("localhost:10.0"), 10);
+ assert.equal(displayNumber("unix:0"), 0);
+ assert.equal(displayNumber(""), null);
+ assert.equal(displayNumber(null), null);
+ assert.equal(displayNumber("garbage"), null);
+ // A dead DISPLAY counts as absent — that is what makes the fallback safe
+ // on hosts that carry a stale value (closed SSH forward, dead CI :99).
+ assert.equal(displayUsable(":65530"), false); // no such X socket, ever
+ // Injectable exists seam: a "socket" for :42 → usable
+ assert.equal(displayUsable(":42", { exists: (p) => /\/X42$/.test(p) }), true);
+ assert.equal(displayUsable(":43", { exists: (p) => /\/X42$/.test(p) }), false);
+});
+
+test("server mode: the launch decision matrix is pure and typed", () => {
+ const base = { platform: "linux", headless: false, display: "", usable: false, xvfb: true, enabled: true };
+ assert.equal(serverModePlan({ ...base }).action, "boot");
+ // not linux / headless / live display → no server mode involvement
+ assert.equal(serverModePlan({ ...base, platform: "win32" }).action, "native");
+ assert.equal(serverModePlan({ ...base, headless: true }).action, "skip");
+ assert.equal(serverModePlan({ ...base, usable: true }).action, "native");
+ // dead display + disabled → typed hint naming AXUSE_SERVER_MODE
+ const off = serverModePlan({ ...base, enabled: false });
+ assert.equal(off.action, "fail-disabled");
+ assert.match(off.hint, /AXUSE_SERVER_MODE/);
+ // dead display + no Xvfb → typed install hint
+ const noX = serverModePlan({ ...base, xvfb: false });
+ assert.equal(noX.action, "fail-xvfb");
+ assert.match(noX.hint, /apt-get install -y xvfb/);
+ assert.match(noX.hint, /detect --headless/);
+});
+
+test("server mode: free display numbers are picked away from taken ones", () => {
+ const taken = takenDisplayNumbers();
+ assert.ok(taken.includes(0) && taken.includes(1), "native session displays are never taken");
+ // Deterministic draws: 20 (busy), 21 (busy), then a free one.
+ let i = 0;
+ const seq = () => [0, 1 / 978, 0.5][i++];
+ const n1 = pickDisplayNumber({ taken: [20, 21], random: seq });
+ assert.ok(![20, 21].includes(n1) && n1 >= 20 && n1 <= 997, `picked a free number, got ${n1}`);
+ const n2 = pickDisplayNumber({ taken: [], random: () => 0.5 });
+ assert.ok(n2 >= 20 && n2 <= 997);
+ // taken: everything in the range → falls back above 1000 instead of failing
+ const busy = Array.from({ length: 978 }, (_, k) => 20 + k);
+ assert.ok(pickDisplayNumber({ taken: busy, random: () => 0 }) >= 1000);
+});
+
+test("server mode: AXUSE_SERVER_MODE / no-sandbox env parsing", () => {
+ for (const v of ["", "auto", "1", "true", "on", undefined]) {
+ assert.equal(serverModeEnabled({ AXUSE_SERVER_MODE: v }), true, `enabled: ${v}`);
+ }
+ for (const v of ["0", "off", "false", "no"]) {
+ assert.equal(serverModeEnabled({ AXUSE_SERVER_MODE: v }), false, `disabled: ${v}`);
+ }
+ // no-sandbox: explicit env beats everything; root forces it; otherwise off
+ assert.deepEqual(needsNoSandbox({ uid: 1000, env: { AXUSE_NO_SANDBOX: "1" } }), { add: true, reason: "AXUSE_NO_SANDBOX=1" });
+ assert.equal(needsNoSandbox({ uid: 0, env: {} }).add, true);
+ assert.match(needsNoSandbox({ uid: 0, env: {} }).reason, /root/);
+ assert.equal(needsNoSandbox({ uid: 1000, env: {} }).add, false);
+});
+
+/* ------------------------------------------------------------ live lane */
+
+const linux = process.platform === "linux";
+const xvfb = spawnSync("which", ["Xvfb"]).status === 0;
+const hasBrowser = !!locateBrowser();
+const liveGate = linux && xvfb && hasBrowser;
+const liveSkip = liveGate ? false
+ : "requires Linux + Xvfb + a Chromium-family browser (sudo apt install xvfb; server mode is the display-less Linux lane)";
+const DEAD_DISPLAY = ":988"; // the suite's own dead value (desktop lane uses :977-:980)
+
+/** Force the in-process dead-display world; restores afterwards. */
+function withDeadDisplay() {
+ const savedDisplay = process.env.DISPLAY;
+ const savedMode = process.env.AXUSE_SERVER_MODE;
+ process.env.DISPLAY = DEAD_DISPLAY;
+ process.env.AXUSE_SERVER_MODE = undefined;
+ return () => {
+ if (savedDisplay === undefined) delete process.env.DISPLAY;
+ else process.env.DISPLAY = savedDisplay;
+ if (savedMode === undefined) delete process.env.AXUSE_SERVER_MODE;
+ else process.env.AXUSE_SERVER_MODE = savedMode;
+ __resetVirtualDisplay();
+ };
+}
+
+test("server mode: stays off when disabled (typed failure, no Xvfb boot)", { skip: liveSkip }, async (t) => {
+ const restore = withDeadDisplay();
+ t.after(restore);
+ process.env.AXUSE_SERVER_MODE = "0";
+ const c = new Controller();
+ t.after(() => c.dispose());
+ await assert.rejects(
+ () => c.execute("open", { url: "about:blank", settle_ms: 100 }),
+ (e) => e.code === "LAUNCH_FAILED" && /AXUSE_SERVER_MODE/.test(e.message) && e.retry === "never",
+ );
+ assert.equal(virtualDisplayStatus().active, false, "disabled server mode never boots an Xvfb");
+});
+
+test("server mode: headed Chrome auto-boots a virtual display (anti-bot posture)", { skip: liveSkip }, async (t) => {
+ const restore = withDeadDisplay();
+ t.after(restore);
+ const c = new Controller();
+ t.after(() => c.dispose());
+ const geo = displayGeometry();
+
+ const r = await c.execute("open", {
+ url: "data:text/html,<h1>server mode</h1><button id=\"b\" onclick=\"this.textContent='clicked'\">go</button>",
+ settle_ms: 150,
+ });
+ // The fact the model sees: headed on an auto-booted virtual display.
+ assert.equal(r.display?.virtual, true);
+ assert.match(r.display.id, /^:\d+$/);
+ assert.equal(r.display.width, geo.w);
+ assert.equal(r.display.height, geo.h);
+
+ // Anti-bot posture, measured in the real browser — the whole point of the
+ // lane: a genuine headed build, no headless fingerprint anywhere.
+ const ua = JSON.parse((await c.execute("evaluate", { expression: "navigator.userAgent" })).value ?? '""');
+ const fp = JSON.parse((await c.execute("evaluate", {
+ expression: "({ webdriver: navigator.webdriver, w: innerWidth, h: innerHeight, webgl: !!document.createElement('canvas').getContext('webgl') })",
+ })).value ?? "{}");
+ assert.doesNotMatch(ua, /headless/i);
+ assert.equal(fp.webdriver, false);
+ assert.ok(fp.w >= geo.w - 80, `viewport width ${fp.w} ≈ ${geo.w} (--window-size honored)`);
+ assert.equal(fp.webgl, true, "WebGL present (SwiftShader) — a signal anti-bot checks");
+
+ // Pixels work too (challenge solvers vision-crop from screenshots).
+ const shot = await c.execute("screenshot", { budget_bytes: 60_000 });
+ assert.ok(shot.image.bytes > 2000, "a real rendered frame, not a black void");
+ assert.ok(shot.image.base64.startsWith("/9j/"), "JPEG SOI");
+
+ // The virtual display is a singleton: a second launch reuses it.
+ const r2 = await c.execute("open", { url: "about:blank", settle_ms: 100 });
+ assert.equal(r2.display?.id, r.display.id);
+
+ // And the trusted-input path works on it (the solver lane's primitives).
+ const clicked = await c.execute("click", { target: { x: 8, y: 8 }, settle_ms: 50 });
+ assert.ok(clicked, "input dispatch on the virtual display is fine");
+});
+
+test("server mode: AXUSE_HEADLESS=1 lane still opens headless on a dead display", { skip: liveSkip }, async (t) => {
+ const restore = withDeadDisplay();
+ t.after(restore);
+ const savedHeadless = process.env.AXUSE_HEADLESS;
+ process.env.AXUSE_HEADLESS = "1";
+ t.after(() => { if (savedHeadless === undefined) delete process.env.AXUSE_HEADLESS; else process.env.AXUSE_HEADLESS = savedHeadless; });
+ __resetVirtualDisplay();
+ const c = new Controller();
+ t.after(() => c.dispose());
+ const r = await c.execute("open", { url: "about:blank", settle_ms: 100 });
+ assert.equal(r.display, undefined, "headless launches never report a virtual display");
+ assert.equal(virtualDisplayStatus().active, false, "headless needs no display — none was booted");
+});
diff --git a/test/skip-allowlist.json b/test/skip-allowlist.json
index b71d980..799e92d 100644
--- a/test/skip-allowlist.json
+++ b/test/skip-allowlist.json
@@ -4,6 +4,7 @@
"desktop driver: screen_info reports a usable native coordinate space": "platform-or-gate: Windows live driver, or macOS with AXUSE_TEST_MACOS_DESKTOP=1",
"desktop driver: budgeted screenshot of a small region": "platform-windows: Windows-only live screenshot",
"linux desktop: driver drives a private Xvfb (input, capture, windows)": "platform-linux-xvfb: spawns a private Xvfb (sudo apt install xvfb); never touches the operator session",
+ "server mode: ": "platform-linux-xvfb: the display-less Linux lane (sudo apt install xvfb + a browser); live tests force a dead DISPLAY and boot a private Xvfb — hermetic, never touches the operator session",
"linux desktop: JPEG decodes in an independent decoder when PIL exists": "platform-linux-xvfb: spawns a private Xvfb; PIL verified when present",
"atspi: snapshot + read round-trip on a live app (read-only)": "platform-linux-atspi: needs the session's at-spi2 registry (DBUS_SESSION_BUS_ADDRESS); bare Xvfb/CI has none — read-only, never acts",
"atspi: action sandbox — snapshot, ax_set, ax_click on a private bus+Xvfb+GTK app": "platform-linux-gtk-sandbox: needs Xvfb + dbus-run-session + python3-gi Gtk3 (CI installs them); fully isolated private bus",