# SSH Agent Forwarding and Rosetta Support in Apple Container

> Enable SSH agent forwarding and Rosetta support in Apple containers. Seamlessly perform Git operations and build cross-architecture apps on Apple Silicon Macs without QEMU.

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

---

**Apple's `container` CLI provides native SSH agent forwarding via the `--ssh` flag and x86-64 binary translation via the `--rosetta` flag, enabling seamless remote Git operations and cross-architecture builds on Apple Silicon Macs without copying private keys or using QEMU emulation.**

The `container` repository from Apple delivers a lightweight container runtime optimized for macOS. When developing on Apple Silicon hardware, developers frequently need to authenticate with private Git repositories while building images for x86-64 targets. Understanding how **SSH agent forwarding** and **Rosetta support** are implemented at the source code level ensures secure credential management and optimal performance when working with cross-platform containers.

## How SSH Agent Forwarding Works

SSH agent forwarding in `container` mounts the host's authentication socket into the container environment, allowing seamless use of existing SSH keys without copying them into the VM filesystem.

### CLI Flag and Configuration Propagation

The `--ssh` flag is declared in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift) (line 31) and propagates to the container configuration via the `ssh` Boolean property in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift). When this flag is present, the runtime prepares to bind-mount the host's authentication socket into the guest environment.

### Runtime Socket Mounting

When a container starts, [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (lines 55-108) checks `config.ssh`. If true, the service creates a bind-mount from the host path `/run/host-services/ssh-auth.sock` to the guest path `/var/host-services/ssh-auth.sock` and injects `SSH_AUTH_SOCK` into the container environment. Helper code in [`Sources/ContainerCommands/Machine/MachineHelpers.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Machine/MachineHelpers.swift) (lines 54-55) copies the host's `SSH_AUTH_SOCK` variable into the container's process environment, ensuring every spawned process inherits the forwarded socket.

### User-Visible Behavior

As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 56-61), the `--ssh` flag effectively expands to `--volume "${SSH_AUTH_SOCK}:/run/host-services/ssh-auth.sock" --env SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock`. This design allows the socket to update automatically across host logins, enabling `ssh-add -l` or `git clone` operations to function exactly as they would on the host machine without exposing private keys to the VM filesystem.

## How Rosetta Support Works

Rosetta support enables x86-64 binary execution on Apple Silicon Macs by leveraging Apple's Rosetta 2 translation layer, eliminating the need for slower QEMU emulation when building or running amd64 containers.

### Configuration and Defaults

The `--rosetta` flag is parsed in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (line 325) and maps to `ContainerSystemConfig.build.rosetta` in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) (lines 81-108). Notably, this value defaults to `true`, meaning Rosetta translation is enabled by default for optimal performance on Apple Silicon.

### Builder Implementation

In [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift) (lines 196-263), the builder reads the configuration via `useRosetta = containerSystemConfig.build.rosetta`. When Rosetta is enabled, the builder launches the VM with Rosetta support active. If disabled via `--no-rosetta`, the builder omits the QEMU-enable flag and relies on emulation instead, which is useful for CI environments requiring deterministic emulation behavior.

### Architecture Targeting

When Rosetta is active, the VM's userland can execute x86-64 binaries such as `uname`, `gcc`, or `make` without emulation overhead. As shown in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 81-86), running `container run --arch amd64 … uname -a` returns an `x86_64` kernel line because the binary runs through Rosetta translation rather than QEMU.

## Combining SSH Forwarding and Rosetta

These two features operate independently within the `container` architecture. **SSH agent forwarding** functions regardless of the target architecture, as the Unix domain socket transport is unaffected by binary translation. **Rosetta** only activates when the container executes x86-64 binaries.

If you forward SSH into an amd64 container and run the `ssh` command, Rosetta translates the x86-64 binary while the forwarded socket resolves correctly to the host's agent. The implementation deliberately keeps these code paths separate, allowing users to enable either, both, or neither according to their specific workflow requirements.

## Practical Examples

The following commands demonstrate common use cases for these features, as referenced in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 70):

```bash

# Forward SSH agent into an Alpine container for Git operations

container run -it --rm --ssh alpine:latest sh -c '
  echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK"
  apk add --no-cache openssh-client
  ssh-add -l        # Lists host-side keys

  git clone git@github.com:myorg/private-repo.git
'

```

```bash

# Build an amd64 image on Apple Silicon with Rosetta (default behavior)

container build --arch amd64 -t myorg/hello-amd64:latest .

```

```bash

# Disable Rosetta and use QEMU for deterministic emulation

container build --arch amd64 --no-rosetta -t myorg/hello-amd64:qemu .

```

```bash

# Combine both features: forward SSH while building amd64 image

container build --arch amd64 --ssh -t myorg/hello-amd64:ssh .

```

## Summary

- **SSH agent forwarding** mounts the host's `/run/host-services/ssh-auth.sock` into the container at `/var/host-services/ssh-auth.sock` and sets `SSH_AUTH_SOCK`, implemented in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) and [`MachineHelpers.swift`](https://github.com/apple/container/blob/main/MachineHelpers.swift).
- **Rosetta support** defaults to enabled in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and allows x86-64 binary execution without QEMU, controlled via [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift).
- Both features are orthogonal: SSH forwarding works across all architectures, while Rosetta specifically accelerates amd64 binary execution on arm64 hosts.
- The `--ssh` and `--rosetta` flags (along with `--no-rosetta`) are documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) and [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md).

## Frequently Asked Questions

### Does SSH agent forwarding work with Rosetta-enabled containers?

Yes. SSH agent forwarding operates independently of the container architecture. When you run an amd64 container with both `--ssh` and `--rosetta`, Rosetta translates the x86-64 binaries while the SSH socket mounts function normally, allowing seamless Git operations within translated environments.

### Where does the container mount the SSH agent socket?

According to the implementation in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift), the host socket at `/run/host-services/ssh-auth.sock` is bind-mounted to `/var/host-services/ssh-auth.sock` in the guest, with the `SSH_AUTH_SOCK` environment variable pointing to this guest path.

### Is Rosetta enabled by default in Apple Container?

Yes. The `rosetta` Boolean in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) defaults to `true`, meaning x86-64 binaries run through Rosetta translation unless you explicitly disable it with the `--no-rosetta` flag.

### How do I disable Rosetta and force QEMU emulation?

Pass the `--no-rosetta` flag to your build or run commands. This sets `containerSystemConfig.build.rosetta` to false, causing [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) to omit the Rosetta enablement flag and rely on QEMU emulation instead.