Skip to content

Chrome DevTools for coding agents

docs: add VM-to-host remote debugging workaround (#399)

circle339f9dab0787f1
diff --git a/README.md b/README.md
index 1aaab3e6..0b78b85b 100644
--- a/README.md
+++ b/README.md
@@ -421,6 +421,8 @@ Check the performance of https://developers.chrome.com
Your MCP client should connect to the running Chrome instance and receive a performance report.
+If you hit VM-to-host port forwarding issues, see the “Remote debugging between virtual machine (VM) and host fails” section in [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails).
+
For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/).
## Known limitations
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 302fe560..7fc62eac 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -27,3 +27,14 @@ npm cache clean --force
This indicates that the browser could not be started. Make sure that no Chrome
instances are running or close them. Make sure you have the latest stable Chrome
installed and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en).
+
+### Remote debugging between virtual machine (VM) and host fails
+
+When connecting DevTools inside a VM to Chrome running on the host, any domain is rejected by Chrome because of host header validation. Tunneling the port over SSH bypasses this restriction. In the VM, run:
+
+```sh
+ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 <user>@<host-ip>
+```
+
+Point the MCP connection inside the VM to `http://127.0.0.1:9222` and DevTools
+will reach the host browser without triggering the Host validation.