Connect your Docker client to a remote Docker host

It's often useful to connect to a remote Docker host to run commands such as checking the status of containers and viewing logs etc.

I recently wrote about using Docker Machine to create a new Docker host on Azure. But what if you need to connect to an existing Docker host? That's what I'll cover in this post.


We'll need to be able to SSH into the remote host. I've written up detailed instructions here. In summary, if you don't already have an SSH key, you'll need to generate one:

ssh-keygen -t rsa

And then copy it to the remote machine:

ssh-copy-id {username}@{host}

Later, Docker Machine will be sending commands over SSH on our behalf, so you'll need to be able to enter sudo mode without entering your password. You may want to only enable this while we configure Docker Machine. SSH to the remote machine and edit the sudoers file:

sudo nano /etc/sudoers

And add the following to the end of the file where {username} is your username on the remote machine:

{username}  ALL=(ALL) NOPASSWD:ALL

Save the file, logout and login again and you should be able to enter sudo mode without entering your password.

Make sure the Docker port is open

Docker Machine will SSH to the remote machine to configure the Docker engine. The Docker client will then connect on TCP port 2376. You'll need to make sure this port is open on your firewall. If you're using Azure, configure your Network Security Group like this:

Add the remote machine using Docker machine

We can now use the docker-machine command to register the remote Docker host. On your client machine enter the following command. You'll need to substitute values for ip-address, bash-username, remote-ssh-username and remote-docker-host for your environment:

docker-machine create --driver generic --generic-ip-address={ip-address} --generic-ssh-key "%localappdata%/lxss/home/{bash-username}/.ssh/id_rsa" --generic-ssh-user={remote-ssh-username} {remote-docker-host}

For example on Windows 10 with the Linux subsystem installed:

docker-machine create --driver generic --generic-ip-address= --generic-ssh-key "%localappdata%/lxss/home/kevin/.ssh/id_rsa" --generic-ssh-user=kevin remote-docker-host

Or on Linux:

docker-machine create --driver generic --generic-ip-address= --generic-ssh-key ~/.ssh/id_rsa --generic-ssh-user=kevin remote-docker-host

Configure the Docker client to use the remote engine

Finally, we need to tell your local Docker client to use a remote Docker engine. The following command will show the environment variables you need to set:

docker-machine env {remote-docker-host}

For example on my machine:

docker-machine env remote-docker-host


SET DOCKER_CERT_PATH=C:\Users\kevin\.docker\machine\machines\remote-docker-host
SET DOCKER_MACHINE_NAME=remote-docker-host
REM Run this command to configure your shell:
REM     @FOR /f "tokens=*" %i IN ('docker-machine env remote-docker-host') DO @%i

Next, simply copy and execute the last line and your Docker client will be configured to use the remote Docker engine:

@FOR /f "tokens=*" %i IN ('docker-machine env remote-docker-host') DO @%i

That's it. Commands you enter using your local Docker client will be executed by the remote Docker engine.

These settings will only apply to your current command prompt session. You can check which Docker engine you are connected to by running:

docker-machine ls