{"_id":"@the-long-ride/aevra-browser","_rev":"3-0429b7db4c6473bb334dbb761d2258eb","name":"@the-long-ride/aevra-browser","dist-tags":{"latest":"1.0.1"},"versions":{"0.0.0-stage":{"name":"@the-long-ride/aevra-browser","version":"0.0.0-stage","_id":"@the-long-ride/aevra-browser@0.0.0-stage","stub":true,"maintainers":[{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"}],"dist":{"shasum":"baa80b8340613157f38d8b560808902824408d2a","tarball":"https://registry.npmjs.org/@the-long-ride/aevra-browser/-/aevra-browser-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-MSB6jfqB4N2qIljCL+67DB+I60qN04B0btPJppGiJ55JPvdh/P7c/0QlJsSdB6fehIlM4XCc7sD2FH/SbJBRbA==","signatures":[{"sig":"MEUCIFgN/mR/q0EsOVq+9pbwGTPdoUvDKsMzhY6W1GwGv+c9AiEAmuzzzNL3a2WSqePmQqfcYqoOBvYzqCk40d8TSp3iWig=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":350},"_npmUser":{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.0.0":{"name":"@the-long-ride/aevra-browser","version":"1.0.0","license":"MIT","_id":"@the-long-ride/aevra-browser@1.0.0","maintainers":[{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"}],"homepage":"https://github.com/the-long-ride/aevra-browser#readme","bugs":{"url":"https://github.com/the-long-ride/aevra-browser/issues"},"bin":{"aevra-browser":"dist/src/cli.js"},"dist":{"shasum":"2d5647d1b1be7b5c11d002de1fee893fdab98b0a","tarball":"https://registry.npmjs.org/@the-long-ride/aevra-browser/-/aevra-browser-1.0.0.tgz","fileCount":97,"integrity":"sha512-29P3vza1YTAwZI2VDyttgqtrVGNzZ7oK8WjIudhTQ5wCm8R9qRWYVc/dMyuzeUiIJE1HJZfhSaGFZttwNgdYkA==","signatures":[{"sig":"MEQCICZx/hORdBdqwmIFq2fGWvqEjYt1jJr2Va96H3NcqDROAiAt1QyHkKhHGI+3SBrcGxVZPEITiZvN8VWvvjew01Fq9w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIBSxA6xZNXQsfyr3JLdA1406VRAIfl7+twGfjyVMMN7HAiBx7Ibx8zlNDbvVh6oC3BzSNT7qJBxXfzXVVpGgefp+lg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":463624},"type":"module","engines":{"node":">=24.0.0"},"gitHead":"085afb95c8ca830d485ee18eec84b563eaf88d3e","scripts":{"lint":"node scripts/loc-lint.mjs","test":"node scripts/test.mjs","build":"node scripts/build.mjs","format":"prettier --write .","prepack":"npm run build","coverage":"c8 node scripts/test.mjs","typecheck":"node node_modules/typescript/bin/tsc -p tsconfig.typecheck.json","format:check":"prettier --check .","test:package":"node scripts/verify-package-runtime.mjs","build:extension":"node scripts/build-extension.mjs"},"_npmUser":{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"},"repository":{"url":"git+https://github.com/the-long-ride/aevra-browser.git","type":"git"},"_npmVersion":"12.1.0","description":"Standalone browser-control MCP server built on aevra's extension and CDP drivers.","directories":{},"_nodeVersion":"24.22.1","dependencies":{"smol-toml":"^1.9.1","jsonc-parser":"^3.3.1"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^12.0.0","prettier":"^3.5.3","typescript":"^5.8.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/aevra-browser_1.0.0_1793274806439_0.05472937614818696","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"_id":"@the-long-ride/aevra-browser@1.0.1","bin":{"aevra-browser":"dist/src/cli.js"},"bugs":{"url":"https://github.com/the-long-ride/aevra-browser-use/issues"},"dist":{"shasum":"b75f8b6a34d529cb7c1a17ded101bd8f012dd830","tarball":"https://registry.npmjs.org/@the-long-ride/aevra-browser/-/aevra-browser-1.0.1.tgz","fileCount":97,"integrity":"sha512-diwqyxAuQyA8728EU/UHJhUsLsBCaW4ssWm423E4sGFWtbUkmT9S5vebEE8I96iDPB6hbRHNMhjl9zIv1/IR4g==","signatures":[{"sig":"MEUCIGF1aKlfnaPjGAFLaJOJAS5qYV2VYW18MktZ2OqJjQRFAiEAtm896tEXwQkeAdpLJpT5UpBN4E70UBGax+I396o1VJg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCW9dQTdVryzqK88CxiEZuk2kaz0lYT+dL5ljzDTIy+KQIgJYWxW6vxoqUz4BzJo49eju1GXxKud7NC8MTstxE4PAI="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@the-long-ride%2faevra-browser@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":464645},"name":"@the-long-ride/aevra-browser","type":"module","author":{"name":"the-long-ride"},"engines":{"node":">=24.0.0"},"gitHead":"05d68bf997a5e10fc91a7cb8b9287dd35ab35ffd","license":"MIT","scripts":{"lint":"node scripts/loc-lint.mjs","test":"node scripts/test.mjs","build":"node scripts/build.mjs","format":"prettier --write .","prepack":"npm run build","coverage":"c8 node scripts/test.mjs","typecheck":"node node_modules/typescript/bin/tsc -p tsconfig.typecheck.json","format:check":"prettier --check .","test:package":"node scripts/verify-package-runtime.mjs","build:extension":"node scripts/build-extension.mjs"},"version":"1.0.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d8859a96-b3cd-4a4b-b3db-6b66b453648b"}},"homepage":"https://github.com/the-long-ride/aevra-browser-use#readme","keywords":["mcp","mcp-server","model-context-protocol","browser-automation","browser-use","cdp","chrome-devtools-protocol","browser","automation","ai-agents","claude-code","antigravity","codex","aevra"],"overrides":{"glob":"^14.0.4","minimatch":"^11.0.5"},"repository":{"url":"git+https://github.com/the-long-ride/aevra-browser-use.git","type":"git"},"_npmVersion":"11.19.1","description":"Standalone browser-control MCP server built on aevra's extension and CDP drivers.","directories":{},"maintainers":[{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"}],"_nodeVersion":"24.22.2","dependencies":{"smol-toml":"^1.9.1","jsonc-parser":"^3.3.1"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^12.0.0","prettier":"^3.5.3","typescript":"^5.8.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aevra-browser_1.0.1_1793945305512_0.8540836276716234"}}},"time":{"created":"2026-10-29T11:52:29.600Z","modified":"2026-11-06T06:08:25.963Z","0.0.0-stage":"2026-10-29T11:52:29.600Z","1.0.0":"2026-10-29T11:53:26.538Z","1.0.1":"2026-11-06T06:08:25.630Z"},"bugs":{"url":"https://github.com/the-long-ride/aevra-browser-use/issues"},"license":"MIT","homepage":"https://github.com/the-long-ride/aevra-browser-use#readme","repository":{"url":"git+https://github.com/the-long-ride/aevra-browser-use.git","type":"git"},"description":"Standalone browser-control MCP server built on aevra's extension and CDP drivers.","maintainers":[{"name":"the-long-ride-1406","email":"thelong1406@gmail.com"}],"readme":"# @the-long-ride/aevra-browser\n\nBrowser control for any MCP client, without the aevra gateway.\n\nOne local daemon owns [aevra](https://github.com/the-long-ride/aevra)'s browser\nextension and CDP drivers. It exposes aevra's ten `browser_*` tools over loopback\nHTTP, and a stdio bridge lets any number of MCP clients share the same paired\nbrowser. The package needs Node.js 24 or newer. Native agent configuration uses small TOML and JSONC parser dependencies.\n\n**Release:** `1.0.1`. **Compatibility:** the browser drivers are pinned to the aevra v1.2.1 snapshot. The\nextension is built from the checked root-source snapshot in `shared/aevra` and is\npublished as a zip release asset.\n\n## Keep browsing while the agent works\n\nAevra Browser supports mouse-free, tab-targeted automation. An agent can read and interact with its task tab through the extension or CDP while you keep using your mouse and keyboard in another tab or application. Browser actions are delivered to the selected browser target rather than through system-wide mouse movement or keyboard injection.\n\nKeep an explicit `tabId` for the agent's task and reuse that tab's element refs. Ordinary target selection does not activate the tab. DOM focus and browser input events stay within that target; they can still change the page the agent is working on. Using separate tabs avoids competing with the agent over the same field or page state.\n\nExplicit `browser_tabs` focus requests activate the requested tab. The extension's visible-tab screenshot path requires an active tab and refuses an inactive target instead of activating it silently; screenshot support depends on the chosen transport. Multiple MCP clients share the daemon's browser state, so coordinate which client owns each task tab. Mouse-free targeting does not provide separate browser profiles or merge simultaneous edits.\n\n## Why Aevra Browser?\n\nUse this project for browser automation alongside your own browsing, with one local connection shared by your MCP clients.\n\n- **One daemon, multiple clients:** stdio bridges share the paired browser instead of each starting its own extension server. The daemon stays available after an individual client exits.\n- **Two connection paths:** pair the Aevra extension for a browser profile, or attach through CDP to a browser you started with a debugging port.\n- **A bounded browser toolset:** ten `browser_*` tools expose navigation, observation and actions. `browser_execute_script` accepts a bounded action grammar; the drivers retain credential-field refusals and untrusted/redacted page results.\n- **A small local deployment:** Node.js 24+, an npm command and native TOML/JSONC configuration editing. stdio starts the daemon on demand; authenticated loopback HTTP is available for clients that need it.\n- **A stable upstream boundary:** the browser drivers are pinned to the Aevra v1.2.1 snapshot and the extension is built from the checked shared-source snapshot. Package and schema compatibility do not depend on the gateway running beside it.\n\n## How it differs from the other Aevra repositories\n\n| Project                                                             | Focus                                                                               | Access and workflow                                                                  |\n| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| **Aevra Browser — this repository**                                 | Browser tabs through an extension or CDP                                            | Shared loopback daemon, one-time pairing, stdio bridges or bearer-authenticated HTTP |\n| [Aevra](https://github.com/the-long-ride/aevra)                     | Files, commands, Git, processes, browser/desktop tools and upstream MCP aggregation | Gateway Web UI, workspace/connector policy, approvals and hash-chained auditing      |\n| [Aevra Desktop](https://github.com/the-long-ride/aevra-desktop-use) | Native application windows and accessibility controls                               | Application allowlist, native settings/tray UI and local Activity history            |\n\nChoose Browser for browser-only automation on a single-user machine. Choose the gateway when browser actions need centralized workspace policy, approvals and audit. Choose Desktop for native applications outside browser tabs. All clients connected to this daemon share browser state and authority; the pairing/token model does not create isolated per-client browsing sessions.\n\n## Current release and compatibility\n\nVersion **1.0.1** includes custom startup listener ports through a consecutive base block or individual listener options, including daemon auto-start and installed stdio agents. It retains the standalone daemon/bridge, one-time pairing, extension installation, explicit CDP attachment, listener health and loopback authentication. See the [changelog](CHANGELOG.md) for release changes and the [documentation index](docs/README.md) for implemented specifications.\n\nThe browser drivers remain pinned to **Aevra v1.2.1**. The shared extension and agent integration sources are separately recorded in `shared/aevra-source.json`. Root Aevra and Aevra Desktop have independent release scopes; updating a sibling repository does not update this package's bundled snapshot. Use the [gateway](https://github.com/the-long-ride/aevra) for its current MCP management, token statistics and wider workspace features.\n\n## Quick start\n\n1. Install the extension, then load it unpacked.\n\n   ```bash\n   npx -y @the-long-ride/aevra-browser extension install\n   ```\n\n   Open `chrome://extensions` (or `edge://extensions`), turn on Developer mode,\n   choose **Load unpacked** and select the folder the command prints. Keep that\n   folder where it is: Chrome derives the extension id from its path, and the\n   pairing is bound to that id.\n\n2. Pair the browser profile.\n\n   ```bash\n   npx -y @the-long-ride/aevra-browser pair\n   ```\n\n   It prints an 8-character code. In the Aevra extension popup, enter the code and\n   port `47841`. A code is valid for 5 minutes and works once.\n\n3. Add the server to your MCP clients.\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"aevra-browser\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@the-long-ride/aevra-browser\", \"mcp\"]\n       }\n     }\n   }\n   ```\n\n   Every client that launches this command drives the same paired browser. The first\n   one starts the daemon in the background and it keeps running after a client exits.\n   `browser_status` tells the agent what to do next (`not_paired`,\n   `waiting_for_extension`, `ready_to_connect`, `attached`).\n\n## Other ways to connect\n\n### HTTP with a bearer token\n\nThe daemon serves MCP over Streamable HTTP (JSON responses) at\n`http://127.0.0.1:47842/mcp`. Every request needs the daemon's token:\n\n```bash\naevra-browser status --show-token\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"aevra-browser\": {\n      \"url\": \"http://127.0.0.1:47842/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer <token from status --show-token>\" }\n    }\n  }\n}\n```\n\nThe token is generated each time the daemon starts, so the stdio configuration above\nis the better default. The endpoint answers `401` without the token and `403` to any\nrequest whose `Origin` or `Host` is not loopback, so a web page cannot reach it.\n\n### CDP mode\n\nTo drive a browser without the extension, start it with a debugging port and attach:\n\n```bash\nchrome --remote-debugging-port=9222\naevra-browser cdp --port 9222\n```\n\nThis is the same as an agent calling `browser_connect` with `transport: \"cdp\"`. The\nbrowser is never discovered or launched for you.\n\n## Settings and local agent installation\n\n```sh\naevra-browser ui\naevra-browser config get --json\naevra-browser config set pairPort 50141\naevra-browser config reset pairPort\naevra-browser agent install codex\naevra-browser agent install all --transport stdio\naevra-browser agent install claude-code --transport http --dry-run\naevra-browser agent status --json\naevra-browser agent uninstall all\naevra-browser uninstall --purge --dry-run\n```\n\nStart the daemon before opening `ui`. Its one-use local login opens a settings page\nfor listener configuration, pairing, profile removal, transport examples and\nagent integrations. Configuration is saved atomically; listener changes require\nan explicit daemon restart. Effective settings show whether values come from\ndefaults, saved configuration or environment overrides.\n\nInstall from a persistent npm location before registering agents. The installer\nsupports Codex, Claude Code, OpenCode and Antigravity, with native stdio or HTTP\nconfiguration. Each registration gets a separate credential. HTTP credentials\nsurvive daemon restarts and grant MCP access only. Refresh/restart the agent to\nload registration changes.\n\nSkills are canonical at `~/.agents/skills/aevra-browser`; agent-specific folders\nreceive links (Windows directory junctions), while Codex discovers the canonical\nfolder directly. Existing custom entries, modified skills and conflicting links\nare retained with a conflict report. `agent uninstall` revokes only that target's\ncredential and removes its managed resources. `uninstall --purge` also stops the\ndaemon and removes owned state; package-manager removal remains separate.\n\nBoth products install to a shared stable extension location. Load one copy. In\nits popup use root Aevra's pairing port `47831` or Browser's `47841` with a fresh\ncode; custom configured ports work too. Pairing failure keeps the old connection.\nThe selected server's port appears in the popup. Shared files remain until their\nlast owner is removed. Remove the browser's load-unpacked registration manually\nwhen neither product needs it.\n\n## Commands\n\n| Command                                               | What it does                                                    |\n| ----------------------------------------------------- | --------------------------------------------------------------- |\n| `aevra-browser mcp`                                   | Stdio MCP server. Starts the daemon when none is running.       |\n| `aevra-browser serve`                                 | Runs the daemon in the foreground. Exits 0 if one already runs. |\n| `aevra-browser pair`                                  | Prints a one-time pairing code.                                 |\n| `aevra-browser unpair <id>` / `--all`                 | Removes one pairing. `--all` also invalidates every token.      |\n| `aevra-browser status [--json] [--show-token]`        | Shows the daemon, ports, connection state and paired profiles.  |\n| `aevra-browser stop`                                  | Stops the daemon.                                               |\n| `aevra-browser cdp [--port <n>]`                      | Attaches to a browser started with `--remote-debugging-port`.   |\n| `aevra-browser extension install [--dir <p>] [--yes]` | Downloads the extension zip and unpacks it safely.              |\n\n## Ports and environment\n\nThe [implemented startup-port specification](docs/specs/custom-startup-ports.md) describes validation, precedence and daemon reuse in detail.\n\nChoose listener ports for one invocation with either a consecutive block or individual options:\n\n```bash\naevra-browser serve --basePort=51000\n# Pairing/settings: 51000; MCP: 51001; extension WebSocket: 51002\naevra-browser pair --up 51010 --mp=51020 --wp 51030\naevra-browser cdp --port=9222 --basePort=51000\naevra-browser agent install codex --basePort=51000\n```\n\n`--ui-port` (`--up`), `--mcp-port` (`--mp`) and `--ws-port` (`--wp`) accept any subset;\nthe remaining listeners keep their environment or saved defaults. Both `--flag=N` and\n`--flag N` work on `serve`, `mcp`, `pair`, `cdp`, `ui` and `agent install`.\nCLI choices override environment and saved settings without rewriting `config.json`.\nExplicit agent installations remember those choices per credential for stdio auto-start;\nHTTP installations use the actual running MCP listener URL when the daemon is already running.\n\nDo not mix `--basePort` with individual options or repeat a listener through either alias.\nListener values must be decimal integers from 1 to 65535, distinct from one another;\n`--basePort` must be at most 65533. If an explicitly requested listener differs from a\nrunning daemon, stop it with `aevra-browser stop` and retry. A command without listener\noptions can continue using the running daemon's actual ports. CDP's existing `--port`\nstill selects the browser debugging target independently.\n\nAll listeners bind `127.0.0.1` only. The defaults do not overlap aevra's `47830-47833`,\nso both can run on one machine.\n\n| Listener                             | Default | Environment variable      |\n| ------------------------------------ | ------- | ------------------------- |\n| Pairing HTTP (`/api/browser/pair`)   | `47841` | `AEVRA_BROWSER_PAIR_PORT` |\n| MCP HTTP (`/mcp`)                    | `47842` | `AEVRA_BROWSER_MCP_PORT`  |\n| Extension WebSocket                  | `47843` | `AEVRA_BROWSER_WS_PORT`   |\n| CDP target (browser's debugger port) | `9222`  | `AEVRA_BROWSER_CDP_PORT`  |\n\nIf a port is taken, `serve` exits non-zero with\n`BROWSER_LISTENER_FAILED: port <n> in use (set AEVRA_BROWSER_..._PORT)`.\n\nState (the token signing key, pairings, the daemon lock and the unpacked extension)\nlives in `AEVRA_BROWSER_HOME` when set, otherwise `%LOCALAPPDATA%\\aevra-browser` on\nWindows, `~/Library/Application Support/aevra-browser` on macOS and\n`$XDG_STATE_HOME/aevra-browser` (default `~/.local/state/aevra-browser`) on Linux.\n\n## What the tools refuse\n\nGovernance is deliberately minimal. These guards always apply:\n\n- credential, one-time-code and payment fields are refused by the extension and CDP\n  drivers;\n- `browser_navigate` and `browser_tabs` with `action: \"open\"` refuse browser-internal\n  schemes, aevra's and this daemon's own ports, and URLs that carry secret-shaped data;\n- vision snapshots of sensitive origins (banking, mail, identity providers and\n  similar) are refused, because pixels cannot be redacted;\n- text that looks like a secret is refused before it is typed into a page;\n- `browser_execute_script` accepts only aevra's bounded action grammar, never\n  arbitrary JavaScript;\n- page text, logs and tab titles are redacted and marked untrusted before they reach\n  the model.\n\nThere are no approvals, per-connection grants or audit log. Any client of the daemon\ncan act on the paired browser, which suits a single-user machine.\n\n## Known limits\n\n- Reconnect uses the saved pairing origin, including custom ports. The server must be available and the saved credential valid.\n- One loaded extension can switch between products by pairing port. Only one server controls it at a time; entering a fresh code switches the connection.\n- **No signed extension.** Install is load-unpacked, as with aevra.\n\n## Development\n\n```bash\ngit clone --recurse-submodules https://github.com/the-long-ride/aevra-browser-use\ncd aevra-browser-use\nnpm ci\nnpm test            # compiles, then runs node:test\nnpm run typecheck\nnpm run lint        # .ts files stay under 350 lines\nnpm run coverage    # 85% gate on src/\nnpm run build && npm run test:package\nnpm run build:extension\n```\n\n`src/vendor.ts` is the only file that imports from `vendor/aevra`. The vendored files\nare compiled into `dist/vendor` by the same `tsc` run, and `test:package` fails if a\nfile the package needs is not shipped. Bumping the submodule is its own commit.\n\n## License\n\n[MIT](LICENSE).\n","readmeFilename":"README.md","keywords":["mcp","mcp-server","model-context-protocol","browser-automation","browser-use","cdp","chrome-devtools-protocol","browser","automation","ai-agents","claude-code","antigravity","codex","aevra"],"author":{"name":"the-long-ride"}}