NOMOS Browser

Your agent's browser, with you in the room.

Governed browsing infrastructure for AI agents. The browser becomes a platform resource, not a toy bolted onto a model — and the owner sees, authorizes, and interrupts what the agent does.

0.3.0-rc.2 · MIT · Node ≥ 22.6 · Chromium via Playwright · no build step

The problem

Giving an agent the power to use a browser is giving it the power to buy, send, delete, and leak on someone's behalf. This is usually solved in two bad ways:

• blind trust — the agent acts and the owner finds out later;

• paralysis — the agent asks about everything, and the owner clicks "yes" on autopilot until approval becomes a reflex.

NOMOS Browser separates what the owner has already authorized from what needs consent now, and makes the difference visible, auditable, and reversible.

Related MCP server: Cloudflare Playwright MCP

How it looks

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

The browsing state belongs to the Runtime, not the model. The agent disconnects, dies, or is swapped for another from another vendor: the session stays alive, with the same tabs, cookies, and task.

Features

Demo

The Live Agent Console is served by the runtime itself, on the same origin, with CSP connect-src 'self' — there is no permissive CORS to exploit.

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

Reproducible scripts with expected results are in docs/demos.md.

Installation

npm ci --include=dev
npx playwright install chromium

--include=dev is not decoration: with NODE_ENV=production or npm config omit=dev, npm ci skips devDependencies and the typecheck later fails with "This is not the tsc command you are looking for". Details in docs/INSTALLATION.md.

There is no build step for the runtime: Node runs TypeScript natively. The UI has its own step (node packages/ui/build.ts) because it reads brand tokens from the vault on every generation.

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>

The CLI never grants a sensitive capability: a session created by it is born with download, upload, send, purchase, payment, and delete denied.

Examples

# 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 and AUTO

The hierarchy, and the order is the guarantee:

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

ASK — ask

Reads pass through. Every action that changes the page stops and asks, with consequence and recourse written in Portuguese, so the decision is conscious and not a reflex click.

Approving a browser.task is not a blank check: every step the plan decides to execute re-enters the gate.

AUTO — act without asking

The agent runs on its own everything you have already authorized through your policy. What does not change:

• actions with financial effect, external sending, or high irreversibility keep asking for approval — browser.upload asks in AUTO because it sends your data out, and that cannot be taken back;

• a route without a declared risk profile falls into "always approve" (fail-closed);

• if the autonomy state cannot be proven (runtime down, reconnection), the UI never shows AUTO: it falls to unknown and treats it as ASK.

AUTO != BYPASS is not a documentation promise. The autonomy gate runs after capability and human control: when it executes, everything the policy denies has already returned 403. There is no branch in the code that turns a deny into an allow.

More in docs/ask-mode.md and docs/auto-mode.md.

Security

• Token authentication with scopes (OBSERVE, NAVIGATE, INPUT, DOWNLOAD, UPLOAD, SECRET, CONTROL, ADMIN). Every route has a declared scope; none lives on the default.

• Who acts does not authorize. The agent profile cannot approve, delegate mode, or resume. Stopping, yes: pause and emergency-stop can never be harder than acting.

• Fail-closed policy per capability, with A6_DESTRUCTIVE denied.

• Anti-SSRF: navigating to an internal host is an explicit act, never inferred.

• Anti-injection provenance in the execution path: observe and extract return provenance.

• Mandatory control lease (allow_unleased: false).

• Secrets do not appear in the UI, the audit, or the replay.

The T1–T10 threat model, with declared residuals, is in docs/SECURITY.md.

Nothing here claims "100% secure". No measure supports that, and none ever will.

Audit and replay

Trail of 19 fields per action, hash-chained, with secret redaction at the source. On close, the session is sealed.

The replay is read-only in three independent layers: there is no write verb on the route (405 + Allow: GET); reading the history does not resurrect the session; and the mode is declared by the runtime, not inferred by the screen.

It is also honest about its own reading: it reports corrupted lines and missing sources instead of returning a shorter timeline that presents itself as complete. A session that never existed is 404, not an empty 200 replay.

See docs/audit-and-replay.md.

MCP

16 tools, no model coupling:

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

In the NOMOS ecosystem, the browser is a governed capability under the owner's policy, with a signed catalog and trust by fingerprint of the normalized manifest. See docs/mcp.md and docs/NOMOS-INTEGRATION.md.

Configuration

51 keys, queryable by the runtime itself:

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

The separation is deliberate: "what exists?" can be answered to any bearer; "what is in effect here?" cannot. See docs/CONFIGURATION.md.

Troubleshooting

Symptom → cause → verification → fix in docs/TROUBLESHOOTING.md.

Development

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

Use the runner, not node --test tests/ directly. Node's runner parallelizes per CPU; under memory pressure the process dies mid-way and leaves truncated output without a summary line, which looks like success. run-suite.sh runs one file at a time, and a dead file shows up as MORTO.

Tests

Measured at 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

The project refuses to call PASS what was not observed. Two examples:

Browser control is real. A click synthesized by JavaScript reaches the page with isTrusted=false; one dispatched via CDP arrives with true. The spike tests both — the second proves control, the first proves the test is not a vacuum.

The approval counter is not blind. Under product mutation, UNEXPECTED_APPROVAL_PROMPTS goes from 0 to 3 and to 5 depending on the injected defect. A counter that stayed at zero under mutation would not be measuring anything.

Known limitations

• p99 is not reported on any latency path: 30 samples require 100 to sustain a p99. No observed maximum is called p99.

• There is no HTTP route to issue a scoped token — it exists in the internal API.

• The pr.page.isClosed() branch is unreachable in normal operation; it is race defense, not coverage.

• The UI status bar updates by 700 ms polling. Events arrive in ~1 ms; the bar does not.

• Validated on macOS/Apple Silicon. Other platforms have not been measured.

The complete list, with numbers, is in docs/LIMITATIONS.md, and what is PROVEN versus what is MEASURED or NOT PROVEN is in PRODUCT_TRUTH_MATRIX.md.

Roadmap

In ROADMAP.md. What is there are legitimate debts, not date promises.

Documentation

Start here

Reference

Brand

The NOMOS brand is frozen at v1.0 and the official resolver responds rc=0. Tokens are read from the vault on every build and are not versioned in this repository — copying a brand token to an intermediate file is forbidden by the governance contract. See docs/BRAND.md.

License

MIT. See LICENSE. Holder: Voltolini-SPACE.

The license covers the code. It does not grant rights over the "NOMOS" and "NOMOS Browser" trademarks or over the visual identity tokens, which are governed separately and are not versioned here. Details in NOTICE.md.

Until 2026-08-25 this repository declared "all rights reserved" with a placeholder holder. Both were the owner's decision, and they have been decided.

Part of the NOMOS ecosystem · voltolini.space