How to Set Up SSH Agent Socket Forwarding into Containers

The Apple Container tool forwards your host's SSH authentication socket into containers via the --ssh flag, mounting it at /var/host-services/ssh-auth.sock and injecting the SSH_AUTH_SOCK environment variable automatically.

The apple/container repository provides native support for SSH agent forwarding, eliminating the need to copy private keys into container images. By appending the --ssh flag to any container command, developers can securely authenticate with remote Git repositories or SSH servers directly from inside the guest environment.

How SSH Agent Socket Forwarding Works

The implementation spans multiple Swift files across the codebase, handling detection, propagation, and mounting of the authentication socket.

Detecting the Host Socket

When a container starts with --ssh, the tool checks the host environment for the SSH_AUTH_SOCK variable. In Sources/ContainerCommands/Container/ContainerStart.swift (lines 91-93) and ContainerRun.swift (lines 131-132), the code reads ProcessInfo.processInfo.environment["SSH_AUTH_SOCK"] and adds the path to the dynamic environment passed to the VM-guest.

Propagating the Variable to the Guest

The runtime service receives this dynamic environment and validates the container configuration. In Sources/Services/RuntimeLinux/Server/RuntimeService.swift (lines 55-94), the sshAuthSocketHostUrl method checks if config.ssh is true, then extracts the socket path from the environment variables to create a URL pointing to the host's SSH agent.

Mounting the Socket in the Container

Once validated, the runtime mounts the host socket into the container filesystem. According to RuntimeService.swift (lines 1028-1035), the service 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 into the container's environment, ensuring processes inside can locate the forwarded socket.

Using the --ssh Flag

The user interface for this feature is the --ssh flag defined in Sources/ContainerAPIService/Client/Flags.swift (lines 191-220). When appended to any container sub-command, this flag sets ContainerConfiguration.ssh to true, triggering the entire forwarding pipeline.

To start a container with SSH forwarding:

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

To use SSH during a build:

container build --ssh myimage:latest .

Verifying SSH Agent Access Inside Containers

Once inside the container, verify the forwarding works by checking the environment variable and listing loaded keys:

env | grep SSH_AUTH_SOCK

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

ssh-add -l

The socket is dynamically resolved at container start time, meaning logging out and back in on the host, or changing the SSH agent socket, automatically updates for new container invocations without manual reconfiguration.

Summary

• The --ssh flag in apple/container automatically forwards your host's SSH agent into containers by detecting SSH_AUTH_SOCK at runtime.
• Implementation files include ContainerStart.swift, ContainerRun.swift, and RuntimeService.swift, which handle detection, validation, and mounting.
• The socket is mounted at /var/host-services/ssh-auth.sock with the SSH_AUTH_SOCK environment variable injected automatically.
• Works with all container sub-commands including run, exec, and build.
• No private keys are copied into the container, maintaining security boundaries while enabling seamless Git and SSH operations.

Frequently Asked Questions

Does the --ssh flag work with container exec?

Yes. The --ssh flag is available across all container sub-commands that accept configuration options, including container exec. When used, it triggers the same socket detection and mounting logic implemented in RuntimeService.swift, allowing processes inside existing containers to access the host's SSH agent.

What path is used for the forwarded SSH socket inside the container?

The socket is mounted at the fixed path /var/host-services/ssh-auth.sock inside the container, as implemented in RuntimeService.swift (lines 1028-1035). The environment variable SSH_AUTH_SOCK is automatically set to point to this location, allowing standard SSH tools to function without configuration changes.

Do I need to manually set SSH_AUTH_SOCK before running container commands?

No. The Apple Container tool automatically reads the SSH_AUTH_SOCK environment variable from the host's ProcessInfo.processInfo.environment when the --ssh flag is present. You only need to ensure your host SSH agent is running; the container runtime handles the detection and forwarding without manual configuration.

Is the forwarded socket updated if I change SSH agents on the host?

The socket path is resolved dynamically at container start time. Each invocation of a container command with --ssh re-reads the host's current SSH_AUTH_SOCK value. However, already running containers maintain their initial mount; to use a different socket, simply start a new container instance.

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