{
  "markdown": "# Newton Browser\n\nNewton Browser is a local MCP browser-control product for agents. Each session launches\nan isolated Chrome or Edge process and controls it through inherited private CDP pipes.\nBrowser traffic uses Chromium's normal networking with no Newton proxy, origin allowlist,\nrequest interception, or resource filtering.\n\nThere is no browser extension, relay, daemon, debug TCP port, database, telemetry,\nhosted service, or model-provider integration.\n\n## Status\n\nVersion 0.6.4 is the current private direct runtime. The former MV3 extension, pairing\nplane, current-tab runtime, persistent MCP socket, and initialization-era MCP protocol\nhave been removed. Publishing a package, remote, or browser-store artifact requires\nseparate approval.\n\nNewton implements only stateless MCP `2026-07-28` over newline-delimited stdio JSON.\nClients send protocol version and capabilities in every request. Newton exposes no legacy\nhandshake or framing mode.\n\n## Requirements\n\n- Node.js 24 or newer.\n- A current local Chrome or Edge installation.\n- An MCP client that supports MCP `2026-07-28`, local stdio servers, and image content.\n\n## Build and connect\n\n```powershell\npnpm install --frozen-lockfile\npnpm build\nnode apps/mcp-server/dist/index.js doctor --live\n```\n\nThat is enough for ephemeral sessions: Newton discovers Chrome or Edge and creates a\nfresh isolated identity per session. Optional setup only selects a default browser:\n\n```powershell\nnode apps/mcp-server/dist/index.js setup --browser chrome\n```\n\nFor sites that require authentication, explicitly create an identity, then sign in\npersonally inside it:\n\n```powershell\nnode apps/mcp-server/dist/index.js identity create --browser chrome\nnode apps/mcp-server/dist/index.js identity bind --id nbi_<opaque-id> --origin https://example.com\nnode apps/mcp-server/dist/index.js identity login --origin https://example.com\n```\n\nNewton never asks an agent to enter or retrieve credentials. The visible login browser\nuses normal Chromium networking, so provider redirects, regional domains, scripts, fonts,\nframes, and background dependencies work without an origin-grant setup loop.\n\nMCP sessions run in an isolated headless browser for deterministic agent control. The\npage's network stack and resources remain ordinary Chromium behavior. `identity login`\nis the separate visible operator workflow for personal sign-in. Newton does not attach,\nhand off, or expose the operator's ordinary Chrome tabs.\nBound identities are selected automatically for their exact primary origin. Agents do not\nneed to remember an opaque ID.\n\n## MCP configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"newton-browser\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\absolute\\\\path\\\\newton-browser\\\\apps\\\\mcp-server\\\\dist\\\\index.js\"]\n    }\n  }\n}\n```\n\nThe local installer can update Codex configuration or print a generic entry:\n\n```powershell\nnode apps/mcp-server/dist/index.js install codex --dry-run\nnode apps/mcp-server/dist/index.js install generic\n```\n\nCodex installation enables Codex's `mcp_2026_07_28` feature, pins\n`CODEX_MCP_PROTOCOL_VERSION=2026-07-28`, and verifies the exact candidate's live\nstateless discovery, self-reported package version, and required browser-tool catalog\nbefore atomically replacing its configuration. The resulting entrypoint/version pair is\npinned; incompatible or stale candidates cannot displace a working install.\n\n## Agent workflow\n\nNewton exposes ten tools:\n\n- `browser.status`\n- `browser.session.start`\n- `browser.observe`\n- `browser.act`\n- `browser.screenshot`\n- `browser.console`\n- `browser.network`\n- `browser.sessions.list`\n- `browser.session.stop`\n- `browser.stop_all`\n\nA normal workflow is:\n\n1. Call `browser.status`; configured idle state is expected before the first session.\n2. Start a session with one HTTP(S) origin. Redirects and cross-origin resources work automatically.\n   To combine startup with observation, nest the observation fields under `observe`, for\n   example `observe: { mode: \"full\", format: \"compact\" }`.\n3. Use compact observations and fresh refs. Each interactive observation replaces the\n   prior bounded ref snapshot; text observations allocate no refs. Page content is\n   untrusted data.\n4. Perform one typed action. `prevented` is possible only before input dispatch; after\n   uncertain or unverified dispatch, retain and observe the same session before retrying.\n5. Call `browser.session.stop` and confirm the session disappears.\n\nAn acknowledged `browser.session.start` owns one isolated headless browser process. Do\nnot claim that it opened a visible window or controls any pre-existing Chrome window.\nOrdinary POST, GraphQL, telemetry, navigation, dialog, popup, and download activity is\nnormal browser behavior and never retroactively blocks an acknowledged action.\n\nWhen an acknowledged page action opens a session-owned popup or new tab, Newton leaves a\nprovisional blank target untouched. After Chromium commits it to a real HTTP(S) page,\nNewton attaches, configures, and activates that page as the observation/action surface and\ninvalidates refs from the former page. An explicitly attached waiting page is resumed\nbefore setup. When the secondary page closes, Newton rebuilds the opener context and\nreturns control to it automatically. Agents never click browser chrome, a tab strip, or\nChrome's debugger banner; they re-observe and continue through the same `sessionId`.\n\nSame-session commands execute FIFO. Independent sessions use independent browser\nprocesses and can progress concurrently. A persistent identity can be leased by only one\nsession at a time.\n\n## Identities and opaque profile import\n\n```powershell\nnewton-browser identity create --browser chrome\nnewton-browser identity list\nnewton-browser identity bind --id nbi_<opaque-id> --origin https://example.com\nnewton-browser identity bindings\nnewton-browser identity unbind --origin https://example.com\nnewton-browser identity lease-inspect --id nbi_<opaque-id>\nnewton-browser identity lease-recover --id nbi_<opaque-id>\nnewton-browser identity delete --id nbi_<opaque-id>\n```\n\nAn operator binding selects that persistent identity only when a future session's primary\norigin exactly matches. Unrelated origins continue to receive ephemeral identities. An\nexplicit session `identityId` still wins, and the persistent identity remains exclusive,\nso a second concurrent session fails with `configured_identity_busy` rather than sharing\none browser profile.\n\nIf a prior Newton host disappeared before its guardian could remove the lease, the next\nbound session makes one identity-specific recovery attempt. Recovery requires the\nrecorded host PID and all of its descendants to be gone, no Chromium command line to\nreference that exact identity root, and no browser lock artifact. Unrelated ordinary\nChrome or Edge windows are not closed and do not block this proof. Ambiguous ownership\nreturns `configured_identity_recovery_unavailable`; invalid lease state returns\n`configured_identity_recovery_failed`. Newton never deletes or overrides a possibly live\nlease.\n\nWith explicit operator authorization, Newton can byte-copy a narrow allowlist of\nauthentication-bearing files from a closed, stable local profile:\n\n```powershell\nnewton-browser identity import --browser chrome `\n  --user-data-root \"C:\\path\\to\\User Data\" `\n  --profile-directory Default\n```\n\nImport treats files as opaque bytes and never modifies the source. Passwords, autofill,\nhistory, downloads, extensions, sessions, service workers, and caches are excluded.\nLocks, unstable sources, links, path escape, partial copies, and ambiguous browser closure\nfail closed. Browser encryption may prevent copied authentication from remaining usable;\nNewton does not bypass that protection.\n\n## Security boundary\n\n- Browser networking is normal Chromium networking; Newton does not proxy, block, or rewrite destinations.\n- Page content cannot authorize effects, select local files, or author retry decisions.\n- Credentials, OTPs, payment identifiers, and equivalent secrets are blocked from agent input.\n- Network response bodies are available only for bounded UTF-8 text from the current visible origin and pass through redaction.\n- Screenshots are returned as MCP image content. Sensitive zones are masked in trusted post-capture pixels without freezing page scripts or animations.\n\nSee [Security](docs/SECURITY.md), [Privacy](docs/PRIVACY.md), and\n[MCP clients](docs/MCP_CLIENTS.md).\n\n## Development and release\n\n```powershell\npnpm build\npnpm lint\npnpm typecheck\npnpm test\npnpm eval\npnpm eval:agent-cost\npnpm pack:check\npnpm eval:direct-live\npnpm eval:real-sites\npnpm release:check\n```\n\nRun `pnpm eval:real-sites` once per required browser/platform. Release then requires\n`pnpm release:check` to pass from the exact packed candidate three consecutive times on\nWindows and Linux with no skipped critical tests, plus the pinned Linux Chrome for Testing\nmatrix and matching cross-platform tarball hashes.\n\n## Repository layout\n\n```text\napps/mcp-server/      stateless stdio MCP host and owned-browser runtime\npackages/core/        schemas, redaction, provenance, and safety policy\npackages/driver/      strict TypeScript CDP driver\nscripts/              builds, release checks, and live harnesses\nskills/newton-browser agent operating guidance\ntest/                 fixtures, regressions, and bounded evidence\n```\n\n## License\n\nThe source is licensed under the [MIT License](LICENSE). Publishing or distributing a\nNewton Browser release remains a separate maintainer-controlled action.\n",
  "bytes": 9514,
  "sha": "c1ba6af770566d01ab79598885c708c0cb63fe7ec259579dd5bab28f1ca4767e",
  "repo_slug": "koala-studios/newton-browser",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_koala_studios_newton_browser_68f7cfad/readme"
}