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

> Learn to forward SSH agent sockets and publish Unix sockets to containers using the `container` tool. Securely access host SSH authentication from within your containerized environment.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-19

---

**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`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerStart.swift) (lines 91-93) and [`ContainerRun.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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:

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

```

Inside the container, verify the setup:

```bash
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:

```bash
container build --ssh myimage:latest .

```

## Dynamic Resolution Behavior

The socket path is resolved at container start time rather than build time. Because [`RuntimeService.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/ContainerStart.swift) and [`ContainerRun.swift`](https://github.com/apple/container/blob/main/ContainerRun.swift) by reading the host’s `SSH_AUTH_SOCK` environment variable.
- **Implementation** in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.