# How to Set Up SSH Agent Socket Forwarding into Containers

> Effortlessly set up SSH agent socket forwarding into containers with Apple's container tool. Use the --ssh flag for secure, automatic forwarding and simplified access.

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

---

**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`](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 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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:

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

```

To use SSH during a build:

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

```bash
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`](https://github.com/apple/container/blob/main/ContainerStart.swift), [`ContainerRun.swift`](https://github.com/apple/container/blob/main/ContainerRun.swift), and [`RuntimeService.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.