Bronom

Bronom is a visible, multi-tab Electron browser that exposes its live tabs to AI clients through MCP. It is deliberately not headless and is not tied to the lifetime of an AI session.

Project website: https://netroforge.github.io/bronom/

What it keeps

• Cookies, local storage, IndexedDB, service workers, cache, and login sessions use Electron's persistent persist:bronom partition.
• Open tabs and the active tab are restored from tabs.json in Electron's user-data directory.
• Appearance settings are restored from settings.json in the same profile.
• Allowed and blocked website permissions are restored from site-permissions.json in the same profile.
• Window position, size, monitor, maximized state, and fullscreen state are restored. If that monitor is disconnected, the window is centered on the current primary display.
• Closing the window hides it by default. The Electron process and MCP endpoint keep running; click the tray icon to open its menu and choose Show Bronom or Quit. Disable Hide in tray when closing in Settings to make the window close button quit Bronom instead.
• A second launch focuses the existing instance instead of starting a competing browser profile.

Appearance

Open Settings from the gear button at the right of the address bar. Bronom includes three application themes:

• Light for a bright, neutral browser shell.
• Dark for a low-glare browser shell.
• Cyberpunk for a neon cyan and magenta browser shell.

The selected theme is applied immediately and survives application restarts. It changes Bronom's controls and native color preference without injecting styles into websites. The same dialog includes separate MCP security, Site permissions, and Updates sections.

Site permissions

When a website requests access such as location, notifications, clipboard, camera, or microphone, Bronom asks before granting it and remembers the Allow or Deny decision for that exact website origin. Open Settings → Site permissions to change a saved decision, forget one so Bronom asks again, or reset the section to clear all saved decisions.

Updates

Automatic update checks are disabled by default. Packaged builds check the public GitHub release feed shortly after startup only after you enable both Enable auto update and Check for updates on startup. Bronom never downloads an update silently: an in-app notification shows the available version and release notes, then asks you to Download update and Install and restart.

You can also check manually from Settings, the Bronom application menu, or the tray menu. Update preferences are stored in the persistent profile. Development builds do not contact the release feed; set BRONOM_DISABLE_AUTO_UPDATE=1 to disable checks for a packaged launch as well.

Bronom Home

The compact B button before the first regular tab opens Bronom Home, an internal dashboard that stays inside the persistent browser partition. Bronom keeps Home as a singleton: clicking the button focuses the existing Home page or recreates it if needed. Regular new tabs remain blank. Home provides:

• Copy-ready setup instructions for Codex, Claude Code, Cursor, VS Code/GitHub Copilot, and generic Streamable HTTP clients.
• A live list of active requests and recently seen MCP clients.
• The current 25-tool browser catalog, grouped by session, navigation, interaction, and inspection.
• The local MCP endpoint and authentication guidance.

Regular websites, including https://google.com, can be opened from the address bar, a new-tab request with a URL, or browser_navigate.

Run

Requirements: Node.js 22+ and a graphical Linux, macOS, or Windows session.

npm install
npm run dev

Development runs use a persistent bronom-dev profile. This keeps development cookies, tabs, storage, and window state across restarts while avoiding the single-instance lock and profile of an installed Bronom build. If an older window appears after upgrading the source, quit it from Bronom → Quit once instead of only closing the window.

For the built application:

npm run build
npm start

To ask an already running development instance to flush its profile and quit cleanly:

node_modules/.bin/electron . --quit

The MCP endpoint is available while the app is running:

http://127.0.0.1:47812/mcp

Health check:

export BRONOM_MCP_TOKEN="$(cat ~/.config/Bronom/mcp-token)"
curl -H "Authorization: Bearer $BRONOM_MCP_TOKEN" http://127.0.0.1:47812/healthz

The exact profile path is shown on Bronom Home. On Linux, the packaged default is ~/.config/Bronom/mcp-token; development builds use ~/.config/bronom-dev/mcp-token. Bronom creates one random token per profile and restricts the token file to the profile owner.

Connect an MCP client

Use a Streamable HTTP MCP configuration and start Bronom before the client connects. A generic JSON configuration looks like:

{
  "mcpServers": {
    "bronom": {
      "url": "http://127.0.0.1:47812/mcp",
      "headers": {
        "Authorization": "Bearer <paste the token shown by Bronom Home>"
      }
    }
  }
}

The exact schema depends on the MCP client; Bronom Home includes separate current instructions for the major coding agents. Disconnecting or closing that client does not close Bronom.

Optional environment variables:

• BRONOM_MCP_PORT: listen port, default 47812.
• BRONOM_MCP_HOST: loopback listen host, default 127.0.0.1. Non-loopback values are rejected.
• BRONOM_MCP_TOKEN: override the generated per-profile token with at least 32 URL-safe characters. While authentication is enabled, every MCP and health request must send Authorization: Bearer <token>.
• BRONOM_DISABLE_MCP_AUTH: start the current launch with MCP authentication disabled. The same setting can be changed immediately under Settings → MCP security. Bronom remains loopback-only, but every local process can then control the profile; use this only on a trusted single-user machine.
• BRONOM_USER_DATA_DIR: use an alternate profile directory instead of the packaged or bronom-dev default. This is primarily useful for isolated integration tests.
• BRONOM_DISABLE_AUTO_UPDATE: set to 1 to disable update checks for the current launch.
• BRONOM_DOWNLOAD_DIR: save website downloads in this directory instead of the operating system's Downloads directory.

