NOMOS Browser

Der Browser deines Agents, mit dir im Raum.

Governierte Browser-Infrastruktur für KI-Agenten. Der Browser wird zu einer Plattformressource, nicht zu einem Spielzeug, das an ein Modell gekoppelt ist — und der Besitzer sieht, autorisiert und unterbricht, was der Agent tut.

0.3.0-rc.2 · MIT · Node ≥ 22.6 · Chromium via Playwright · ohne Build-Schritt

Das Problem

Einem Agenten die Macht zu geben, einen Browser zu nutzen, heißt ihm die Macht zu geben, im Namen von jemandem zu kaufen, zu senden, zu löschen und Daten leaken zu lassen. Das wird meist auf zwei schlechte Arten gelöst:

• blindes Vertrauen — der Agent handelt und der Besitzer erfährt es danach;

• Lähmung — der Agent fragt alles, und der Besitzer klickt „Ja" im Automatismus, bis die Genehmigung zum Reflex wird.

Der NOMOS Browser trennt das, was der Besitzer bereits autorisiert hat von dem, was jetzt Zustimmung braucht, und macht den Unterschied sichtbar, auditierbar und umkehrbar.

Related MCP server: gaze

Wie es aussieht

NOMOS · Claude · Gemini · Qwen · Ollama · agente próprio
                        │
      MCP  ·  REST v1  ·  WebSocket  ·  SDK  ·  CLI  ·  Live Agent Console
                        │
              NOMOS BROWSER RUNTIME
        política → autonomia → aprovação → auditoria
                        │
                 Playwright · CDP
                        │
                     Chromium

Der Navigationszustand gehört dem Runtime, nicht dem Modell. Der Agent trennt sich, stirbt oder wird durch einen anderen von einem anderen Anbieter ersetzt: Die Sitzung bleibt am Leben, mit denselben Tabs, Cookies und Tasks.

Funktionen

Demo

Die Live Agent Console wird vom Runtime selbst auf derselben Origin mit CSP connect-src 'self' ausgeliefert — es gibt kein permissives CORS zum Ausnutzen.

node packages/api/src/daemon.ts
# abra a URL com o token que o daemon imprime

Reproduzierbare Abläufe mit erwartetem Ergebnis findest du in docs/demos.md.

Installation

npm ci --include=dev
npx playwright install chromium

--include=dev ist keine Dekoration: Mit NODE_ENV=production oder npm config omit=dev überspringt npm ci die devDependencies und der Typecheck schlägt danach mit "This is not the tsc command you are looking for" fehl. Details in docs/INSTALLATION.md.

Es gibt keinen Build-Schritt für das Runtime: Node führt TypeScript nativ aus. Die Oberfläche hat einen eigenen Schritt (node packages/ui/build.ts), weil sie bei jeder Generierung die Markentokens aus dem Tresor liest.

Quick start

# 1. subir o runtime
node packages/api/src/daemon.ts &

# 2. estado
node packages/cli/src/main.ts health

# 3. abrir uma página (a sessão nasce com a política padrão)
node packages/cli/src/main.ts open https://example.com

# 4. ver o que ficou gravado
node packages/cli/src/main.ts sessions
node packages/cli/src/main.ts replay <SESSION_ID>

Die CLI gewährt niemals sensible Capabilities: Eine von ihr erstellte Sitzung wird mit verweigertem Download, Upload, Send, Purchase, Payment und Delete geboren.

Beispiele

# capturar a tela de uma sessão
node packages/cli/src/main.ts screenshot <SESSION_ID> --out /tmp/tela.png

# entregar um objetivo ao agente
node packages/cli/src/main.ts task --session <SESSION_ID> "encontre o preço do plano anual"

# acompanhar os eventos ao vivo
node packages/cli/src/main.ts events --session <SESSION_ID>

# verificar a integridade do replay gravado
node packages/cli/src/main.ts replay verify <SESSION_ID>

ASK und AUTO

Die Hierarchie, und die Reihenfolge ist die Garantie:

POLÍTICA DO DONO → MODO DE AUTONOMIA → CAPABILITY DO NOMOS → GATES DE APROVAÇÃO → AÇÃO

ASK — fragen

