Repository navigation
feat(macos): mount through macFUSE's FSKit backend, auto by default (#210) - #357
Open
zodiac1214 wants to merge 5 commits into
Open
zodiac1214 wants to merge 5 commits into
zodiac1214 wants to merge 5 commits into
Conversation
…amsoir#210) New setting fuse.macos_backend chooses how macFUSE serves the ortho volume: - auto (default) tries FSKit, logs why it could not mount, and falls back to the kext, so a 0.5.0 install with the kext approved keeps working on upgrade and moves to FSKit once the File System Extension is turned on. - fskit uses macFUSE's FSKit backend through fuse3's MFMount channel transport: no kernel extension, no Recovery mode approval. Recommended for new installs. Needs macFUSE 5.3.3+ (MFChannelInterrupt). - kernel uses the macFUSE kext as before. fuse::MacosBackend parses the setting (compiled everywhere, mapped to fuse3::MacFuseBackend on macOS only); OrchestratorConfig carries it to MountManager, which applies it with Fuse3OrthoUnionFS::with_macos_backend. Docs: docs/macos.md presents FSKit as the recommended path with the kext as the fallback, explains auto and its log line, and adds the Full Disk Access step for /usr/libexec/fskitd that FSKit needs when X-Plane is on an external drive. docs/configuration.md, the config.ini comments, the MacFuseAvailable preflight hint and CLAUDE.md follow. CHANGELOG entry under Unreleased. TEMPORARY: the workspace [patch] takes fuse3 from zodiac1214/fuse3 branch feat/mfmount-transport (1910979) until the transport is merged into samsoir/fuse3 master; then the patch is dropped and Cargo.lock moves to that commit. Closes samsoir#210 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PA3HzXrgf2kkia3o2Yo9bi
zodiac1214
marked this pull request as ready for review
November 10, 2026 15:35
Author
This was referenced Nov 11, 2026
samsoir
requested changes
Nov 11, 2026
| /// Default macOS mount backend: FSKit when it can mount, the kernel extension | ||
| /// otherwise (#210). Not `fskit`, which would turn a 0.5.0 install whose kext | ||
| /// is approved but whose File System Extension is off into a failed mount. | ||
| pub const DEFAULT_FUSE_MACOS_BACKEND: &str = "auto"; |
Owner
There was a problem hiding this comment.
Needed before merge: a live test of the fallback path.
Every Mac upgrading from 0.5.0 has the kext approved and the File System Extension off, so with this default they will take the fallback on every launch, and so far it has only been reasoned about. Could you run it once: File System Extension turned off, kext approved, fuse.macos_backend = auto, then xearthlayer run? I would like to know:
- the warning line it logs,
- how long the FSKit attempt takes before the kext mount starts,
- whether macOS shows any prompt or dialog along the way,
- and the
mountline for the volume (it should not carry thefskitflag).
A paste in this thread is enough.
Author
There was a problem hiding this comment.
we might need someone else to do it :( for compliance reasons, all my macbook/studio can't approve kext without triggering auditing
Comment on lines
+50
to
+51
| [patch."https://github.com/samsoir/fuse3"] | ||
| fuse3 = { git = "https://github.com/zodiac1214/fuse3", branch = "feat/mfmount-transport" } |
Owner
There was a problem hiding this comment.
As your description says: this goes once samsoir/fuse3#2 merges, with the lock then pointing at that merge commit on samsoir/fuse3 master. Listing it here only so it is tracked with the other blockers.
…acfuse-fskit-0.5.1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lets XEarthLayer on macOS mount through macFUSE's FSKit backend, so a new Mac no longer has to boot into Recovery and approve the kext. It builds on the fuse3
MFMountchannel transport (PR 1: samsoir/fuse3#2).Important
Patch override, to update once PR 1 merges. The workspace
[patch."https://github.com/samsoir/fuse3"]inCargo.tomlstill points fuse3 atzodiac1214/fuse3branchfeat/mfmount-transport, on purpose: the MFMount transport is not insamsoir/fuse3yet. PR 1 is the fuse3 change, samsoir/fuse3#2 againstsamsoir/fuse3master. Once it merges:[patch]block and its comment from the workspaceCargo.toml.cargo update -p fuse3, or edit the fuse3sourceline ofCargo.lockto the newsamsoir/fuse3master commit (cargo updatealso rewrites unrelatedwindows-syspins).CLAUDE.mdmacOS line no longer mentions the temporary patch.A patch to a personal fork cannot ship, so this PR must not leave draft before these steps are done.
Closes #210
What changes for users
fuse.macos_backend:auto(default),fskit,kernel.autotries FSKit. If FSKit can't mount, it logsmacFUSE FSKit backend unavailable (<reason>); using the kernel backendand falls back to the kext, so a 0.5.0 install with the kext approved keeps working on upgrade.fskitis FSKit only, and the recommended setup for new installs.kernelis the kext only.MFChannelInterrupt). With 5.4.0+, a mount-point failure is also reported by name./usr/libexec/fskitdneeds Full Disk Access.Review points addressed
develop/0.5.1. The two feature commits applied cleanly. The first commit's title no longer says "by default".auto, notfskit. Changed inMacosBackend::default(),DEFAULT_FUSE_MACOS_BACKEND, the config writer, settings docs and tests. The five default assertions were flipped first and seen failing.docs/macos.md: the macFUSE 5.3.3 floor; FSKit recommended with the kext as fallback; whatautodoes and its log line; a new step 2a forfskitdFull Disk Access on an external drive; three new troubleshooting rows (fallback warning, macFUSE too old, external drive).docs/configuration.mdand the generatedconfig.inicomments: theautodefault and the 5.3.3 floor.CLAUDE.md: the platform and[fuse]lines.MacFuseAvailablepreflight hint names 5.3.3 and thefskitdstep in one sentence. Its test now asserts both.[Unreleased], since this branch has no 0.5.1 heading yet.[patch]still in place, deliberately: see the note at the top.Cargo.lockis bumped to the squashed commit1910979of PR 1, and that is the only lockfile line changed.Verification (on the Mac)
make pre-commit: passed (fmt, clippy-D warnings, all tests, release script tests).make verify-macos: passed, including both live macFUSE smoke tests on the newautodefault (ortho_union_fs_mounts_and_serves_a_file_through_macfuse,ortho_union_fs_volume_is_named_after_its_mount_point_folder).make pre-commiton Linux: not run locally (no Linux machine here). The LinuxVerifyCI job covers it.macOS 26.6.2 (25G83), Apple Silicon, macFUSE 5.5.0.
🤖 Generated with Claude Code
https://claude.ai/code/session_01PA3HzXrgf2kkia3o2Yo9bi