# How to Use Socket Forwarding for Inter-Container Communication in Apple Container > Learn how to use socket forwarding for seamless inter-container communication in Apple Container. Enable zero-overhead IPC with the --publish-socket flag for efficient communication between containers without TCP. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-21 --- **Apple Container provides a built-in `--publish-socket` flag that binds Unix-domain sockets from the host directly into a container's filesystem namespace, enabling zero-overhead IPC between containers without TCP networking.** The **apple/container** repository implements a native socket forwarding mechanism that allows processes in different containers to communicate via Unix-domain sockets. This approach eliminates the need for TCP ports while preserving filesystem permissions and offering lower latency than network-based alternatives. ## Understanding Socket Forwarding in Apple Container Socket forwarding creates a direct bind mount of a Unix-domain socket from the host into the container's filesystem namespace. Unlike TCP port forwarding, this method incurs **no extra networking overhead** and maintains the original socket permissions. The implementation spans the CLI parsing layer and the runtime service, ensuring that socket configurations are validated before the container starts. ## Declaring Socket Mappings with `--publish-socket` The `--publish-socket` flag accepts a `host_path:container_path` pair that defines how the socket should be exposed inside the container. ### CLI Syntax and Validation The flag is defined in **[`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift)** (line 311). When you pass `--publish-socket`, the `Parser.publishSocket(_:)` method validates the syntax, verifies the host path exists, and constructs a `PublishSocket` value. According to the source code in **[`Sources/Services/ContainerAPIService/Client/Parser.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Parser.swift)** (lines 739-766), the parser handles: - Syntax validation for the `host:container` format - Filesystem checks for the host socket path - Optional permission settings ```bash # Forward the Docker daemon socket into the container at the same path container run --publish-socket /var/run/docker.sock:/var/run/docker.sock my-image # Forward an SSH agent socket with custom container path container run \ --publish-socket /tmp/ssh-auth.sock:/ssh-agent.sock \ --env SSH_AUTH_SOCK=/ssh-agent.sock \ my-image ``` ### Swift Implementation When building custom tooling, you can use the parser directly: ```swift do { // Parse a single "--publish-socket" argument let socket = try Parser.publishSocket("/tmp/ssh-auth.sock:/ssh-agent.sock") print("Host path: \(socket.hostPath)") print("Container path: \(socket.containerPath)") } catch { print("Invalid socket spec: \(error)") } ``` ## Runtime Configuration and Binding Once parsed, the socket configuration passes to the runtime service. In **[`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift)** (lines 1010-1044), the `RuntimeService` reads each `PublishSocket` entry and creates a `UnixSocketConfiguration` object. The runtime loop binds the host socket into the container namespace before the process starts: ```swift // Inside RuntimeService.startContainer(...) for forwarder in self.socketForwarders { let socketConfig = UnixSocketConfiguration( source: forwarder.hostPath, // e.g., "/tmp/ssh-auth.sock" destination: forwarder.containerPath, // e.g., "/ssh-agent.sock" mode: forwarder.permissions ?? .default ) czConfig.sockets.append(socketConfig) } ``` This configuration ensures the socket is available immediately when the container entrypoint executes. ## Practical Use Cases and Examples ### Forwarding the Docker Daemon Socket You can grant containers access to the host's Docker daemon without exposing TCP ports: ```bash container run --publish-socket /var/run/docker.sock:/var/run/docker.sock docker-cli-image ``` ### Forwarding an SSH Agent Socket The test suite in **[`Tests/CLITests/Subcommands/Run/TestCLIRunLifecycle.swift`](https://github.com/apple/container/blob/main/Tests/CLITests/Subcommands/Run/TestCLIRunLifecycle.swift)** (lines 148-204) demonstrates forwarding an SSH agent socket. The test creates a temporary Unix socket on the host, forwards it using `--publish-socket`, and verifies accessibility inside the container: ```swift let socketDir = FileManager.default.temporaryDirectory .appendingPathComponent(UUID().uuidString) try FileManager.default.createDirectory(at: socketDir, withIntermediateDirectories: true) let socketPath = socketDir.appendingPathComponent("ssh-auth.sock").path // Create a dummy Unix socket to act as the SSH agent let serverFd = socket(AF_UNIX, SOCK_STREAM, 0) precondition(serverFd >= 0, "socket() failed") // Run the container with the socket forwarded try doLongRun(name: name, args: ["--ssh"], env: ["SSH_AUTH_SOCK": socketPath]) ``` This pattern allows containers to use host SSH keys without copying sensitive material into the image. ## Controlling Socket Permissions You can explicitly set the socket file mode using the `--publish-socket-permissions` flag. The parser handles permission validation around line 766 in [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift), ensuring the format is valid before runtime. ```bash # Forward a socket with explicit mode 766 (rw-x for owner, rw for group, rw for others) container run \ --publish-socket /tmp/my.sock:/my.sock \ --publish-socket-permissions 766 \ my-image ``` If omitted, the runtime uses default permissions from the host socket. ## Summary - **Socket forwarding** binds Unix-domain sockets from the host directly into the container filesystem namespace using the `--publish-socket` flag. - The **CLI parser** validates syntax and paths in [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift) (lines 739-766), while the **runtime service** creates `UnixSocketConfiguration` objects in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (lines 1010-1044). - This mechanism works with any Unix-domain socket, including Docker daemon sockets and SSH agents. - **Zero network overhead** occurs because the socket operates through filesystem bindings rather than TCP/IP. - Permissions can be explicitly controlled via `--publish-socket-permissions`. ## Frequently Asked Questions ### What is socket forwarding in Apple Container? Socket forwarding is a feature that exposes Unix-domain sockets from the host into containers (or vice versa) by mounting the socket file into the container's filesystem namespace. According to the apple/container source code, this is implemented through the `--publish-socket` flag and configured via `UnixSocketConfiguration` objects at runtime. ### How does socket forwarding differ from TCP port forwarding? Socket forwarding binds the actual socket file into the container namespace, eliminating TCP/IP overhead and maintaining native Unix socket semantics. TCP port forwarding requires network stack traversal and exposes services on network interfaces, while socket forwarding operates entirely through filesystem operations with permission preservation. ### Can I forward multiple sockets into a single container? Yes. You can specify multiple `--publish-socket` flags when running a container. The `RuntimeService` processes each socket forwarder in a loop (starting at line 1010 in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift)), creating separate `UnixSocketConfiguration` entries for each mapping. ### How are socket permissions handled when forwarding? Permissions are preserved from the host socket by default, or you can override them using `--publish-socket-permissions`. The parser validates the permission format in [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift) around line 766, and the `UnixSocketConfiguration` accepts an explicit mode parameter that applies to the socket inside the container namespace.