Using ssh-agent with docker on macOS


Question or issue on macOS:

I would like to use ssh-agent to forward my keys into the docker image and pull from a private github repo.

I am using a slightly modified version of with boot2docker on Yosemite.

ssh-add -l
...key details
boot2docker up

Then I use the command which I have seen in a number of places (i.e.

docker run --rm -t -i -v $SSH_AUTH_SOCK:/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent my_image /bin/bash

However it doesn’t seem to work:

[email protected]:/# ssh-add -l
Could not open a connection to your authentication agent.

[email protected]:/# eval `ssh-agent -s`
Agent pid 19

[email protected]:/# ssh-add -l
The agent has no identities.

[email protected]:/# ssh [email protected]
Warning: Permanently added the RSA host key for IP address '' to the list of known hosts.
Permission denied (publickey).

How to solve this problem?

Solution no. 1:

A one-liner:

Here’s how to set it up on Ubuntu 16 running a Debian Jessie image:

docker run --rm -it --name container_name \
-v $(dirname $SSH_AUTH_SOCK):$(dirname $SSH_AUTH_SOCK) \

Solution no. 2:

I expanded on @wilwilson’s answer, and created a script that will setup agent forwarding in an OSX boot2docker environment.


# Use a unique ssh socket name per-invocation of this script

# ssh into boot2docker with agent forwarding
ssh -i ~/.ssh/id_boot2docker \
    -o StrictHostKeyChecking=no \
    -o IdentitiesOnly=yes \
    -o UserKnownHostsFile=/dev/null \
    -o LogLevel=quiet \
    -p 2022 [email protected] \
    -A -M -S $SSH_SOCK -f -n \
    tail -f /dev/null

# get the agent socket path from the boot2docker vm
B2D_AGENT_SOCK=$(ssh -S $SSH_SOCK [email protected] echo \$SSH_AUTH_SOCK)

# mount the socket (from the boot2docker vm) onto the docker container
# and set the ssh agent environment variable so ssh tools pick it up
docker run \
    -v $B2D_AGENT_SOCK:/ssh-agent \
    -e "SSH_AUTH_SOCK=/ssh-agent" \
    "[email protected]"

# we're done; kill off the boot2docker ssh agent
ssh -S $SSH_SOCK -O exit [email protected]

Stick it in ~/bin/docker-run-ssh, chmod +x it, and use docker-run-ssh instead of docker run.

Solution no. 3:

Since version, docker for macOS allows users to access the host’s SSH agent inside containers.

Here’s an example command that let’s you do it:

docker run --rm -it \
-v /run/host-services/ssh-auth.sock:/ssh-agent \
-e SSH_AUTH_SOCK="/ssh-agent" \

Note that you have to mount the specific path (/run/host-services/ssh-auth.sock) instead of the path contained in $SSH_AUTH_SOCK environment variable, like you would do on linux hosts.

Solution no. 4:

I ran into a similar issue, and was able to make things pretty seamless by using ssh in master mode with a control socket and wrapping it all in a script like this:


ssh -i ~/.vagrant.d/insecure_private_key -p 2222 -A -M -S ssh.socket -f [email protected] tail -f /dev/null

HOST_SSH_AUTH_SOCK=$(ssh -S ssh.socket [email protected] env | grep "SSH_AUTH_SOCK" | cut -f 2 -d =)

docker run -v $HOST_SSH_AUTH_SOCK:/ssh-agent \
       -e "SSH_AUTH_SOCK=/ssh-agent" \
       -t hello-world "[email protected]"

ssh -S ssh.socket -O exit [email protected]

Not the prettiest thing in the universe, but much better than manually keeping an SSH session open IMO.

Solution no. 5:

For me accessing ssh-agent to forward keys worked on OSX Mavericks and docker 1.5 as follows:

  1. ssh into the boot2docker VM with boot2docker ssh -A. Don’t forget to use option -A which enables forwarding of the authentication agent connection.

  2. Inside the boot2docker ssh session:

    [email protected]:~$ echo $SSH_AUTH_SOCK /tmp/ssh-BRLb99Y69U/agent.7750 

This session must be left open. Take note of the value of the SSH_AUTH_SOCK environmental variable.

  1. In another OS X terminal issue the docker run command with the SSH_AUTH_SOCK value from step 2 as follows:

    docker run --rm -t -i \ -v /tmp/ssh-BRLb99Y69U/agent.7750:/ssh-agent \ -e SSH_AUTH_SOCK=/ssh-agent my_image /bin/bash [email protected]:/# ssh-add -l 2048 6c:8e:82:08:74:33:78:61:f9:9a:74:1b:65:46:be:eb /Users/dev/.ssh/id_rsa (RSA) 

I don’t really like the fact that I have to keep a boot2docker ssh session open to make this work, but until a better solution is found, this at least worked for me.

Solution no. 6:

By default, boot2docker shares only files under /Users. SSH_AUTH_SOCK is probably under /tmp so the -v mounts the agent of the VM, not the one from your mac.

If you setup your VirtualBox to share /tmp, it should be working.

Solution no. 7:

Socket forwarding doesn’t work on OS X yet. Here is a variation of @henrjk answer brought into 2019 using Docker for Mac instead of boot2docker which is now obsolete.

  1. First run a ssh server in the container, with /tmp being on the exportable volume. Like this

     docker run -v tmp:/tmp -v \ ${HOME}/.ssh/ \ -d -p 2222:22 arvindr226/alpine-ssh 
  2. Then ssh into this container with agent forwarding

     ssh -A -p 2222 [email protected] 
  3. Inside of that ssh session find out the current socket for ssh-agent

     3f53fa1f5452:~# echo $SSH_AUTH_SOCK /tmp/ssh-9zjJcSa3DM/agent.7 
  4. Now you can run your real container. Just make sure to replace the value of SSH_AUTH_SOCK below, with the value you got in the step above

     docker run -it -v tmp:/tmp \ -e SSH_AUTH_SOCK=/tmp/ssh-9zjJcSa3DM/agent.7 \ vladistan/ansible 

Solution no. 8:

Could not open a connection to your authentication agent.

This error occurs when $SSH_AUTH_SOCK env var is set incorrectly on the host or not set at all. There are various workarounds you could try. My suggestion, however, is to dual-boot Linux and macOS.

Additional resources:

  • Using SSH keys inside docker container – Related Question
  • SSH and docker-compose – Blog post
  • Build secrets and SSH forwarding in Docker 18.09 – Blog post

Hope this helps!