MCP tools

• browser_status, browser_show, browser_tabs
• browser_new_tab, browser_select_tab, browser_close_tab
• browser_navigate, browser_history, browser_wait
• browser_snapshot, browser_click, browser_type, browser_fill_form, browser_press
• browser_select, browser_hover, browser_drag, browser_scroll, browser_file_upload
• browser_resize, browser_screenshot, browser_console, browser_network, browser_downloads, browser_evaluate

The preferred interaction loop is browser_snapshot → semantic element ref (e1, e2, ...) → browser_click or browser_type. Take a fresh snapshot after navigation or large DOM changes.

browser_screenshot can capture either the visible viewport or the full page. Console and network histories are bounded to the 500 most recent entries per tab, and network results intentionally omit headers and bodies. Website downloads are tracked through MCP, use collision-safe filenames, and never silently overwrite an existing file.

browser_resize applies a per-tab viewport override for responsive testing and can reset it without resizing the desktop window. browser_fill_form updates several inputs, text areas, selects, checkboxes, radios, or editable elements in one call.

Support Bronom

Bronom is free and open source. The current funding goal is Windows code signing and Apple notarization so new users see fewer security warnings when installing it. Support is always optional; Bronom has no locked features or donation popups.

Security model

• The MCP server binds to loopback by default and rejects non-local browser origins.
• By default, every MCP and health request requires a strong bearer token. Bronom generates and reuses an owner-only token for each browser profile unless a valid BRONOM_MCP_TOKEN override is supplied. Authentication can be explicitly disabled in Settings → MCP security or for launch with BRONOM_DISABLE_MCP_AUTH=1.
• Website tabs have Node.js disabled, context isolation enabled, Chromium sandboxing enabled, and web security enabled.
• New browser windows become managed tabs.
• Unknown site permission requests require explicit confirmation. Bronom remembers each decision per website origin and permission type, and lets you review or revoke it later in Settings.
• Camera, microphone, and file-system grants are never reused: Bronom shows the requested scope and asks again each time.
• browser_evaluate is intentionally powerful: only connect trusted AI clients to this browser profile.
• browser_file_upload can attach any absolute local file path supplied by a connected client. Only connect clients you trust with local file access.

Testing

Unit tests live in tests/*.test.ts and use Vitest. Real-application integration tests live in tests/integration/*.e2e.ts and use Playwright's Electron API with reusable fixtures from tests/integration/fixtures.ts. Every integration test launches Bronom with an isolated temporary profile and cleans it up afterward. The suite covers the visible shell, tabs, MCP, Home, themes, site permissions, restart persistence, and updater settings without contacting the live release feed. Application, test, preload, website, and build configuration source is TypeScript.

npm test
npm run test:integration
npm run typecheck
npm run build
npm run build:website
npm run build:unpack

On a headless Linux machine, run the already-built integration suite under Xvfb:

xvfb-run --auto-servernum npm run test:integration:run

The CI workflow runs unit tests, the production build, the real Electron integration suite, and the production dependency audit. Pull requests whose branch name contains release- additionally build the complete Linux, macOS, and Windows package sets in a hosted matrix before merge.

GitHub Pages

The English product website is authored in website/ with TypeScript behavior and built by Vite. The dedicated Pages workflow builds it from main, uploads the generated docs/ artifact, and deploys it through GitHub Pages. It resolves platform-specific downloads from the latest public GitHub release only after a user clicks a download card.

Preview the exact production output locally:

npm run build:website
npm run preview:website

Releases

GitHub Actions validates every pull request and every push to main. When package.json changes to a new version on main, the auto-tag workflow creates an annotated v<version> tag and dispatches the release workflow. The initial repository commit is intentionally not auto-tagged.

The release workflow creates one draft release, builds Linux, macOS, and Windows artifacts in parallel from the immutable tag commit, uploads the updater manifests and a hashes.txt SHA-256 manifest, and publishes only after every platform job succeeds. Packaged Bronom builds use those manifests through electron-updater. The workflow can also be dispatched manually for an existing version tag.

Current releases are unsigned community builds: the binaries are not platform code-signed and macOS packages are not Apple-notarized. macOS Gatekeeper and Windows SmartScreen may therefore warn before first launch. Build jobs never receive release-write credentials; the final job publishes the completed set and generates GitHub artifact attestations. Verify a downloaded asset with gh attestation verify <asset> -R Netroforge/bronom, then compare it with hashes.txt.

Dependabot checks npm packages and GitHub Actions weekly and groups related Electron, Vue/Vite, MCP, and TypeScript updates. GitHub Pages deploys independently from the desktop release workflow.