Chromium Bridge

Chromium Bridge connects user-authorized local tools to the Chromium browser session you already use. The repository contains a Manifest V3 extension, a macOS Native Messaging host, a CLI, and a Codex MCP plugin.

The portable extension core handles tabs, compact page snapshots, interactions, user-supplied scripts, screenshots, optional cookies, and filtered network capture. Browser-specific providers stay separate; the included Arc provider can list and focus Spaces on macOS.

Security model

• Browser data is unavailable until the user approves website access in the extension popup.

• Website, tab, and cookie access remain unavailable until the user grants the optional permissions. Chromium requires the DevTools debugger permission at install time, but the extension's consent gate still blocks its use until local browser access is approved.

• Network capture requires a URL substring or an explicit all-URLs opt-in. Secret fields are redacted by default, and capture events and files are size-limited.

• The extension makes no requests to a developer-operated server. It sends requested data to the user-installed local host through Chromium Native Messaging.

• Local clients, including AI tools, decide how tool output is processed and may use third-party services. Review their privacy settings before exposing sensitive pages.

• Native Messaging origins are allowlisted, the host verifies the caller origin, and local sockets and captures are owner-only.

Read PRIVACY.md and SECURITY.md before using raw cookie or capture modes.

Related MCP server: Konnect

Install

Requirements:

• macOS

• Arc, Chrome, Chromium, Brave, Edge, or Vivaldi based on Chrome 138 or newer

• Codex desktop app or CLI. The installer detects codex in PATH and the CLI bundled inside ChatGPT.app or Codex.app.

Run:

curl -fsSL https://raw.githubusercontent.com/nextster/chromium-bridge/main/install.sh | sh

The installer opens the Unlisted Chrome Web Store listing. Chromium requires one explicit Add to browser confirmation; approve local browser access in the extension popup and enable Allow User Scripts when prompted.

The installer:

1. Uses an existing Node.js 20+ runtime, or installs a pinned and SHA-256-verified Node.js runtime under ~/.chromium-bridge.

2. Installs the Native Messaging host and CLI for supported Chromium browsers.

3. Copies the Codex marketplace to a persistent location and registers the Chromium Bridge plugin.

4. Opens the Unlisted Store listing and waits for extension installation, local-access consent, and Allow User Scripts.

5. Reports readiness after the browser bridge answers a live status check.

No administrator access, Homebrew, global npm package, HTTP server, or permanent source checkout is required. Restart Codex after first installation so it loads the plugin.

To inspect the installer before running it:

curl -fsSLo chromium-bridge-install.sh https://raw.githubusercontent.com/nextster/chromium-bridge/main/install.sh
less chromium-bridge-install.sh
sh chromium-bridge-install.sh

The equivalent development installation is:

git clone https://github.com/nextster/chromium-bridge.git
cd chromium-bridge
npm run setup -- --source

The setup command copies the unpacked extension and native runtime under ~/.chromium-bridge, registers the Native Messaging host, and installs the local Codex plugin.

For a source build, complete these browser steps once:

1. Enable Developer mode on the browser extensions page.

2. Choose Load unpacked and select ~/.chromium-bridge/extension.

3. Open the Chromium Bridge popup and approve local browser access.

4. Open the extension details and enable Allow User Scripts.

5. Reload Codex after the plugin is installed.

Run the one-command installer again to update installed components. Useful options are --no-open, --no-wait, --no-codex, and --dry-run. Set CHROMIUM_BRIDGE_REF=main only when intentionally testing the unreleased development branch.

Migrating from Load unpacked

Run the normal installation command. The installer refreshes the managed unpacked copy, verifies that the connected extension has the development ID, removes only that development extension, and opens the Store listing. Chromium still requires one explicit Add to browser confirmation. The installer then waits for the exact Store ID, new popup consent, and Allow User Scripts before deleting the obsolete local extension files.

An unpacked extension loaded directly from an arbitrary source checkout may be too old for automatic removal. In that case, remove that one development extension from the browser extensions page and rerun the installer; the Native Messaging host, Codex plugin, and captures remain intact.

Store installation

The Chrome Web Store can distribute only the extension. The Native Messaging host and Codex plugin remain a separate local companion because browser stores cannot install native executables.

The normal one-command installer uses Store mode. An explicit host-only installation remains available when the extension is already installed:

curl -fsSL https://raw.githubusercontent.com/nextster/chromium-bridge/main/install.sh | sh -s -- --host-only

Homebrew

