Support

Help for installing, connecting and removing Browser Control.

On this page:

• Get help
• The popup shows Disconnected
• Pause, resume and reload the host
• Uninstall and remove the native host
• Report a security issue
• Reviewer test steps: a full walkthrough that installs the host and shows the extension working

Get help

For everything else, such as setup problems, bugs, questions and feature requests, open an issue at github.com/opzero1/browser-control/issues. Issues are public. Include:

• The extension version, shown at the bottom of the Browser Control popup.
• Your operating system and your Google Chrome™ version.
• What the popup shows: Connected, Paused or Disconnected, and the text of the Error row if there is one.
• The output of these two commands, run in the helper folder that you unpacked:

  node scripts/check-native-host-manifest.js --json
  node native-host/client.js ping

The popup shows Disconnected

“Disconnected” means that the extension cannot reach the native messaging host. Try these steps in order.

1. Install the host. The extension does nothing until the host is installed. In the helper folder, run:

   node scripts/install-native-host.js --extension-id dcnjjnecbhipdbngkhjppkckpkellmld

   That ID is for the Chrome Web Store version. If you loaded an unpacked copy of the extension, use the ID that chrome://extensions shows for it.
2. Check the host manifest. Run node scripts/check-native-host-manifest.js --json. It reports a missing manifest, a missing host program or a wrong extension ID, and it prints a repair command.
3. Check Node.js. The host needs Node.js 18 or later. The host launcher looks for node on the PATH, then in /opt/homebrew/bin and /usr/local/bin, and then uses the Node.js that ran the installer. If you use a Node.js version manager, run the installer with the version that you want Chrome to use.
4. Keep the helper folder in place. The manifest points to the host by its full path. If you moved or renamed the folder, run the installer again.
5. Reload. Open the popup and click Reload host. While the host is not paused, the extension also retries the connection every 30 seconds.
6. Check the socket folder. After a crash, the host removes a leftover ~/.opzero-chrome/default.sock by itself when no running host answers on it. It still refuses to start if that path is not a socket, belongs to another user, or if the ~/.opzero-chrome folder is not private to your user account. To make the folder private:

   chmod 700 ~/.opzero-chrome

   Then click Reload host.
7. Use one Chrome profile at a time. All Chrome profiles share the same host manifest and socket. If Browser Control is turned on in more than one profile, only the first profile to start the host connects. Pause the host in the other profiles.
8. Wait for the version check. If node native-host/client.js ping reports Extension protocol v2 is not ready, the host is still checking the extension. This takes up to 10 seconds after the host starts. If the message stays, update the extension and the helper to matching versions, and then click Reload host.
9. Other browsers. The installer registers the host for Google Chrome™ only. For another browser, pass --manifest-path with the full path of the com.opzero.chrome.json file in that browser’s native messaging hosts folder.

Pause, resume and reload the host

Open the Browser Control popup from the Chrome toolbar. The status shows Connected, Connecting, Paused or Disconnected. Connecting means that Chrome started the host and the extension is waiting for its first reply. If the host does not reply within 15 seconds, or later stops answering, the extension drops it and starts a new one. When the host is not connected, or when there is an error, the popup also shows the host name, the time of the last check and the last error.

Reload host

Turns off pause, closes the connection and opens it again, so Chrome starts a new host process. Use it after you install or update the helper. If the popup still shows Disconnected, wait 30 seconds or click the button again.

Pause host

Closes the connection to the host, stops the automatic retries and ends every agent session. Agents lose access at once, and the debugger is detached from agent tabs. The setting stays in effect after Chrome restarts. The button then changes to Resume host.

Resume host

Turns off pause and connects to the host again.

Uninstall and remove the native host

1. Remove the extension on the chrome://extensions page. Chrome deletes the extension’s storage and closes its connection to the host.
2. Remove the native messaging host manifest and the host’s socket folder.

   macOS:

   rm "$HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.opzero.chrome.json"
   rm -r "$HOME/.opzero-chrome"

   Linux:

   rm "$HOME/.config/google-chrome/NativeMessagingHosts/com.opzero.chrome.json"
   rm -r "$HOME/.opzero-chrome"

   Windows (Command Prompt):

   reg delete "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.opzero.chrome" /f
   del "%USERPROFILE%\AppData\Local\opzero-chrome\com.opzero.chrome.json"

   If you installed with --manifest-path, delete the file at that path instead.
3. Delete the helper folder that you unpacked.
4. Delete any tab-video- recording folders that your agent tooling created.

The privacy policy lists everything that Browser Control stores.

Report a security issue

Do not describe a security problem in a public issue. Report it privately through GitHub, so that only the Browser Control maintainers can read it:

1. Open the private vulnerability report form at github.com/opzero1/browser-control/security/advisories/new. You need a GitHub account.
2. Describe the affected version, the steps to reproduce the problem and its impact.
3. Submit the report. The report and any follow-up discussion stay in that private advisory.

Use GitHub Issues for everything that is not a security problem.