agent-browser

Ein gehärteter lokaler Browser für KI-Agenten. Null Abhängigkeiten. Steuert das Chrome, das du bereits hast, über das DevTools-Protokoll, extrahiert token-effizientes Markdown und wird nicht trivial als Automatisierung erkannt.

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

Alles läuft lokal. Kein Konto, kein API-Schlüssel, kein Remote-Dienst, kein Kontingent.

Warum

Einen Agenten mit rohem HTML zu füttern verschwendet den Großteil seines Kontexts. Gemessen auf echten Seiten:

Und ein Browser, der sich als Automatisierung zu erkennen gibt, wird blockiert, degradiert oder mit anderen Inhalten bedient – was stillschweigend das korrumpiert, was der Agent daraus geschlossen hat.

Related MCP server: Browser-MCP Navigator

Installieren

Als MCP-Server

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

Tools: browser_markdown, browser_text, browser_html, browser_links, browser_screenshot, browser_evaluate, browser_accessibility_tree, browser_pdf, browser_probe.

Als Bibliothek

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

Als DSH-/Cordis-Plugin

Einzeiler (empfohlen – verdrahtet automatisch, wenn du DSH wirklich meinst):

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

Starte dsh neu – browser_markdown, browser_text, browser_links, browser_evaluate, browser_screenshot, browser_probe erscheinen als native Tools. Kein Handler läuft bei einem einfachen npm install; eine absichtliche install ist erforderlich.

Manuell (falls du die Komposition lieber selbst bearbeitest):

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

Erfordert Node ≥ 18 und eine Chrome/Chromium-Installation. Füge dann zur Host-Komposition hinzu (das Tool-Registry liegt auf dem Host, nicht pro Agent):

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

Kurzform (wenn die Komposition bereits insert umschließt):

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

Env-Overrides: AGENT_BROWSER_BIN (Chrome-Binary), AGENT_BROWSER_ENDPOINT (an langlebigen Browser anhängen via --endpoint), oder config.cli.

CLI

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

Optionen: --headful, --no-stealth, --block-images, --gpu/--no-gpu, --width, --height, --viewport WxH, --main, --raw, --full, --endpoint <ws>, --timeout, --json, -o.

--endpoint hängt sich an einen bereits laufenden Browser an, statt einen zu starten – nützlich, um einen einzelnen langlebigen Browser über viele Aufrufe hinweg wiederzuverwenden.

Bot-Erkennung

Führe es selbst aus: npm run test:bot. Letztes Ergebnis:

Normales Headless-Chrome fällt bei vier sannysoft-Zeilen durch (HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, alte UA) und wird als Bot gemeldet.

Ein nicht erreichbarer Detektor zählt als ÜBERSPRUNG, nie als bestanden, und das Tor erfordert drei erreichbare Bestehen – ein Tag, an dem die Testseiten nicht erreichbar sind, kann also nicht als Erfolg fehlinterpretiert werden.

Die Umgebung zählt mehr als das Patchen

Der identische Code, an zwei Orten gemessen:

Jedes CDP-Signal bleibt in beiden Fällen sauber – das ist Code, und der Code ist richtig. Was das Urteil kippt, ist die Umgebung: eine Rechenzentrums-ASN plus Software-Rendering löst einen Schwachsignal-Verbund aus, den kein noch so viel Fingerprint-Patching behebt.

Das ist die ehrliche Form des Problems. Den Browser zu härten entfernt die trivialen Hinweise. Wo du ihn ausführst, entscheidet den Rest.

Was die Härtung tut, und warum

Jeder Punkt kam von einem Detektor, der uns sagte, dass wir falsch lagen:

• Kein --enable-automation. Dieses Flag – das Puppeteer und Playwright hinzufügen – setzt navigator.webdriver = true. Rohes CDP setzt es nicht, also bleibt es false, ohne dass etwas gepatcht wird.

• Kein Runtime.enable. Es ist der lauteste CDP-Hinweis und treibt den klassischen Console/Error.stack-Detektor an. Runtime.evaluate funktioniert auch ohne.

• Fenster und Bildschirm bewegen sich zusammen. --window-size ohne --ozone-override-screen-size ergibt outerWidth > screen.width, was physikalisch unmöglich ist – ein stärkeres Signal als normales Headless.

• Kein Standard-Device-Metrics-Override. Die übliche 1280×720 ist Playwrights Standard-Viewport und Detektoren markieren sie namentlich. Setze --viewport nur, wenn du es brauchst.

• Echte GPU, wenn verfügbar, was einen echten ANGLE (NVIDIA …)-Renderer statt SwiftShader ergibt.

