Connecting to Deployment Servers and Remote Interpreters with SSH-Agent

When you work with remote servers, a common and recommended security measure is to use SSH key pairs for authentication.

Our friends at PyCharm have prepared a great blog post on the topic. It explains how to generate an SSH key pair, store the passphrase for the private key in the credential helper, and, in the end, how to connect to a remote Python interpreter over SSH using the generated key pair for authentication.

Before proceeding, make sure that you have a remote machine at hand to which you can connect over SSH using the generated key pair. Also, make sure to add your key to the credential helper application (SSH agent, Pageant, or a compatible tool). If you don’t have a spare remote machine, you can use the example Vagrant box provided as part of the above tutorial.

When ready, jump right into the PhpStorm specifics.

Using SSH key-based authentication in PhpStorm

In PhpStorm, we can make use of SSH keys and credential helper applications in two areas: when configuring remote deployment servers and remote PHP interpreters. Both scenarios involve the same setup technique, and we can actually reuse an existing remote deployment server configuration for setting up an interpreter.

Setting up a remote deployment server

To connect to a remote deployment server over SSH, we need to create a new server access configuration of the SFTP type.

Navigate to Settings / Preferences | Build, Execution, Deployment | Deployment. Then, click + to add a new SFTP server:


Next, provide the server parameters:


In this tutorial, we’ll use the values that will allow us to connect to the example Vagrant box:

  • SFTP host: localhost
  • Port: 2222 (the default port that Vagrant exposes for SSH).
  • User name: example
  • Auth type: Authentication agent (ssh-agent or Pageant)

By setting authentication method to Authentication agent, you’re instructing PhpStorm to use the credentials stored in the credential helper application (SSH agent, Pageant, or a compatible tool).

Once the parameters are set, test your connection, apply the changes, and you’re good to go!

The remote server that we have configured will probably handle our PHP code as well. We can reuse its configuration for setting up a remote PHP interpreter. First, let’s ensure that PHP is installed on the remote server. Select Tools | Start SSH Session… in the main menu and select the remote host in the pop-up window:


Since your SSH keys are managed by the credential helper, the SSH session should instantly start in the built-in PhpStorm terminal without requiring you to type anything. To find out whether PHP is installed, run the php -v command:


The command is not found, which means that PHP is not installed. We can easily fix this by running the following command:

sudo apt-get install php

Note that this command requires elevated privileges, i.e. entering your password. In our Vagrant box, the password for the example user is set to hunter2. Type it in when prompted, and wait a short while until PHP is installed. To be absolutely sure, you can run the php -v command once more:


Setting up a remote PHP interpreter

PHP is now installed on a remote server, and instructing PhpStorm to use it could not be simpler. Navigate to Settings / Preferences | Languages & Frameworks | PHP and click the ellipsis (…) button next to the CLI Interpreter field:


In the opened CLI Interpreters window, click + and select the From Docker, Vagrant, VM, Remote… interpreter type:


PhpStorm will detect a remote deployment server configuration that we created earlier and will suggest reusing it as a configuration for the remote interpreter:


Click OK, apply your changes, and you are done! You can now upload, download, and manage remote files directly in PhpStorm, as well as execute your PHP code remotely.

As a side note, if you need to set up only a remote PHP interpreter, without reusing an existing deployment configuration, choose the SSH Credentials option in the above dialog box. Provide the server parameters and select the Authentication agent (ssh-agent or Pageant) authentication type – just as you would for configuring a remote deployment server.

JetBrains PhpStorm Team
The Drive to Develop

This entry was posted in Cool Feature, Newsletter, Tutorial and tagged , . Bookmark the permalink.
  • mlcy

    I upgraded phpstrom from 2017.2 to 2017.2.4 on Mac, but i don’t see “deployment” as a setting under “Build, Execution, Deployment”. Does anyone know how to make it show up? Thanks in advance.

    • Eugene Morozov

      Please navigate to Settings/Preferences | Plugins and check that all built-in plugins are enabled.

  • Mickaël Perrin

    That’s definitely a great addition, thanks a lot for this feature. However, when you have multiple keys in the agent, phpstorm may fail to establish the connection. The error message is SSH_MSG_DISCONNECT: 2 Too many authentication failures. Are there any plans to support kind of IdentitiesOnly, so the connection could be established with the adequate certificate and not the first ones ?

    • Dmitry Tronin

      Since 2017.3 you’ll be able to use openssh config files (see where you can indeed toggle IdentitiesOnly. Would that work for you?

      • Mickaël Perrin

        Thanks, for your answer. Sadly, it looks like it doesn’t work.

        I use, indeed, a ssh config file. But when I encounter the error in Phpstorm, a simple `ssh server_name` in terminal works.

        My ssh config file has the IdentitiesOnly applied for all servers.

        • Dmitry Tronin

          Thanks for the info. Starting 2017.3 you shouldn’t receive SSH_MSG_DISCONNECT errors for servers with IdentitiesOnly configured. If you encounter that problem on 2017.3 – feel free to submit a corresponding report at our tracker:

  • frenchbeast

    There is something i don’t really understand. How does it know which ssh-agent to use?
    I have an one loaded with my keys including one coming from a YubiKey.
    InteliJ doesn’t seem to pick it up.
    Is there a way to give the socket or the pid to use?

    • Eugene Morozov

      The thing is that PhpStorm doesn’t have to know anything about the ssh-agent – it just executes a command like “ssh hostname” and lets the system to take care of everything else.
      Does “ssh -v hostname” work for you in Terminal?

      • frenchbeast

        Hello Eugene,
        Yes it does work from my terminal.
        I there a recommendation on how to start the ssh-agent?
        Or maybe a environmental variable to set?