Mount Remote Server via SSHFS on macOS - Complete Setup Guide

dokploy-sshfs-setup.md

Mount Remote Server (dokploy) via SSHFS on macOS

This guide documents how to mount a remote server's directory as a network drive on macOS using SSHFS.

Prerequisites

• macOS (tested on macOS Sequoia)
• SSH access to remote server configured in ~/.ssh/config
• Homebrew installed

Installation Steps

1. Install macFUSE

macFUSE is required for mounting remote filesystems on macOS:

brew install --cask macfuse

Important: After installation, you must approve the kernel extension:

1. Go to System Settings → Privacy & Security
2. Look for a message about system software from "Benjamin Fleischer"
3. Click "Allow" to approve the macFUSE extension
4. Restart your Mac if prompted

2. Install FUSE-T (optional but recommended)

FUSE-T is a userspace FUSE implementation that can work alongside macFUSE:

brew install fuse-t

3. Install SSHFS

brew install gromgit/fuse/sshfs-mac

Note: This formula is deprecated but still functional.

4. Create Mount Point Directory

mkdir -p ~/mounts/dokploy

SSH Configuration

Ensure your ~/.ssh/config has the server configured:

Host dokploy
    HostName 5.78.100.199
    User stephan
    IdentitiesOnly yes
    IdentityFile ~/.ssh/id_ed25519

Manual Mounting

To manually mount the remote directory:

sshfs dokploy:/home/stephan/ ~/mounts/dokploy -o volname=Dokploy,reconnect,ServerAliveInterval=15,defer_permissions

Mount Options Explained:

• volname=Dokploy - Sets the volume name shown in Finder
• reconnect - Automatically reconnect if connection drops
• ServerAliveInterval=15 - Keep connection alive with 15s pings
• defer_permissions - Improves compatibility with macOS permissions

Unmounting

umount ~/mounts/dokploy

Or force unmount if needed:

sudo umount -f ~/mounts/dokploy

Auto-Mount on Login

To automatically mount the drive on login, create a Launch Agent:

Create the plist file:

cat > ~/Library/LaunchAgents/com.user.sshfs.dokploy.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.sshfs.dokploy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/sshfs</string>
        <string>dokploy:/home/stephan/</string>
        <string>/Users/stephanfitzpatrick/mounts/dokploy</string>
        <string>-o</string>
        <string>volname=Dokploy,reconnect,ServerAliveInterval=15,defer_permissions</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>StandardErrorPath</key>
    <string>/tmp/sshfs-dokploy.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/sshfs-dokploy.out</string>
</dict>
</plist>
EOF

Note: Update the username path (/Users/stephanfitzpatrick/) to match your username.

Load the Launch Agent:

launchctl load ~/Library/LaunchAgents/com.user.sshfs.dokploy.plist

Verify it's loaded:

launchctl list | grep dokploy

Managing the Auto-Mount

Disable auto-mount:

launchctl unload ~/Library/LaunchAgents/com.user.sshfs.dokploy.plist

Re-enable auto-mount:

launchctl load ~/Library/LaunchAgents/com.user.sshfs.dokploy.plist

Check mount status:

mount | grep dokploy

View logs if issues occur:

cat /tmp/sshfs-dokploy.err
cat /tmp/sshfs-dokploy.out

Performance Considerations

SSHFS can be slow for operations involving many small files because:

• Each file requires a separate round-trip to the server
• SSH encryption adds overhead
• Network latency is multiplied by the number of files

For better performance with many small files:

• Use rsync or scp for bulk transfers
• Work with files directly on the server via SSH
• Consider using rclone with full cache mode (though it had Finder compatibility issues in our testing)

Troubleshooting

Mount fails with "Resource busy"

sudo umount -f ~/mounts/dokploy
rmdir ~/mounts/dokploy
mkdir ~/mounts/dokploy
# Try mounting again

Can't approve macFUSE extension

If you don't see the approval prompt:

1. Try rebooting after installation
2. Check System Settings → General → Login Items & Extensions
3. The prompt should appear when you first try to mount

SSHFS hangs or is very slow

• Check your network connection
• Verify SSH connection works: ssh dokploy
• Check server load: ssh dokploy 'uptime'

Alternative: rclone

We also tested rclone as an alternative, but it had Finder compatibility issues (error -8062 when copying files). SSHFS proved more reliable for macOS Finder operations.

If you want to try rclone anyway:

# Install official rclone binary (Homebrew version doesn't support mount)
cd /tmp
curl -O https://downloads.rclone.org/rclone-current-osx-arm64.zip
unzip rclone-current-osx-arm64.zip
cd rclone-*-osx-arm64
sudo cp rclone /usr/local/bin/
sudo chmod 755 /usr/local/bin/rclone

# Configure
mkdir -p ~/.config/rclone
cat > ~/.config/rclone/rclone.conf << 'EOF'
[dokploy]
type = sftp
host = 5.78.100.199
user = stephan
port = 22
key_file = ~/.ssh/id_ed25519
shell_type = unix
EOF

# Mount
/usr/local/bin/rclone mount dokploy:/home/stephan/ ~/mounts/dokploy --vfs-cache-mode full --daemon

Summary

Your dokploy server's /home/stephan/ directory is now:

• ✅ Mounted at ~/mounts/dokploy
• ✅ Auto-mounts on login
• ✅ Fully bi-directional (changes sync both ways)
• ✅ Deletes propagate between local and remote
• ✅ Accessible in Finder as "Dokploy" volume

---

Created: 2025-11-01 System: macOS Sequoia, Apple Silicon