skip to Main Content

What is the "correct" or suggested way to have multiple developers (2 in this case) using Xdebug from their Windows desktops to debug code running on a Linux server over SSH?

The standard configuration of VSCode for editing over SSH installs a vscode NodeJS server component on the Linux host, so when Xdebug is used it is that local server which opens port 9003 and VSCode communicates over the SSH link with that. Therefore a second client connecting will try to also open 9003 to localhost on the Linux server and fail.

Using a proxy is one solution to this, although I struggled yesterday to make it work using dbgbProxy (I also tried the Komodo Python script but that doesn’t support current versions of Python). I did get php-xdebug-proxy working in the end. Even then it means that each client needs to set their own unique key within vscode and the browser they’re using.

On the other hand xdebug’s discover_client_host seems like a cleaner solution (at least for my use case where the server is a development box on the local network). But if there’s a way to get vscode to use that I couldn’t find it; I tried the alternative SSH-FS extension but I couldn’t get the xdebug extension to work with the virtual file system despite that being supported by recent versions (the debugger ran but it was unable to map the file locations).

Either way I couldn’t find any clear instructions online with example configurations, and a lot of what I did find was threads here and elsewhere that were years old and therefore out of date.

A working ssh-fs solution would be my preference, as I don’t like having vscode-server installed on every server I touch – sometimes it’s appropriate, others it isn’t, others it simply won’t work (eg on a system with a readonly filesystem). But I’d also be happy to get dbgbproxy working as php-xdebug-proxy has a lot of dependencies to pull in.



  1. If all machines are on the same LAN, then you can set xdebug.discover_client_host=1. It instructs Xdebug to connect to the IP address that was in the HTTP header, instead of the configured IP address (through xdebug.client_host). Remember that it is Xdebug that makes a TCP connection to your IDE.

    VS Code (or any other IDE) needs to listen for incoming debugging connections — which is the same as for single-user connections.

    Requesting a PHP script/application through the browser with Xdebug activated (either through xdebug.start_with_request=always or a browser extension) would be enough for Xdebug on the server, to find the IP address of the machine that initiated the HTTP request. Xdebug will always want to connect to the configured port on that IP address (of the machine running the browser).

    If the Linux server is not on the same network, then dbgpProxy can work, as long as PHP/Xdebug can connect to that debug proxy. You then need to configure and use these IDE keys so that the proxy knows where to forward the incoming debug request to. I have made a video explaining this in greater detail:

    Neither the discover_client_host nor dbgpProxy methods do anything with SSH.

    If neither the above-mentioned methods work in your set-up, then can alternatively have a look at Xdebug Cloud, which allows for debugging in more complicated scenarios.

    Login or Signup to reply.
  2. Since you said you’d prefer using sshfs I suggest the following.

    1. You will be running VS Code on your workstation, have a workspace folder – so you can store the sshfs config somewhere – and the server folder mounded via sshfs.

    2. The .vscode/launch.json is going to be on the server side, because the path mappings should be the same for all users.

    3. The debugger will be running on your workstation inside VS Code, and that means Xdebug (within the PHP server) will connect back to your workstation. This will be achieved via xdebug.discover_client_host=1 php.ini setting.

    4. Your launch.json will contain path mappings in this manner:

    { "version": "0.2.0", "configurations": [ 
            "name": "Listen for Xdebug",
            "type": "php", 
            "request": "launch", 
            "pathMappings": { "/var/www/html": "ssh://server.domain.lan/var/www/html" },
    ] }

    The local path (ssh://server...) is hardcoded because there is currently a bug in VS Code preventing normal variable subsitution.

    After it is fixed the line could look like this:

    "pathMappings": { "/var/www/html": "${workspaceFolder}" },

    Do not forger, you will also need a Xdebug Browser helper.

    I suggest you use xdebug_info() to get an idea what is happening when you open the script in your browser.

    There are also other combinations possible, so let me know if this does not work for you.

    Login or Signup to reply.
Please signup or login to give your own answer.
Back To Top