Lesezugriffe gehen direkt durch. Jede Aktion, die die Seite verändert, stoppt und fragt, mit Konsequenz und Ressource auf Portugiesisch geschrieben, damit die Entscheidung bewusst ist und kein Reflexklick.

Eine browser.task zu genehmigen ist kein Blankoscheck: Jeder Schritt, den der Plan auszuführen beschließt, tritt erneut in das Tor ein.

AUTO — handeln ohne zu fragen

Der Agent führt selbstständig alles aus, was du durch deine Richtlinie bereits autorisiert hast. Was sich nicht ändert:

• Aktionen mit finanzieller Wirkung, externem Versand oder hoher Irreversibilität fragen weiterhin nach Genehmigung — browser.upload fragt in AUTO, weil es deine Daten nach außen sendet, und das lässt sich nicht zurücknehmen;

• eine Route ohne deklariertes Risikoprofil fällt auf „immer genehmigen" (fail-closed);

• wenn der Autonomiezustand nicht nachgewiesen werden kann (Runtime ausgefallen, Wiederverbindung), zeigt die Oberfläche niemals AUTO: Sie fällt auf unbekannt zurück und behandelt es als ASK.

AUTO != BYPASS ist kein Dokumentationsversprechen. Das Autonomietor läuft nach Capability und menschlicher Kontrolle: Wenn es ausführt, hat alles, was die Richtlinie verweigert, bereits 403 zurückgegeben. Es gibt keinen Codezweig, der ein deny in ein allow verwandelt.

Mehr in docs/ask-mode.md und docs/auto-mode.md.

Sicherheit

• Token-Authentifizierung mit Scopes (OBSERVE, NAVIGATE, INPUT, DOWNLOAD, UPLOAD, SECRET, CONTROL, ADMIN). Jede Route hat einen deklarierten Scope; keine lebt vom Default.

• Wer handelt, autorisiert nicht. Das Agentprofil erreicht weder Genehmigen, Modusdelegieren noch Fortsetzen. Stoppen schon: pause und emergency-stop dürfen nie schwieriger sein als Handeln.

• Fail-closed-Richtlinie pro Capability, mit verweigertem A6_DESTRUCTIVE.

• Anti-SSRF: Zu einem internen Host zu navigieren ist ein expliziter Akt, nie abgeleitet.

• Anti-Injection-Provenienz im Ausführungspfad: observe und extract geben provenance zurück.

• Obligatorischer Kontroll-Lease (allow_unleased: false).

• Geheimnisse erscheinen weder in der Oberfläche, im Audit noch im Replay.

Das Bedrohungsmodell T1–T10, mit deklarierten Resten, findest du in docs/SECURITY.md.

Nichts hier behauptet „100% sicher". Keine Maßnahme stützt das, und keine wird es je stützen.

Audit und Replay

Spur mit 19 Feldern pro Aktion, hash-verkettet, mit Geheimnis-Schwärzung an der Quelle. Beim Beenden wird die Sitzung versiegelt.

Das Replay ist in drei unabhängigen Ebenen schreibgeschützt: Es gibt kein Schreibverb auf der Route (405 + Allow: GET); das Lesen des Verlaufs erweckt die Sitzung nicht wieder; und der Modus wird deklariert vom Runtime, nicht vom Bildschirm abgeleitet.

Es ist auch ehrlich über das eigene Lesen: Es meldet beschädigte Zeilen und fehlende Quellen, statt eine kürzere Zeitleiste zurückzugeben, die sich als vollständig ausgibt. Eine Sitzung, die nie existiert hat, ist 404, kein leeres Replay mit 200.

Siehe docs/audit-and-replay.md.

MCP

16 Tools, ohne Modellkopplung:

browser_navigate · browser_observe · browser_find · browser_extract · browser_screenshot · browser_click · browser_type · browser_press · browser_scroll · browser_tabs · browser_tab_open · browser_tab_switch · browser_tab_close · browser_download · browser_upload · browser_task

Im NOMOS-Ökosystem ist der Browser eine Capability, die von der Richtlinie des Besitzers regiert wird, mit signiertem Katalog und Vertrauen durch Fingerabdruck des normalisierten Manifests. Siehe docs/mcp.md und docs/NOMOS-INTEGRATION.md.

Konfiguration

51 Schlüssel, vom Runtime selbst abfragbar:

