Connect to remote Docker over SSH

We recommend using the Visual Studio Code Remote-SSH extension to connect to a remote machine running Docker engine, but it also possible to connect to the remote Docker engine directly, using SSH tunneling.

Set up SSH Tunneling

  1. Use ssh-keygen or similar to get and configure a public/private key pair for SSH authentication. Password authentication is not supported by Docker and not possible with a DOCKER_HOST-based configuration. If a key pair has already been set up, it can be used.

  2. Configure ssh-agent on the local system with the private key file produced above.

    • Windows (OpenSSH): The latest version(s) of Windows 10 include OpenSSH by default. There is a Windows service, ssh-agent that is disabled by default, and needs to be re-enabled and set to automatic start. From an admin command prompt, run sc config ssh-agent start=auto and net start ssh-agent. Then, do ssh-add <keyfile>.

    • Windows (Pageant): You can use Pageant instead of OpenSSH, in which case it is necessary to set the environment variable SSH_AUTH_SOCK=pageant. Making that a user or system environment variable will be easiest.

    • Linux: ssh-agent is present by default. Do ssh-add <keyfile>. Ubuntu was tested; you might have different results on other distributions.

    • macOS: ssh-agent is present by default, but ssh-add does not persist across logins. Do ssh-add <keyfile>. We recommend configuring VS Code to run this command on terminal startup with terminal.integrated.shellArgs.osx or otherwise configuring a startup script. You can also manually run that command each login.

  3. Verify that your identity is available to the agent with ssh-add -l. It should list one or more identities that look something like 2048 SHA256:abcdefghijk somethingsomething (RSA). If it does not list any identity, you will not be able to connect. Also, it needs to have the right identity. The Docker CLI working does not mean that the Explorer window will work. The Explorer window uses dockerode (which in turn uses ssh2), whereas the Docker CLI uses the ssh command, and benefits from an automatically inferred configuration.

  4. Configure VS Code with your DOCKER_HOST to ssh://username@host:port. If you don't include username, it will use your current local user name, which might be wrong. If you omit the port, it defaults to 22.

    • You can use the DOCKER_HOST environment variable, or

    • There's a setting in VS Code, which has the same effect, but allows for user or workspace settings instead of machine settings.

  5. It is recommended to change the refresh rate to something longer with the docker.explorerRefreshInterval setting. The connection over SSH is slow, and it can result in trying to refresh again before the previous refresh even finished. We recommend at least 3000 ms.