fix: connect-existing with remote/containerized Firefox by MayCXC · Pull Request #50 · mozilla/firefox-devtools-mcp

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC · 2026-03-28T08:01:05Z

Summary

Fixes several issues that prevented --connect-existing from working with Firefox running on a remote host or in a separate container (e.g., via SSH tunnel).

Bug fixes

--marionette-host CLI arg was silently ignored. The option was parsed and the type had the field, but it was never passed to the options object. Geckodriver always connected to 127.0.0.1.
selenium-manager downloaded a 307MB Firefox binary. In connect-existing mode Firefox is already running. Changed --browser firefox to --driver geckodriver so selenium-manager only downloads the driver (~5MB).
No cleanup on disconnect. No lifecycle handling existed. The Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that clean up Firefox and close the server before exiting, following the pattern from the MCP SDK examples. StdioServerTransport does not currently fire onclose on stdin EOF (PR #1814), so raw stdin listeners are included as a workaround.
kill() skipped session cleanup. Was synchronous and did not send DELETE /session. Made async with session cleanup so Marionette accepts new connections.
Seamless reconnect after Firefox restart.getFirefox() now detects a lost connection and reconnects transparently instead of throwing an error on the first call.

New features

--marionette-host parameter. Controls which host geckodriver connects to for Marionette and where the BiDi WebSocket URL is rewritten to point. Supports MARIONETTE_HOST env var.
BiDi support for connect-existing. Opens a WebSocket to Firefox's Remote Agent using the webSocketUrl session capability, enabling console and network event monitoring.

Test plan

list_pages works with --connect-existing --marionette-host host.internal
list_console_messages returns BiDi data
Quit and restart Firefox without MCP reconnect: seamless reconnect on next tool call, pages and BiDi both work
MCP reconnect without quitting Firefox: old container exits cleanly (no zombie), new container connects, pages and BiDi both work
No stale Marionette sessions after disconnect

Supersedes #51.

When using --connect-existing to connect to Firefox running on a different host (e.g., via SSH tunnel or in a separate container), several issues prevented it from working: 1. The --marionette-host CLI arg was parsed but never passed to the options object, so geckodriver always connected to 127.0.0.1. 2. selenium-manager was invoked with --browser firefox, causing it to download a 307MB Firefox binary that connect-existing never uses. Changed to --driver geckodriver to fetch only the driver. 3. No cleanup on disconnect: the Marionette session was never released when the MCP client disconnected, so Firefox refused new connections until restarted. Added SIGTERM/SIGINT/stdin handlers that call firefox.close() before exit. Raw stdin listeners are needed because StdioServerTransport does not fire onclose on stdin EOF. 4. kill() was synchronous and skipped DELETE /session, leaving stale sessions. Made it async and added session cleanup. 5. BiDi was unavailable in connect-existing mode. Added WebSocket support via the webSocketUrl session capability, with URL rewriting for remote hosts. BiDi subscription failure is non-fatal so Classic WebDriver continues working.

MayCXC · 2026-03-29T13:50:53Z

@juliandescottes @freema iterated on this a bit, it is ready now.

freema · 2026-03-29T14:01:12Z

Hey @MayCXC, this looks great, thanks! I'll merge this into main. I'll add tests and do some manual testing, then cut a new release.

Small note: kill() is now async but reset() calls it without await — I'll fix that when adding tests.

- Fix prettier formatting (long lines, missing line breaks) - Fix curly brace requirement for if statements - Fix no-base-to-string: use String() instead of .toString() - Fix no-floating-promises: void async kill() in reset() - Fix no-misused-promises: wrap async cleanup in void handler - Remove unused FirefoxDisconnectedError import - Fix IBiDi type to include subscribe method - Fix type narrowing for bidiConnection return Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests cover: - GeckodriverHttpDriver BiDi: getBidi(), subscribe, caching, error handling - Session cleanup: kill() and quit() send DELETE /session - kill() resilience when DELETE fails - marionetteHost option passthrough - Reconnect: reset() clears driver state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

juliandescottes · 2026-04-27T15:04:58Z

@MayCXC

Hi Aaron,

Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966

We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

MayCXC · 2026-04-27T15:43:38Z

@MayCXC
Hi Aaron,
Already sent an email, but trying here as well. We want to update the project's license to Apache/MIT https://bugzilla.mozilla.org/show_bug.cgi?id=2032966
We need the agreement from existing contributors to proceed. If you are OK with the change, could either reply here or by email to say that you agree. Let me know if you have any question.

OK with me 👍

juliandescottes · 2026-04-27T15:50:37Z

Thanks a lot!

MayCXC force-pushed the connect-existing-bidi-v2 branch from 1b0f461 to fcd5855Compare March 28, 2026 08:16

MayCXC mentioned this pull request Mar 28, 2026
Add --marionette-host for remote/tunneled Firefox #51
Closed

MayCXC force-pushed the connect-existing-bidi-v2 branch 2 times, most recently from ae0f07a to 5f6b39fCompare March 29, 2026 11:54

MayCXC changed the title ~~Enable BiDi support for connect-existing mode~~fix: connect-existing with remote/containerized FirefoxMar 29, 2026

MayCXC force-pushed the connect-existing-bidi-v2 branch 6 times, most recently from 478f62d to 4740414Compare March 29, 2026 13:41

MayCXC force-pushed the connect-existing-bidi-v2 branch from 4740414 to c02fc02Compare March 29, 2026 13:48

freema merged commit 6e17b50 into mozilla:mainMar 29, 2026

freema mentioned this pull request Mar 29, 2026
test: add unit tests for connect-existing mode #52
Merged
3 tasks