[BUG] Preview server cannot read files from ~/Desktop on macOS despite Full Disk Access

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code's preview server returns 404 on every request when the project is located in ~/Desktop on macOS. The preview server subprocess (launched via .claude/launch.json) cannot read any files from the Desktop folder, even after granting Claude Full Disk Access in System Settings → Privacy & Security.

Direct test of the preview sandbox wrapper confirms the cause:

$ /Applications/Claude.app/Contents/Helpers/disclaimer /usr/bin/python3 \
-c "open('/Users/matty/Desktop/project/index.html').read()"
PermissionError: [Errno 1] Operation not permitted

Setting sandbox.filesystem.allowRead in .claude/settings.json does NOT help — it seems to apply only to the Bash tool sandbox, not the preview server sandbox. Moving the project out of ~/Desktop (e.g. to ~/project/) resolves the issue, confirming it's macOS TCC protection of Desktop that the preview sandbox doesn't inherit from Claude's Full Disk Access grant.

What Should Happen?

The preview server should be able to serve files from any project folder, including ~/Desktop, ~/Documents, and ~/Downloads — especially when Claude Code has been granted Full Disk Access. Alternatively, the sandbox.filesystem.allowRead setting in .claude/settings.json should also apply to the preview server sandbox, not just the Bash tool sandbox.

Error Messages/Logs

Preview server stderr:
[aya_proxy] serving /Users/matty/Desktop/aya eshop on http://127.0.0.1:3000
[aya_proxy] code 404, message File not found
[aya_proxy] "GET /index.html HTTP/1.1" 404 -

Direct sandbox test:
$ /Applications/Claude.app/Contents/Helpers/disclaimer /usr/bin/python3 -c "open('/Users/matty/Desktop/aya eshop/index.html').read()"
PermissionError: [Errno 1] Operation not permitted: '/Users/matty/Desktop/aya eshop/index.html'

Steps to Reproduce

1. Place any static project on ~/Desktop (e.g. ~/Desktop/my-site/ containing index.html)
2. Create .claude/launch.json with a static file server, e.g.:

{
"version": "0.0.1",
"configurations": [
{
"name": "Static Dev",
"runtimeExecutable": "python3",
"runtimeArgs": ["/tmp/serve.py"],
"port": 3000
}
]
}

1. Start the preview server via preview_start
2. Run: curl http://127.0.0.1:3000/index.html

Expected: 200 OK
Actual: 404 File not found (for every file in the directory)

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

Claude Code Desktop app (latest as of 2026-04-20)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Workarounds attempted (none worked except moving the project out of ~/Desktop):

1. Granted Claude Full Disk Access (System Settings → Privacy & Security → Full Disk Access) — verified ON
2. Fully quit and relaunched Claude Code (Cmd+Q)
3. Added sandbox config to .claude/settings.json:

{
"sandbox": {
"enabled": true,
"filesystem": {
"allowRead": ["/Users/matty/Desktop/aya eshop"]
}
}
}
→ This setting affects Bash tool but NOT the preview server sandbox.

1. Symlinked the project into /tmp/ — sandbox still blocks access via the symlink.
2. Placed proxy script in /tmp/ (which IS accessible) but serving files from ~/Desktop/ → proxy can run but still cannot read target files.

The only thing that works is relocating the project out of ~/Desktop entirely.

This is a significant UX issue because ~/Desktop is a very common location for user projects on macOS. Users see unexplained 404s with no hint as to the cause.

Suggested fixes:

• Make the preview sandbox honor sandbox.filesystem.allowRead from settings.json
• Have the preview sandbox inherit the parent app's Full Disk Access entitlement
• At minimum, document this limitation prominently in preview/troubleshooting docs