curl -s localhost:7777/api/v1/config/schema   # a FORMA (pública)
curl -s localhost:7777/api/v1/config          # os VALORES efetivos (ADMIN)

Die Trennung ist bewusst: „Was existiert?" kann jedem Träger beantwortet werden; „Was gilt hier?" nicht. Siehe docs/CONFIGURATION.md.

Troubleshooting

Symptom → Ursache → Überprüfung → Korrektur in docs/TROUBLESHOOTING.md.

Entwicklung

npx tsc --noEmit                    # tipos
bash scripts/run-suite.sh           # suíte inteira, um arquivo por vez
bash scripts/run-suite.sh --fast    # pula browser/bench
bash scripts/regressao-completa.sh  # 15 etapas, um veredito
bash scripts/limpar-orfaos.sh       # higiene por prova de posse

Verwende den Executor, nicht node --test tests/ direkt. Der Node-Runner parallelisiert pro CPU; unter Speicherdruck stirbt der Prozess mitten in der Ausführung und hinterlässt eine abgeschnittene Ausgabe ohne Zusammenfassungszeile, die wie Erfolg aussieht. run-suite.sh führt eine Datei nach der anderen aus, und eine tote Datei erscheint als MORTO.

Tests

Gemessen bei HEAD 6964cf0:

suíte TypeScript     789 passes · 0 falhas · 37/37 arquivos
E2E do Live Agent    106 casos  · 9 baterias
sala limpa           14/14 passos, a partir de clone do HEAD
regressão completa   15 etapas · 0 falha · 0 não-executada

Das Projekt weigert sich, das als PASS zu bezeichnen, was nicht beobachtet wurde. Zwei Beispiele:

Die Browserkontrolle ist real. Ein von JavaScript synthetisierter Klick erreicht die Seite mit isTrusted=false; einer, der über CDP ausgelöst wird, mit true. Der Spike testet beide — der zweite beweist die Kontrolle, der erste beweist, dass der Test kein Vakuum ist.

Der Genehmigungszähler ist nicht blind. Unter Produktmutation geht UNEXPECTED_APPROVAL_PROMPTS von 0 auf 3 und auf 5, je nach injiziertem Defekt. Ein Zähler, der unter Mutation bei null bliebe, würde nichts messen.

Bekannte Einschränkungen

• p99 wird auf keinem Latenzpfad berichtet: 30 Stichproben erfordern 100, um ein p99 zu stützen. Kein beobachtetes Maximum wird p99 genannt.

• Es gibt keine HTTP-Route zum Ausstellen eines Tokens mit Scope — sie existiert in der internen API.

• Der Zweig pr.page.isClosed() ist im Normalbetrieb unerreichbar; er ist Rennverteidigung, keine Abdeckung.

• Die Statusleiste der Oberfläche aktualisiert per 700-ms-Polling. Die Ereignisse kommen in ~1 ms an; die Leiste nicht.

• Validierung auf macOS/Apple Silicon. Andere Plattformen wurden nicht gemessen.

Die vollständige Liste mit Zahlen findest du in docs/LIMITATIONS.md, und was PROVEN gegenüber MEASURED oder NOT PROVEN ist, steht in PRODUCT_TRUTH_MATRIX.md.

Roadmap

In ROADMAP.md. Was dort steht, sind legitime Schulden, keine Terminversprechen.

Dokumentation

Beginne hier

Referenz

Marke

Die Marke NOMOS ist in v1.0 eingefroren und der offizielle Resolver antwortet rc=0. Die Tokens werden bei jedem Build aus dem Tresor gelesen und nicht in diesem Repository versioniert — das Kopieren von Marken-Tokens in eine Zwischendatei ist durch den Governance-Vertrag verboten. Siehe docs/BRAND.md.

Lizenz

MIT. Siehe LICENSE. Inhaber: Voltolini-SPACE.

Die Lizenz deckt den Code ab. Sie gewährt keine Rechte an den Marken „NOMOS" und „NOMOS Browser" noch an den Tokens der visuellen Identität, die separat verwaltet und hier nicht versioniert werden. Details in NOTICE.md.

Bis 2026-08-25 erklärte dieses Repository „Alle Rechte vorbehalten" mit einem Platzhalter-Inhaber. Beides war eine Entscheidung des Eigentümers und wurde entschieden.

Teil des NOMOS-Ökosystems · voltolini.space