Platform-Specific Issues

Relevant source files

• README.md

Purpose and Scope

This page documents platform-specific differences between Docker runtime environments on macOS, focusing on networking incompatibilities that affect SMB connectivity to the docker-sshfs container. The primary distinction is between OrbStack and Docker Desktop, which handle network routing differently and require different configuration approaches.

For connection troubleshooting steps, see Connection Problems. For general network architecture, see Network Architecture.

OrbStack vs Docker Desktop

The sshfs-mac-docker system exhibits significantly different behavior depending on the Docker runtime environment used on macOS. This is explicitly documented in README.md9

Recommended Configuration: OrbStack

OrbStack provides native networking that allows SMB connections to work without additional configuration. When using OrbStack:

• Container IP addresses are directly accessible from macOS
• Port forwarding to 127.0.0.1 functions as expected
• No network routing modifications required
• SMB protocol operates normally through Docker's network bridge

Sources : README.md9

Problematic Configuration: Docker Desktop

Docker Desktop requires network routing modifications to function with this system. The default Docker Desktop networking on macOS creates isolation that prevents SMB connections from functioning properly with the standard port forwarding configuration.

docker run --privileged --name docker-sshfs -p 127.0.0.1:139:139 -p 127.0.0.1:445:445 docker-sshfs

This command in README.md31 forwards ports 139 and 445 to 127.0.0.1, but Docker Desktop's network stack does not allow macOS SMB clients to connect through this forwarding.

Sources : README.md9 README.md31

Network Routing Comparison

OrbStack Network Model

Diagram 1: OrbStack Network Path

OrbStack provides a transparent network bridge that allows direct container IP access from macOS. The SMB client can connect to the container's IP address without traversing the localhost port forwarding.

Sources : README.md9 README.md:57-61

Docker Desktop Network Model

Diagram 2: Docker Desktop Network Path with Isolation

Docker Desktop introduces a VM-based isolation layer that interferes with SMB protocol handling. The localhost port forwarding does not function for SMB connections, and direct container IP access requires network routing modifications.

Sources : README.md9 README.md57

Localhost Connection Limitation

A critical platform quirk affects both OrbStack and Docker Desktop: the Finder SMB client cannot connect to smb://localhost or smb://127.0.0.1, even when ports 139 and 445 are correctly forwarded.

The Problem

The README.md31 command maps container ports to 127.0.0.1:

However, README.md57 explicitly notes:

Find Docker IP of container (localhost doesn't seem to work for this)

Root Cause

This limitation stems from macOS's SMB client implementation, which treats localhost SMB connections differently than network-based SMB connections. The SMB protocol stack on macOS expects to connect to network interfaces rather than loopback interfaces for standard file sharing operations.

Required Workaround

Users must obtain the container's internal Docker IP address and connect directly to it:

1. Discover container IP using README.md60:

2. Connect to smb://<container-ip> in Finder README.md65

Sources : README.md31 README.md:57-65

Container IP Discovery

Command-Line Method

The standard approach uses docker inspect with Go template formatting:

This queries the .NetworkSettings.IPAddress field from the container's configuration and returns the dynamically assigned IP address (typically in the 172.17.0.x range).

File Reference : README.md60

IP Address Characteristics

Sources : README.md60

Platform Decision Tree

Diagram 3: Platform-Specific Connection Decision Tree

This flowchart illustrates the critical decision points when setting up sshfs-mac-docker on different macOS Docker runtimes and highlights the localhost connection pitfall.

Sources : README.md9 README.md31 README.md:57-61

Platform Compatibility Matrix

Sources : README.md9 README.md31 README.md:57-61

Identifying Your Platform

Determining Docker Runtime

OrbStack Output :

Operating System: OrbStack

Docker Desktop Output :

Operating System: Docker Desktop

Testing Connectivity

After starting the container with README.md31 test connectivity by obtaining the IP with README.md60 and attempting connection via Finder README.md:63-67

If connection fails with OrbStack, verify:

1. Container is running: docker ps | grep docker-sshfs
2. Ports are bound: docker port docker-sshfs
3. smbd process is running: docker exec docker-sshfs ps aux | grep smbd

If connection fails with Docker Desktop, network routing must be configured (exact steps depend on Docker Desktop version and macOS configuration).

Sources : README.md31 README.md60 README.md:63-67

Network Routing Modifications for Docker Desktop

While Docker Desktop is not the recommended platform README.md9 users who must use it need to modify network routing to allow SMB connections to reach the container's IP address.

Understanding the Routing Problem

Docker Desktop runs containers inside a lightweight VM, creating an additional network layer between macOS and the container. The default routing table does not include paths for direct container IP access from macOS networking services like the Finder SMB client.

Required Configuration Approach

Network routing modifications typically involve:

1. Identifying the Docker bridge network subnet (usually 172.17.0.0/16)
2. Adding static routes from macOS to the Docker VM's network interface
3. Ensuring route persistence across Docker Desktop restarts

The exact commands depend on Docker Desktop's current networking configuration and may change between versions. This complexity is why OrbStack is the recommended platform README.md9

Alternative: Docker Desktop Network Driver

Some users report success by configuring Docker Desktop to use alternative network drivers, though this is not officially documented by the sshfs-mac-docker project.

Sources : README.md9

Verification Steps

After Container Startup

Execute these checks after running README.md31:

1. Verify container IP assignment :

Expected: Non-empty IP in 172.17.0.x range

2. Verify port bindings :

Expected output:

     139/tcp -> 127.0.0.1:139
     445/tcp -> 127.0.0.1:445

3. Test network connectivity :

   • OrbStack: Should succeed
   • Docker Desktop: May fail without routing modifications

Sources : README.md31 README.md60

Summary of Platform Differences

OrbStack Advantages

• Zero network configuration required
• Direct container IP accessibility
• Simpler troubleshooting path
• Officially recommended by project README.md9

Docker Desktop Limitations

• Requires network routing modifications
• More complex networking stack
• Additional troubleshooting steps needed
• Not officially supported without modifications README.md9

Universal Limitation

The localhost SMB connection restriction affects both platforms equally. All users must use the container IP obtained via README.md60 and connect to smb://container-ip in Finder README.md65 not smb://localhost.

Sources : README.md9 README.md57 README.md60 README.md65