Skip to content

SSH to MajorMac Hangs Indefinitely Reading Inside ~/Documents (Full Disk Access)

Symptom

A plain ssh majorlinux@<majormac-tailscale-ip> "echo hello" works fine and returns instantly. But any command that reads inside a TCC-protected folder — ~/Documents, ~/Desktop, ~/Downloads — hangs with no output until the connection times out:

ssh majorlinux@<majormac-tailscale-ip> "ls ~/Documents/<any-subfolder>" 2>&1
# hangs, eventually: MCP error -32001: Request timed out

Confusingly, ls ~ (the home directory itself, not a subfolder) returns fine and even lists Documents/Desktop/Downloads as entries:

ssh majorlinux@<majormac-tailscale-ip> "ls ~" 2>&1
# Applications
# CLAUDE.md
# Desktop
# Documents
# Downloads
# ...

This makes the failure look intermittent or session-specific — it isn't. It's consistent and specific to reading inside the protected folders, not the folders themselves as directory entries.

Cause

macOS's TCC (Transparency, Consent, and Control) framework gates access to a handful of user data categories — Documents, Desktop, Downloads, Photos, Contacts, etc. — independent of normal Unix file permissions. A process needs an explicit TCC grant (Full Disk Access, or the narrower per-folder grant) to read inside these folders, even running as the folder's own owner, if the process itself (sshd, or the Terminal/shell it spawns) has never been granted access.

Unlike most macOS permission prompts, a non-interactive SSH session cannot trigger the GUI consent dialog — there's no windowserver session attached to approve it. The read attempt doesn't fail cleanly with Permission denied; it blocks indefinitely, which is what produces the hang/timeout instead of an immediate, obvious error. This is a known category of TCC behavior, not unique to this fleet — but it's easy to misdiagnose as a network/SSH problem because the symptom looks like a hung connection, not a permissions error.

Diagnosis

Confirm the pattern before assuming Full Disk Access is the cause — rule out actual SSH/network flakiness first:

# 1. Baseline: does a trivial command work at all?
ssh -o ConnectTimeout=10 majorlinux@<majormac-ip> "echo reachable"
# should return instantly

# 2. Does the home directory itself list fine?
ssh -o ConnectTimeout=10 majorlinux@<majormac-ip> "ls ~"
# should return instantly, showing Documents/Desktop/Downloads as entries

# 3. Does reading INSIDE a protected folder hang?
ssh -o ConnectTimeout=10 majorlinux@<majormac-ip> "ls ~/Documents"
# if this hangs/times out while (1) and (2) succeeded, this is the TCC gap

If step 3 hangs specifically (not just "slow"), and steps 1–2 are instant, this is Full Disk Access, not a Tailscale/network issue — don't waste time on wake-majormac retries or connection tuning.

Fix

Grant Full Disk Access to whatever actually spawns the SSH session's shell on MajorMac — for the built-in macOS sshd, that's /usr/sbin/sshd itself (not Terminal.app, since a non-interactive SSH session doesn't go through Terminal):

  1. System Settings → Privacy & Security → Full Disk Access
  2. Click +, press Cmd+Shift+G, type /usr/sbin/sshd, add it
  3. Toggle it on
  4. No restart of sshd should be needed (TCC checks are per-request, not per-process-lifetime), but if the hang persists immediately after granting, restart the SSH session (not the whole Mac) and retry

This is a one-time, physical/GUI-only fix — it cannot be done headlessly over SSH, since granting Full Disk Access itself requires the System Settings UI and, depending on macOS version, an admin password prompt. If you're driving this from a remote/automated session and hit this hang, stop and ask the machine's owner to grant it locally rather than retrying indefinitely.

Why This Matters for Fleet Automation

Any Ansible/Claude/Cowork session that needs to read or write files under a MajorMac user's ~/Documents (project repos, Obsidian vault clones, etc.) over SSH will hit this exact hang if Full Disk Access hasn't been granted. Since the failure mode is a silent timeout rather than a clear permission error, it's worth checking this first — before assuming a Tailscale connectivity problem, a wake-majormac failure, or an SSH key/auth issue — whenever a MajorMac SSH session works for trivial commands but hangs specifically on ~/Documents/~/Desktop/ ~/Downloads paths.