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

> Learn how to forward SSH agent sockets into containers using the apple/container tool. Discover the simple --ssh flag for seamless authentication.

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

---

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

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

```

Inside the container, verify the forwarding works:

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

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

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