How to Forward SSH Agent Sockets Into Containers with the Apple Container Tool

The Container tool provides a first-class --ssh flag that automatically forwards the host's SSH authentication socket into the guest container by mounting it at /run/host-services/ssh-auth.sock and injecting the SSH_AUTH_SOCK environment variable.

The Apple Container repository offers secure SSH agent forwarding that eliminates the need to copy private keys into containers. When you forward SSH agent sockets into containers, you can authenticate with Git remotes and SSH servers using your host's existing agent without exposing sensitive credentials.

How the --ssh Flag Works

The implementation follows a three-stage pipeline from host detection to guest mount:

Detecting the Host SSH Agent

When a container starts, the code checks ProcessInfo.processInfo.environment["SSH_AUTH_SOCK"] to locate the host's authentication socket. If the variable exists, its path is added to the dynamic environment passed to the VM guest.

This detection occurs in:

• Sources/ContainerCommands/Container/ContainerStart.swift (lines 91‑93)
• Sources/ContainerCommands/Container/ContainerRun.swift (lines 131‑132)

Propagating the Socket to the Guest

The runtime service receives the dynamic environment and extracts the SSH_AUTH_SOCK value in RuntimeService.swift::sshAuthSocketHostUrl. When the container configuration has ssh = true, this method validates the configuration and creates a URL pointing to the host socket path from the dynamic environment (lines 55‑94).

Mounting the Socket Inside the Container

During container configuration building, the runtime adds a volume mount from the host socket URL to the fixed guest path /run/host-services/ssh-auth.sock. It also injects the SSH_AUTH_SOCK environment variable pointing to this path so processes inside the container can locate the forwarded agent.

This mount logic is implemented in Sources/Services/RuntimeLinux/Server/RuntimeService.swift (lines 1028‑1035), with environment variable injection at lines 1074‑1075.

Using the --ssh Flag

The --ssh flag is defined in Sources/ContainerAPIService/Client/Flags.swift (lines 191‑220) and toggles ContainerConfiguration.ssh to true. You can use it with any container sub-command that accepts configuration.

Basic Container Execution

Forward your SSH agent into an interactive shell:

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

Inside the container, verify the forwarding works:

env | grep SSH_AUTH_SOCK

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

apk add --no-cache openssh-client git
ssh-add -l
git clone git@github.com:myorg/private-repo.git

Building Images with SSH Access

Use the flag during build operations when you need to access private repositories:

container build --ssh myimage:latest .

Dynamic Updates

Because the socket path is resolved at container start time, logging out or changing the host socket does not require manual updates. The runtime always re-reads SSH_AUTH_SOCK when --ssh is used, ensuring the mount points to the current socket.

Technical Implementation Details

The forwarding mechanism relies on coordination between several components:

ContainerConfiguration (Sources/ContainerResource/Container/ContainerConfiguration.swift) stores the ssh: Bool flag that controls whether the socket should be mounted.

Host Detection occurs in the command implementations:

• ContainerStart.swift handles container start
• ContainerRun.swift handles container run

Runtime Service (RuntimeService.swift) performs the actual socket resolution and mount creation in the Linux runtime server.

Summary

• The --ssh flag automatically forwards your host's SSH agent socket into containers without manual volume mounts.
• Host detection reads SSH_AUTH_SOCK from the process environment at container start time.
• The socket is mounted at /run/host-services/ssh-auth.sock inside the container with the corresponding environment variable injected.
• Implementation spans ContainerStart.swift, ContainerRun.swift, RuntimeService.swift, and Flags.swift.
• The feature works with run, exec, build, and other container sub-commands.

Frequently Asked Questions

How do I verify SSH agent forwarding is working inside a 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 list the keys loaded in your host's agent. If you see your keys listed, the forwarding is active and you can authenticate with SSH-based Git operations or remote servers.

Does the --ssh flag work with all container commands?

Yes, the --ssh flag works with any container sub-command that accepts a configuration object, including run, exec, build, and start. The flag is defined in Flags.swift and simply toggles the ssh boolean in the container configuration, which the runtime service checks when setting up the container environment.

What happens if SSH_AUTH_SOCK is not set on the host?

If the SSH_AUTH_SOCK environment variable is not present in the host process environment when the container starts, the runtime will not create the mount, but the container will still start normally. SSH commands inside the container will fail to authenticate unless you configure alternative authentication methods, as no agent socket will be available.

Is the socket path always the same inside the container?

Yes, the guest path is fixed to /run/host-services/ssh-auth.sock regardless of where the socket resides on the host. The SSH_AUTH_SOCK environment variable inside the container is automatically set to this fixed path, ensuring consistent behavior across different host configurations.

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