Skip to content

0005. Colima SSH Agent Forwarding Chain

Status

Accepted

Context

The host environment is macOS with 1Password providing the SSH agent, and Colima (backed by Lima) providing the Docker runtime. The requirement is:

  • SSH private keys must never exist on disk inside the container.
  • Git operations and SSH connections use keys held in 1Password.
  • The 1Password SSH agent socket on macOS must be reachable from inside the container.

The challenge is that Colima interposes a Lima VM between macOS and Docker containers. The socket forwarding chain is:

macOS 1Password SSH Agent
  -> SSH_AUTH_SOCK on macOS (1Password agent socket)
    -> Colima/Lima VM (forwarded via --ssh-agent or Lima's SSH forwarding)
      -> Container (bind-mounted from VM path)

Unlike Docker Desktop or OrbStack, the macOS-native socket is not directly accessible from containers — it must transit through the VM.

Decision

Use the following forwarding chain:

  1. macOS: 1Password desktop app with "Use the SSH agent" enabled. SSH_AUTH_SOCK must be exported to point to the 1Password agent socket: 

    export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
    The ~/.ssh/config IdentityAgent directive handles direct SSH on the host, but Colima only forwards the socket referenced by SSH_AUTH_SOCK.

  2. Colima: Start with colima start --vm-type=vz --ssh-agent --cpu 8 --memory 8 --disk 60 to forward SSH_AUTH_SOCK from macOS into the Lima VM. The forwarded agent appears at /run/host-services/ssh-auth.sock inside the VM.

  3. Container: devcontainer.json bind-mounts the VM-side socket at /run/host-services/ssh-auth.sock and sets SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock in remoteEnv.

  4. Validation: entrypoint.sh runs ssh-add -l on every start and emits a diagnostic message pointing to the most likely broken link if it fails.

Consequences

Easier: - Zero SSH private keys on disk — anywhere in the chain. - Works with any SSH key managed by 1Password (no per-key configuration). - SSH commit signing works transparently via the same agent.

Harder: - The socket path in the VM depends on the Colima/Lima version. The hardcoded path /run/host-services/ssh-auth.sock is the standard Lima convention but may change. The README includes a troubleshooting matrix for this. - Colima must be started with --ssh-agent (or configured in ~/.colima/default/colima.yaml). Forgetting this breaks the entire chain. - SSH_AUTH_SOCK on macOS defaults to the system ssh-agent, which has no keys. It must be explicitly set to the 1Password socket, or Colima forwards an empty agent. - Socket permissions in the VM may require chmod if Colima maps it with restrictive permissions. The entrypoint validates and reports this.