Prerequisites and Platform Requirements

Relevant source files

• README.md

Purpose and Scope

This page documents the software and platform requirements needed to run sshfs-mac-docker. It covers the required Docker runtime environment, platform-specific considerations for OrbStack versus Docker Desktop, and system capabilities that must be available. For detailed troubleshooting of platform-specific issues, see Platform-Specific Issues. For instructions on building the container once prerequisites are met, see Building the Container.

Sources : README.md:1-90

Required Software Components

The sshfs-mac-docker system requires only two software components on the host macOS system:

Notably, sshfs-mac-docker does not require macFUSE or any kernel extensions to be installed on macOS. All FUSE operations are contained within the Docker container itself.

Sources : README.md3 README.md9

Docker Platform Options

Platform Requirements Comparison

Sources : README.md9 README.md:31-34

OrbStack (Recommended)

OrbStack is the recommended Docker runtime for sshfs-mac-docker because it provides native support for the networking requirements without additional configuration.

Key Advantages :

• Container networking works seamlessly with SMB/CIFS protocol
• No network routing modifications required
• Direct container IP access from macOS Finder

Installation : Available at https://orbstack.dev/

When using OrbStack, the SMB connection workflow operates as documented without additional steps.

Sources : README.md9

Docker Desktop (Alternative with Limitations)

Docker Desktop can be used but has known networking limitations that prevent standard operation.

Known Limitation : Docker Desktop's network implementation does not allow macOS Finder to connect to SMB shares using the standard port forwarding configuration shown in README.md:31-34 The README explicitly states: "Docker Desktop will not work for this without modifying the network routing."

If Using Docker Desktop : Network routing modifications are required but not documented in the current codebase. For troubleshooting these issues, see Platform-Specific Issues.

Sources : README.md9

What is NOT Required

Avoided Dependencies

Sources : README.md3

The primary motivation for sshfs-mac-docker is to avoid installing macFUSE on macOS. The traditional approach to using SSHFS on macOS requires:

By moving FUSE operations into the Docker container's Linux environment, all kernel-level dependencies are isolated from the macOS host system.

Sources : README.md3

System Capabilities Required

Privileged Container Mode

The container must run in privileged mode using the --privileged flag:

Why Privileged Mode is Required :

• FUSE operations require access to the /dev/fuse device
• Mounting filesystems requires elevated capabilities within the container
• SSHFS uses FUSE kernel module which needs privileged access

This requirement is specified in README.md31 as part of the container startup command.

Sources : README.md31

Port Availability

The host system must have the following ports available on localhost (127.0.0.1):

Port Forwarding Configuration :

These ports must not be in use by other services on the macOS host. The 127.0.0.1 binding restricts access to localhost only, preventing external network exposure.

Sources : README.md:31-34

Network Access Requirements

Sources : README.md:57-69

The system requires two distinct network paths:

1. macOS → Container (SMB) :

   • Finder must be able to reach the container's IP address
   • Connection string format: smb://container-ip
   • Container IP is discoverable using docker inspect command shown in README.md60

2. Container → Remote Server (SSH) :

   • Container must have outbound network access to remote SSH servers
   • Standard SSH port (22) must be reachable
   • SSH credentials must be available for authentication

Critical Networking Quirk : The localhost address (127.0.0.1 or localhost) does not work for SMB connections from macOS Finder, even though the ports are forwarded to localhost. Finder must connect using the container's internal Docker network IP address.

Sources : README.md:57-60

Platform Requirements Summary

Pre-Flight Checklist

Minimum System Profile

Sources : README.md:1-90

Next Steps

Once all prerequisites are satisfied:

1. Verify Docker runtime is operational
2. Confirm ports 139 and 445 are available
3. Proceed to Building the Container

For troubleshooting platform-specific issues during setup, see Platform-Specific Issues.

Sources : README.md:1-90