The curl installer remains the shortest path and does not require Homebrew. Users who prefer Homebrew can install the companion from the official nextster tap:

brew install nextster/tap/chromium-bridge
chromium-bridge setup

brew install installs the versioned companion and its Node.js dependency. The explicit setup command registers the Native Messaging host for supported browsers, installs the Codex plugin, opens the Store listing, and performs the same readiness check as the curl installer.

Upgrade and re-register the installed companion with:

brew update
brew upgrade chromium-bridge
chromium-bridge setup

Before removing the Formula, unregister the companion and Codex plugin:

chromium-bridge uninstall
brew uninstall chromium-bridge

Update and uninstall

For curl installations, update by running the installation command again, or explicitly:

curl -fsSL https://raw.githubusercontent.com/nextster/chromium-bridge/main/install.sh | sh -s -- update

Remove the native host, CLI, development extension copy, portable runtime, and Codex plugin registration while preserving captures:

curl -fsSL https://raw.githubusercontent.com/nextster/chromium-bridge/main/install.sh | sh -s -- uninstall

Add --purge to delete captures and all remaining ~/.chromium-bridge data. The browser opens its extensions page because Chromium requires the user to remove the browser extension explicitly.

What it exposes

The Codex MCP server provides:

• Browser status and provider discovery

• Tab listing, background tab creation, navigation, and guarded cleanup

• Compact DOM snapshots with stable temporary refs

• Click, fill, select, wait, and user-supplied JavaScript execution

• Viewport screenshots

• Optional redacted cookie access and filtered network capture

• Replayable, shell-safe curl generation

• Arc Space listing and explicit Space focusing on macOS

Agent-created tabs open in the background by default and are tracked for cleanup. The MCP server closes remaining agent-owned tabs when it exits. Tabs that predate the MCP session cannot be closed without an explicit force flag.

CLI

The installer places the CLI at ~/.chromium-bridge/bin/chromium-bridge:

~/.chromium-bridge/bin/chromium-bridge status
~/.chromium-bridge/bin/chromium-bridge tabs
~/.chromium-bridge/bin/chromium-bridge eval active 'document.title'
~/.chromium-bridge/bin/chromium-bridge capture-start --filter example.com --body
~/.chromium-bridge/bin/chromium-bridge capture-stop
~/.chromium-bridge/bin/chromium-bridge curl
~/.chromium-bridge/bin/chromium-bridge purge

Captures use owner-only files under ~/.chromium-bridge/captures. purge deletes all prior capture sessions and clears the active log.

Architecture

Codex plugin or CLI
        |
        | NDJSON RPC over ~/.chromium-bridge/control.sock (0600)
        v
Native Messaging host <-> Chromium Bridge extension <-> Chromium APIs
        |
        +-> optional providers, including Arc Spaces through JXA

There is no HTTP server or listening TCP port. Chromium launches the native host over stdin/stdout; local clients use a private Unix socket.

Node.js runs the Native Messaging host, CLI, installer, tests, and Codex MCP server. It is not a web server and does not expose a network port. The installer uses a compatible system Node.js or a private verified runtime; it does not install Node globally.

Store release

npm run package:store

This creates a validated Store ZIP without the development key. The published Store item ID is recorded in store/item.json. To change it for a fork or a replacement item:

npm run configure:store -- ITEM_ID

Then reinstall the host, test the store build, and follow store/submission-checklist.md. Store copy, privacy declarations, permission explanations, reviewer instructions, and assets live under store/.

Compatibility

Version 0.6.0 renames the project from Chromium Sidecar to Chromium Bridge. The installer moves the previous state directory to ~/.chromium-bridge, preserves captures and a private Node runtime, removes obsolete Native Messaging and Codex registrations, and installs the new identifiers. Source-mode upgrades retain only an extension-path symlink so an already loaded unpacked extension can reload without manual repair.

• ARC_CODEX_* environment variables remain accepted for the former Arc-specific build.

• ~/.arc-codex-bridge/control.sock remains a compatibility socket when available.

• The source build retains the development extension ID eiffkmiekomnbpgamfchhehdafpnfgco.

New integrations should use CHROMIUM_BRIDGE_*, com.chromium_bridge.bridge, and ~/.chromium-bridge.

Development

npm test
npm run package:extension
npm run package:store
npm run package:source

See CONTRIBUTING.md for release and code-quality expectations. npm run uninstall performs a local source-checkout uninstall; npm run uninstall-host removes only Native Messaging manifests and runtime launchers.