loc bengaluru, ist | local --:-- srijanshukla18@gmail.com →
[post]/tech/rclone-s3-mount-macos

mounting an S3 bucket in Finder on macOS with rclone

/ 4 min read· infra

I mounted an S3 bucket as a local folder in Finder with rclone and FUSE-T, auto-mounted on login. This is the full setup, the flags that make it behave, and where it falls over.

I wanted a very specific setup on my Mac: a local folder in Finder that feels like Dropbox for browsing around and opening files on demand, but backed by a cheap S3 bucket instead of running a bloated desktop sync app.

Specifically:

  • see the full folder tree in Finder
  • only download files when I actually open them
  • cap the local disk cache at 5 GB
  • auto-mount on login so I never have to think about it

rclone mount does this, but most tutorials online skip the two macOS gotchas that will break your setup before you even get to the flags. Here is what worked for me.

Two things to do before touching rclone mount

1. Install FUSE-T

You need a userspace FUSE driver on macOS. Use fuse-t:

brew install --cask fuse-t

Don’t bother messing with kernel-extension macFUSE if you can avoid it, fuse-t works out of the box without kernel extension headaches.

2. Do NOT use the Homebrew rclone binary

This is the main gotcha. If you do brew install rclone, the Homebrew binary does not ship with cmount support on macOS, so rclone mount won’t work properly.

Download the official binary directly from rclone.org and put it in /usr/local/bin/rclone,

curl -L https://downloads.rclone.org/rclone-current-osx-arm64.zip -o /tmp/rclone.zip
cd /tmp && unzip -o rclone.zip
sudo cp /tmp/rclone-v*-osx-arm64/rclone /usr/local/bin/rclone
sudo chmod +x /usr/local/bin/rclone

Verify that cmount is compiled in:

/usr/local/bin/rclone version

Make sure you see go/tags: cmount in the output.

S3 remote config

My rclone config (~/.config/rclone/rclone.conf) looks like this,

[archive]
type = s3
provider = AWS
access_key_id = <YOUR_ACCESS_KEY_ID>
secret_access_key = <YOUR_SECRET_ACCESS_KEY>
region = ap-south-1
storage_class = GLACIER_IR

Note the GLACIER_IR (Glacier Instant Retrieval) storage class. Storage is dirt cheap, retrieval is instant, but you pay per retrieval and there is a minimum storage duration. Which means we really want local caching so Finder doesn’t re-fetch the same file 10 times.

The mount command

/usr/local/bin/rclone mount archive:your-bucket ~/rclone \
  --vfs-cache-mode full \
  --vfs-cache-max-size 5G \
  --vfs-cache-max-age 72h \
  --vfs-read-chunk-size 16M \
  --vfs-read-chunk-size-limit 256M \
  --dir-cache-time 30m \
  --poll-interval 0 \
  --cache-dir /tmp/rclone-cache \
  --volname "rclone" \
  --daemon

Why each flag is there:

  • --vfs-cache-mode full: Without this, Finder chokes and normal file reads/writes behave weirdly. With full, opened files get cached on disk properly.
  • --vfs-cache-max-size 5G and --vfs-cache-max-age 72h: Caps the local cache at 5 GB and evicts files I haven’t touched in 3 days.
  • --vfs-read-chunk-size 16M and --vfs-read-chunk-size-limit 256M: Starts by fetching a 16 MB chunk via HTTP range request when you open a big PDF or video, and doubles the chunk size up to 256 MB if you keep reading sequentially.
  • --dir-cache-time 30m: Caches directory listings in memory for 30 minutes so clicking through folders in Finder is instant and doesn’t spam S3 LIST calls.
  • --poll-interval 0: S3 doesn’t support polling changes anyway, so turn it off.
  • --cache-dir /tmp/rclone-cache: Puts the cache in /tmp so a reboot wipes it clean.

Watch out for --dir-cache-time 30m

Caching directory listings for 30 minutes is great when you are the only one using the bucket as a personal cold archive.

It is terrible if another machine writes to that same bucket and you expect to see the new file show up immediately. Your Mac will happily show you the cached directory listing from 25 minutes ago. I actually got burned by this exact flag later when I tried using this mount to pass messages between two machines - wrote about that fail in syncing two AI agents across machines with Git instead of a shared mount.

Auto-mounting on login

To make it show up under Locations in Finder automatically on every reboot, wire the command above into a macOS LaunchAgent plist under ~/Library/LaunchAgents/ pointing to /usr/local/bin/rclone.

Works great as a cheap cold archive you can browse in Finder. Just don’t use it for anything that needs real-time sync across multiple machines.