🦊 FedoraBridge — read Linux (Btrfs) & Windows (NTFS) disks on a Mac

Open a Linux (Fedora/Btrfs) or Windows (NTFS) drive your Mac can't read, browse it, and copy your files — read-only, no drivers, no macFUSE.

Also searched as: read Btrfs on Mac · read NTFS on Mac · open Linux disk on macOS · recover files from a Linux/Windows drive on Mac · read a dual-boot disk on Mac.

macOS can't natively read Linux Btrfs filesystems, and its NTFS support is read-limited and flaky. If you have an external drive (or a dual-boot disk) with Fedora or Windows on it, macOS will usually just offer to erase it. FedoraBridge lets you plug that disk in, browse its files in your web browser, and copy what you need onto your Mac — with every copied file checksum-verified.

It is strictly read-only. It never writes to, modifies, or erases the source disk. One-way only: disk → Mac.

👉 Never used something like this before? Read HOW-TO-USE.txt — it's a plain-English, step-by-step guide with no technical jargon.

---

What it can read

Filesystem	Used by	Status
Btrfs	Fedora & most modern Linux	✅ files, folders, subvolumes, zstd/zlib compression
NTFS	Windows	✅ files, folders, large/fragmented files, Unicode names
ext4	Linux /boot etc.	detected (read support is Btrfs-focused)

Verified on a real 1 TB dual-boot disk: a full Windows Desktop (32,000+ files, ~5 GB) copied over with every file passing a SHA-256 integrity check.

Highlights

• No drivers to install — no macFUSE, no kernel extensions. Pure userspace.
• Point-and-click — a small local web app: pick disk → browse → tick files → Copy.
• Auto-detects the filesystem (Btrfs vs NTFS) from the disk itself.
• Integrity-verified copies — every file is SHA-256-checked after copying.
• Read-only and safe — the source disk is opened read-only at the lowest level.
• Universal — works on Apple Silicon and Intel Macs.

---

Quick start (the easy way)

1. Download this project (green Code button → Download ZIP, then unzip).
2. Plug in your Linux/Windows disk. If macOS asks to initialize/erase it, click Ignore — never Initialize.
3. Double-click FedoraBridge.app.
   • First time only: if macOS says "unidentified developer", right-click the app → Open → Open.
4. A Terminal window opens — type your Mac password when asked (it needs this to read the raw disk). Nothing is sent anywhere; it's your local machine.
5. Your browser opens automatically. Pick your disk → browse to your files → tick them → Copy selected.

That's it. Copied files land in the folder you choose (default ~/Recovered).

Prefer the command line?

# List what's on a partition (auto-detects Btrfs/NTFS):
sudo python3 spike/fbcopy.py /dev/rdiskXsY ls  win /Users
# Copy a folder to your Mac (checksum-verified):
sudo python3 spike/fbcopy.py /dev/rdiskXsY cp  win /Users/you/Documents ~/Recovered

Find your partition with diskutil list (look for Linux Filesystem or Microsoft Basic Data). For NTFS, the SUBVOL argument is ignored — pass any word like win.

---

How it works

FedoraBridge is a small userspace filesystem reader written in Python. It opens the raw partition device (/dev/rdiskNsM) read-only and parses the filesystem structures directly:

• spike/btrfslib.py — read-only Btrfs engine: superblock → chunk tree → root tree → subvolumes → directories → file extents, with zstd/zlib decompression.
• spike/ntfslib.py — read-only NTFS engine: boot sector → MFT (with fixups) → attributes → data runs → directory indexes, handling resident, non-resident, sparse, and heavily-fragmented files.
• spike/fbcopy.py — command-line browse/copy tool; auto-detects the filesystem and SHA-256-verifies every copy.
• spike/app/server.py — the local web app (a tiny HTTP server + built-in browser UI) that both engines plug into.
• FedoraBridge.app — a double-click wrapper that launches the web app.

Raw-disk reads on macOS require admin rights, which is why it asks for your password. It runs from Terminal because Terminal already holds the macOS permission needed to read external disks.

More background: PRD.md (product requirements) and PHASE-0-SPIKE.md (the feasibility proof).

---

Requirements

• macOS (Apple Silicon or Intel), reasonably current.
• Python 3 (ships with macOS; the first run may prompt to install Command Line Tools).
• For Btrfs zstd-compressed files: libzstd (e.g. brew install zstd). Not needed for Windows/NTFS.
• The disk must be unencrypted (no LUKS / no BitLocker).

Limitations

• Read-only. By design — it can never write back to the source disk.
• No encrypted disks (LUKS / BitLocker) in this version.
• NTFS-compressed files (LZNT1) are skipped with a clear message rather than risk returning wrong bytes — regular files are unaffected.
• Fedora-focused, but the engines are filesystem-based, so other Linux distros on Btrfs and other Windows NTFS volumes generally work too.

Safety

The source disk is opened O_RDONLY and there is no code path that writes to it. Copies onto your Mac are verified with SHA-256. Your password stays on your machine; nothing is uploaded anywhere.

License

MIT. Provided as-is, no warranty. Recovering data is inherently risky — keep backups.