FEATURES

SSH agent

A container can use the SSH agent on your Mac. git clone git@github.com:… or ssh inside the container then signs in with the keys you already loaded, without copying a private key into an image or a volume. The keys stay on the Mac; only the agent’s answers cross into the VM.

Use it in docker run

Mount the socket /run/host-services/ssh-auth.sock into the container and point SSH_AUTH_SOCK at it:

zsh
$ docker run --rm -it \
    -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock \
    -e SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock \
    alpine sh -c 'apk add -q openssh-client && ssh-add -l'
256 SHA256:Xz1q8mF0bq0r9cJt3k6Wl2v7nYp4hA5sDgE8uRiTo0c you@mac (ED25519)

ssh-add -l in the container lists the same keys as ssh-add -l on your Mac. The path is the same one Docker Desktop and OrbStack use, so scripts written for them work unchanged.

The source must be exactly /run/host-services/ssh-auth.sock. That path is not on your Mac; it’s a socket inside Kiri’s VM, and Kiri recognises it. The target can be any path you like, as long as SSH_AUTH_SOCK names it. --mount type=bind,src=/run/host-services/ssh-auth.sock,dst=… works too.

Use it in Compose

The same two lines, as a volume and an environment variable:

services:
  app:
    image: alpine/git
    volumes:
      - /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock
    environment:
      SSH_AUTH_SOCK: /run/host-services/ssh-auth.sock

How it’s forwarded

Kiri’s guest agent listens on /run/host-services/ssh-auth.sock in the VM. Each time a program in a container connects, the agent opens a vsock connection to Kiri’s daemon on the Mac, and the daemon connects to your Mac’s SSH agent and relays bytes both ways. Every connection gets its own relay.

Kiri’s VMYour Maccontainerssh, git$SSH_AUTH_SOCKguest agentlistens on the socketbind mount/run/host-services/ssh-auth.sockkiri daemonone relay eachssh-agentyour keysvsock$SSH_AUTH_SOCK
One connection to the agent: from ssh in the container, through the VM's socket and vsock, to the daemon, which relays it to your Mac's ssh-agent. Signing happens on the Mac.

The daemon uses the agent named by SSH_AUTH_SOCK in its own environment. When the daemon was started at login, without a shell, it asks launchd for the SSH_AUTH_SOCK of your login session. Load keys on the Mac with ssh-add as usual; containers see them at once.

Who can use it

Inside the VM the socket is open to every user, so a container that runs as a non-root user can use it, as with Docker Desktop. A container only reaches it if you mount it in; without the mount, the container has no way to the agent.

If the daemon finds no agent on the Mac, connections to the socket close straight away.

Volumes and mountsBind mounts, --mount and volumes.SecurityWhat containers can and can’t reach on your Mac.

© 2026 Kiri · runkiri.com