• UA beim Start gesetzt, nicht nur über CDP. Emulation.setUserAgentOverride erreicht keine Web-Worker, also meldet ein Worker weiterhin die Headless-UA, während die Seite die saubere meldet (hasInconsistentWorkerValues).

• Kein acceptLanguage-Override. CDP leitet navigator.languages durch Aufteilen dieses Headers ab, also wird "en-US,en;q=0.9" zu ["en-US","en;q=0.9"] – ein q-Wert, der legal nicht existieren kann, und eine weitere Seite/Worker-Diskrepanz. --lang macht es korrekt.

• Client-Hints, abgeleitet aus der Version des Binaries selbst, sodass Sec-CH-UA nicht mit navigator.userAgent kollidieren kann.

• Isolierter Browser-Kontext pro Sitzung, beim Schließen verworfen – sauberer Zustand pro Aufgabe ohne einen zweiten Browserprozess.

Die wiederkehrende Lektion: Konsistenz schlägt Abdeckung. Vier davon sind Fälle, in denen teilweises Spoofing die Erkennung erleichterte, was nur durch das Ausführen echter Detektoren auffiel.

Warum WebGL-Spoofing standardmäßig deaktiviert ist

spoofWebgl existiert und ist sorgfältig implementiert – ein Proxy um natives getParameter, sodass Function.prototype.toString weiterhin [native code] meldet. Es ist deaktiviert, weil Messungen zeigen, dass es nach hinten losgeht. Aus test/webgl-spoof-experiment.mjs:

Hardware zu behaupten, die man nicht hat, behebt eine kosmetische Zeile und lässt den Verbund-Detektor fehlschlagen: Das injizierte Skript erreicht keine Web-Worker, also meldet der Worker weiterhin SwiftShader, und MAX_TEXTURE_SIZE bleibt beim Software-Wert, während die Renderer-Zeichenkette eine diskrete GPU behauptet.

Ehrliches SwiftShader besteht. Eine überzeugende Lüge nicht. Gib dem Browser stattdessen eine echte GPU – es ist kostenlos.

Was das NICHT tut

Fingerprint-Ebene-Erkennung ist der gesamte Umfang. Es besiegt nicht, und versucht nicht zu besiegen:

• TLS/JA3-JA4 und HTTP/2-Fingerprinting – entschieden, bevor irgendein JavaScript läuft

• IP-Reputation – Rechenzentrum vs. Wohn-ASN, oft der eigentliche Blocker

• Verhaltensanalyse – Mauspfade, Timing, Verweildauer

Kommerzielle Challenge-Produkte stützen sich auf diese, also bedeutet „das Gate bestehen“ nicht trivial als Automatisierung markiert, niemals unerkennbar. Gedacht für deine eigenen Seiten, Tests, Barrierefreiheitsarbeit und gewöhnliches Agenten-Browsing.

Speicher

Ein Chrome-Stack kostet ungefähr 450 MB. Der Hebel ist Architektur, nicht Flags: einen Browser und viele isolierte Kontexte statt einen Browser pro Aufgabe. Starte einen Browser einmal und richte dann jeden Aufruf mit --endpoint / AGENT_BROWSER_ENDPOINT darauf aus. --block-images hilft bei Textarbeit.

Null Abhängigkeiten

dependencies ist leer, einschließlich des WebSocket-Transports.

Node's globales WebSocket (WHATWG) kann keine Request-Header senden, was jeder authentifizierte oder proxierte CDP-Endpunkt benötigt, und undici ist nicht eigenständig importierbar. Also implementiert src/ws.mjs RFC 6455 direkt über node:http(s) – Handshake, Maskierung, Fortsetzungsfragmente, 64-Bit-Längen, Ping/Pong – was alles ist, was CDP benötigt.

Der Markdown-Konverter durchläuft das DOM mit einem expliziten Stack, hält die JS-Aufruftiefe bei O(1) unabhängig von der Verschachtelung und verwendet natives innerText für Blattknoten. Das macht ihn sowohl rekursionssicher bei tief verschachtelten Dokumenten als auch deutlich schneller auf großen Seiten.

Umgebung

Anforderungen

Node ≥ 18 und eine Chrome/Chromium-Installation. Kein Build-Schritt.

Danksagungen

Die Härtung dieses Projekts ist fast vollständig aus veröffentlichten Erkennungsforschungen anderer abgeleitet – siehe CREDITS.md. Besonderer Dank an rebrowser-bot-detector, bot.sannysoft.com, deviceandbrowserinfo.com und Camoufox dafür, dass sie gezeigt haben, wie man es richtig macht.

