How to Forward SSH Agent Sockets and Publish Unix Sockets to Containers

Use the --ssh flag with any container command to automatically forward the host’s SSH authentication socket into the guest at /var/host-services/ssh-auth.sock, exposing it via the SSH_AUTH_SOCK environment variable.

The apple/container repository provides first-class support for forwarding SSH agent sockets and publishing Unix sockets to containers, enabling secure authentication without copying private keys into images. By leveraging dynamic environment detection and volume mounting, the toolchain allows containers to use the host’s running ssh-agent for git operations and SSH connections.

How SSH Agent Forwarding Works

Detecting the Host Socket

When a container starts with --ssh, the CLI inspects the parent environment to locate the authentication socket. In Sources/ContainerCommands/Container/ContainerStart.swift (lines 91-93) and ContainerRun.swift (lines 131-132), the code checks ProcessInfo.processInfo.environment["SSH_AUTH_SOCK"]. If the variable exists, its value is captured and added to the dynamic environment passed to the VM guest.

Propagating to the Guest Runtime

The runtime service receives the dynamic environment and validates the container configuration. In Sources/Services/RuntimeLinux/Server/RuntimeService.swift, the sshAuthSocketHostUrl method (lines 55-94) verifies that config.ssh is enabled, then extracts the socket path from the environment variables. This URL is returned for use as a mount point.

Mounting the Socket and Configuring the Environment

The implementation creates a bind mount and sets the appropriate environment variable. According to lines 1028-1035 in RuntimeService.swift, the runtime adds a volume mount from the host socket URL to the fixed guest path /var/host-services/ssh-auth.sock. Simultaneously, lines 1074-1075 inject the SSH_AUTH_SOCK environment variable, setting it to /run/host-services/ssh-auth.sock so processes inside the container can locate the forwarded agent.

Using the --ssh Flag

The command-line interface exposes this functionality through a single flag defined in Sources/ContainerAPIService/Client/Flags.swift (lines 191-220). When present, the flag toggles ContainerConfiguration.ssh to true, triggering the full forwarding pipeline.

Run an interactive container with SSH forwarding:

container run -it --rm --ssh alpine:latest sh

Inside the container, verify the setup:

env | grep SSH_AUTH_SOCK

# SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock

apk add --no-cache openssh-client
ssh-add -l

# Lists keys loaded in the host ssh-agent

Use forwarding during image builds:

container build --ssh myimage:latest .

Dynamic Resolution Behavior

The socket path is resolved at container start time rather than build time. Because RuntimeService.swift re-reads the host’s SSH_AUTH_SOCK variable on every invocation with --ssh, logging out and back in—or changing terminal sessions—does not require manual updates. Each new container automatically points to the current host socket.

Summary

• Activate forwarding by adding --ssh to any container sub-command (run, exec, start, build).
• Detection occurs in ContainerStart.swift and ContainerRun.swift by reading the host’s SSH_AUTH_SOCK environment variable.
• Implementation in RuntimeService.swift mounts the socket to /var/host-services/ssh-auth.sock and exports SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock.
• Security is maintained by never copying private keys into the container; only the authentication socket is forwarded.
• Flexibility is provided through dynamic path resolution, ensuring containers always use the current host agent session.

Frequently Asked Questions

How do I verify that SSH agent forwarding is active inside the container?

Run env | grep SSH_AUTH_SOCK to confirm the variable is set to /run/host-services/ssh-auth.sock, then execute ssh-add -l to display the keys loaded in your host agent. If the key list appears without error, the forwarding is functioning correctly.

Can I use --ssh with container build commands?

Yes. The --ssh flag is supported by all container sub-commands that accept configuration, including container build. This allows build processes to clone private repositories or access secure resources using your host SSH credentials.

Where exactly is the socket mounted inside the container?

The host authentication socket is bind-mounted to the fixed path /var/host-services/ssh-auth.sock. The environment variable SSH_AUTH_SOCK is set to /run/host-services/ssh-auth.sock to ensure standard SSH clients locate the forwarded socket automatically.

What happens if my SSH agent socket path changes after starting a container?

The socket path is resolved dynamically at container start time. Because RuntimeService.swift checks the host’s environment variable on every invocation with --ssh, subsequent containers automatically use the new socket path without requiring configuration changes or restarts of the container service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}