Lizenz

MIT# agent-browser

Ein gehärteter lokaler Browser für KI-Agenten. Null Abhängigkeiten. Steuert das Chrome, das du bereits hast, über das DevTools-Protokoll, extrahiert token-effizientes Markdown und wird nicht trivial als Automatisierung erkannt.

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

Alles läuft lokal. Kein Konto, kein API-Schlüssel, kein externer Dienst, keine Kontingente.

Warum

Das Füttern eines Agenten mit rohem HTML verschwendet den Großteil seines Kontexts. Gemessen auf echten Seiten:

Und ein Browser, der sich als Automatisierung zu erkennen gibt, wird blockiert, degradiert oder mit anderen Inhalten bedient – was stillschweigend das korrumpiert, was der Agent daraus geschlossen hat.

Installieren

Als MCP-Server

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

Tools: browser_markdown, browser_text, browser_html, browser_links, browser_screenshot, browser_evaluate, browser_accessibility_tree, browser_pdf, browser_probe.

Als Bibliothek

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

Als DSH-/Cordis-Plugin

Einzeiler (empfohlen – verdrahtet automatisch, wenn du DSH wirklich meinst):

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

Starte dsh neu – browser_markdown, browser_text, browser_links, browser_evaluate, browser_screenshot, browser_probe erscheinen als native Tools. Kein Handler läuft bei einem einfachen npm install; eine absichtliche install ist erforderlich.

Manuell (falls du die Komposition lieber selbst bearbeiten möchtest):

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

Benötigt Node ≥ 18 und eine Chrome/Chromium-Installation. Füge dann zur Host-Komposition hinzu (das Tool-Registry liegt auf dem Host, nicht pro Agent):

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

Kurzform (wenn die Komposition bereits insert umschließt):

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

Env-Overrides: AGENT_BROWSER_BIN (Chrome-Binary), AGENT_BROWSER_ENDPOINT (an langlebigen Browser anhängen via --endpoint), oder config.cli.

CLI

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

Optionen: --headful, --no-stealth, --block-images, --gpu/--no-gpu, --width, --height, --viewport WxH, --main, --raw, --full, --endpoint <ws>, --timeout, --json, -o.

--endpoint hängt sich an einen bereits laufenden Browser an, statt einen zu starten – nützlich, um einen einzelnen langlebigen Browser über viele Aufrufe hinweg wiederzuverwenden.

Bot-Erkennung

Führe es selbst aus: npm run test:bot. Letztes Ergebnis:

Normales Headless-Chrome fällt bei vier sannysoft-Zeilen durch (HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, alte UA) und wird als Bot gemeldet.

Ein nicht erreichbarer Detektor zählt als ÜBERSPRUNG, nie als bestanden, und das Gate erfordert drei erreichbare Bestehen – ein Tag, an dem die Testseiten nicht erreichbar sind, kann also nicht als Erfolg missverstanden werden.

Umgebung zählt mehr als Patchen

Der identische Code, gemessen an zwei Orten:

Jedes CDP-Signal bleibt in beiden Fällen sauber – das ist Code, und der Code ist richtig. Was das Urteil kippt, ist die Umgebung: eine Rechenzentrums-ASN plus Software-Rendering löst einen Schwachsignal-Verbund aus, den kein noch so vieles Fingerprint-Patchen behebt.

Das ist die ehrliche Form des Problems. Den Browser zu härten entfernt die trivialen Hinweise. Wo du ihn ausführst, entscheidet den Rest.

Was die Härtung tut, und warum

Jeder Punkt kam von einem Detektor, der uns sagte, dass wir falsch lagen:

• Kein --enable-automation. Dieses Flag – das Puppeteer und Playwright hinzufügen – setzt navigator.webdriver = true. Rohes CDP setzt es nicht, also bleibt es false, ohne dass etwas gepatcht wird.

• Kein Runtime.enable. Es ist der lauteste CDP-Hinweis und treibt den klassischen Console/Error.stack-Detektor an. Runtime.evaluate funktioniert auch ohne.

• Fenster und Bildschirm bewegen sich zusammen. --window-size ohne --ozone-override-screen-size ergibt outerWidth > screen.width, was physikalisch unmöglich ist – ein stärkeres Signal als normales Headless.

• Kein Standard-Device-Metrics-Override. Die übliche 1280×720 ist Playwrights Standard-Viewport und Detektoren markieren ihn namentlich. Setze --viewport nur, wenn du es brauchst.

• Echte GPU, wenn verfügbar, was einen echten ANGLE (NVIDIA …)-Renderer statt SwiftShader ergibt.

• UA beim Start gesetzt, nicht nur über CDP. Emulation.setUserAgentOverride erreicht keine Web-Worker, also meldet ein Worker weiterhin die Headless-UA, während die Seite die saubere meldet (hasInconsistentWorkerValues).

• Kein acceptLanguage-Override. CDP leitet navigator.languages durch Aufteilen dieses Headers ab, also wird "en-US,en;q=0.9" zu ["en-US","en;q=0.9"] – ein q-Wert, der legal nicht existieren kann, und eine weitere Seite/Worker-Diskrepanz. --lang macht es korrekt.

• Client-Hints, die aus der eigenen Version des Binaries abgeleitet werden, sodass Sec-CH-UA nicht mit navigator.userAgent kollidieren kann.

• Isolierter Browser-Kontext pro Sitzung, beim Schließen verworfen – sauberer Zustand pro Aufgabe ohne einen zweiten Browserprozess.

Die wiederkehrende Lektion: Konsistenz schlägt Abdeckung. Vier davon sind Fälle, in denen teilweises Spoofing die Erkennung erleichterte, nur durch echte Detektoren aufgedeckt.

Warum WebGL-Spoofing standardmäßig deaktiviert ist

spoofWebgl existiert und ist sorgfältig implementiert – ein Proxy um natives getParameter, sodass Function.prototype.toString weiterhin [native code] meldet. Es ist deaktiviert, weil Messungen sagen, dass es nach hinten losgeht. Aus test/webgl-spoof-experiment.mjs:

Hardware zu behaupten, die du nicht hast, behebt eine kosmetische Zeile und lässt den Verbund-Detektor fehlschlagen: Das injizierte Skript erreicht keine Web-Worker, also meldet der Worker weiterhin SwiftShader, und MAX_TEXTURE_SIZE bleibt beim Softwarewert, während die Renderer-Zeichenkette eine diskrete GPU behauptet.

Ehrliches SwiftShader besteht. Eine überzeugende Lüge nicht. Gib dem Browser stattdessen eine echte GPU – es ist kostenlos.

Was das NICHT tut

Fingerprint-Ebene-Erkennung ist der gesamte Umfang. Es besiegt nicht, und versucht nicht zu besiegen:

• TLS/JA3-JA4 und HTTP/2-Fingerprinting – entschieden, bevor irgendein JavaScript läuft

• IP-Reputation – Rechenzentrum vs. privat, oft der eigentliche Blocker

• Verhaltensanalyse – Mauspfade, Timing, Verweildauer

Kommerzielle Challenge-Produkte stützen sich auf diese, also bedeutet „das Gate bestehen“ nicht trivial als Automatisierung markiert zu werden, nie unerkennbar. Gedacht für deine eigenen Seiten, Tests, Barrierefreiheitsarbeit und gewöhnliches Agenten-Browsing.

Speicher

Ein Chrome-Stack kostet ungefähr 450 MB. Der Hebel ist Architektur, nicht Flags: ein Browser und viele isolierte Kontexte statt ein Browser pro Aufgabe. Starte einen Browser einmal, dann richte jeden Aufruf mit --endpoint / AGENT_BROWSER_ENDPOINT darauf. --block-images hilft bei Textarbeit.

Null Abhängigkeiten

dependencies ist leer, einschließlich des WebSocket-Transports.

Nodes globales WebSocket (WHATWG) kann keine Request-Header senden, was jeder authentifizierte oder proxierte CDP-Endpunkt benötigt, und undici ist nicht eigenständig importierbar. Also implementiert src/ws.mjs RFC 6455 direkt über node:http(s) – Handshake, Maskierung, Fortsetzungsfragmente, 64-Bit-Längen, Ping/Pong – was alles ist, was CDP benötigt.

Der Markdown-Konverter durchläuft das DOM mit einem expliziten Stack, hält die JS-Aufruftiefe bei O(1) unabhängig von der Verschachtelung, und verwendet natives innerText für Blattknoten. Das macht ihn sowohl rekursionssicher auf tief verschachtelten Dokumenten als auch deutlich schneller auf großen Seiten.

Umgebung

Anforderungen

Node ≥ 18 und eine Chrome/Chromium-Installation. Kein Build-Schritt.

Danksagungen

Die Härtung dieses Projekts ist fast vollständig aus veröffentlichten Erkennungsforschungen anderer abgeleitet – siehe CREDITS.md. Besonderer Dank an rebrowser-bot-detector, bot.sannysoft.com, deviceandbrowserinfo.com und Camoufox dafür, dass sie zeigen, wie man es richtig macht.

Lizenz

MIT