Zero to a running Ferail. This guide assumes nothing is installed yet. If you already build Rust projects, skip to Build & run.
Where Ferail runs today. macOS is the primary, daily-driver platform. Windows builds and runs natively with broad parity (verified on-device). Linux builds and runs but is an early port. See the Current status table for the honest breakdown: this guide flags the per-platform steps as you go.
Just want to run it? macOS, Windows and Linux have prebuilt downloads on the Releases page: see Download. This guide is for building from source.
Ferail is not published to crates.io, so build it from this workspace rather
than using cargo install. GPUI and gpui-component come from crates.io, with
a Git patch for the GPUI platform crate. The committed Cargo.lock pins the
dependency versions.
- 1. Install the prerequisites
- 2. Get the code
- 3. Build & run
- 4. Verify your setup
- 5. macOS: the signed
.appbundle - 6. Windows: a distributable build
- 7. Optional: enable the mpv video backend
- 8. Command-line tools
- Troubleshooting
- Where to go next
Install Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThen restart your shell (or source "$HOME/.cargo/env"). You don't need to
pick a version: the repo's rust-toolchain.toml pins
the stable channel (with clippy + rustfmt), and rustup installs/selects it
automatically the first time you build inside the repo. Ferail needs a recent
stable toolchain (GPUI uses Rust edition 2024).
You also need git to clone the repo and to fetch the git dependencies.
-
macOS: install the Xcode Command Line Tools (the C linker + system SDKs):
xcode-select --install
That's all the system tooling a default build needs.
-
Windows: install the MSVC toolchain: Visual Studio Build Tools with the "Desktop development with C++" workload (or full Visual Studio), then the
x86_64-pc-windows-msvcRust target (rustup's default on Windows). See docs/features/windows-port.md for the current state of the Windows port. -
Linux: you need a C toolchain,
pkg-config,cmake, and working Vulkan drivers (the single most common first-run blocker). On Ubuntu/Debian:sudo apt install -y build-essential pkg-config cmake \ libwayland-dev libxkbcommon-dev libxcb1-dev \ libvulkan1 mesa-vulkan-drivers vulkan-tools \ libssl-dev libzstd-dev libdbus-1-dev vulkaninfo | head -n 20 # should print a device, not an error
Fedora equivalents and the full Linux story (including WSL2) are in docs/features/linux-port.md.
For PDF thumbnails and previews on Linux, install Poppler’s pdftoppm
(poppler-utils on Debian/Ubuntu, poppler on Arch). Ferail renders the first
page; PDF documents are recognized by their contents, not their extension.
The built-in viewer plays mp4 / m4v / mov out of the box. The optional
mpv backend (any container, plus live grading and the transparent
chroma-key windows) loads a user-installed libmpv at runtime: Ferail
never bundles it. Install it only if you want that path:
# macOS
brew install mpvRelease downloads (the DMG, the Windows ZIP, the .deb) already compile the
mpv provider in: install libmpv and select mpv under Settings → Plugins,
no rebuild needed. The .deb recommends libmpv2, so apt normally installs it
alongside. When you build from source, the provider is off by default; add
--features mpv (see step 7).
git clone https://github.com/jonx/Ferail.git
cd Ferailcargo run --bin ferail-gpuiThe first build clones gpui / gpui-component from git and compiles a
large dependency tree: expect several minutes and a lot of crates. This is
normal and happens once; later builds are incremental and fast.
A window opens onto your home folder. You're running Ferail.
macOS note: folder access. Run loosely like this, Ferail inherits your terminal's privacy identity, so reads of protected folders (Desktop / Documents / Downloads / removable / network) show an in-app "Access required" screen instead of the normal system prompt. To get the real "…would like to access…" prompts, run the signed app bundle: see step 5 and its permissions notes.
cargo test --workspace # the test suite should pass
cargo run --bin ferail-gpui -- --doctor # health check: config, storage, deps--doctor prints a storage/environment report and exits: handy if the GUI
won't start, and the same report the in-app Settings → Diagnostics page
shows. (Sharing a report? The Diagnostics page redacts file names and paths by
default, so it's safe to send.)
For the real per-folder access prompts (and a normal app you can launch from Finder), build a bundle:
scripts/bundle-mac.sh && open target/Ferail.appThis ad-hoc-signs the app by default. For grants that persist across rebuilds, sign with a real identity:
CODESIGN_IDENTITY="Developer ID Application: …" scripts/bundle-mac.shmacOS gates the protected folders (Desktop, Documents, Downloads, removable volumes, network volumes, cloud providers) behind its privacy system (TCC). The "Ferail would like to access files in your Documents folder" prompt only appears when all of these hold:
- the path is in one of those promptable categories (arbitrary folders are never promptable: they need Full Disk Access);
- Ferail runs as a code-signed
.appbundle with a stable identity; - that bundle's
Info.plistdeclares the matchingNS*UsageDescriptionstring (packaging/macos/Info.plist).
Caveats:
-
Stale grants from terminal runs. Earlier
cargo runsessions attribute grants/denials to Terminal, not Ferail. If the bundle doesn't prompt, clear the stale state:tccutil reset SystemPolicyRemovableVolumes me.jkn.ferail tccutil reset SystemPolicyDocumentsFolder me.jkn.ferail
-
Ad-hoc signing doesn't persist. The default ad-hoc signature changes every build, so macOS treats each build as a new app and re-prompts. Sign with a real identity (above) for grants that stick.
-
After a denial, macOS never re-prompts. Once you click "Don't Allow", the only recourse is the in-app "Open Full Disk Access settings" link (also the path for arbitrary, non-promptable folders).
cargo run is all you need for development: unlike macOS, Windows gates no
folders behind a signed-bundle identity, so there is no permissions reason to
package. Packaging is purely for handing the app to someone else:
./scripts/package-win.ps1That builds release binaries, stages them with the licence files, and writes
target/package/Ferail-<version>-win-x64.zip:
Ferail/
├── Ferail.exe the app
├── cli/ferail.exe the `ferail magic` / `ferail du` CLI
└── licenses/ MIT, Apache-2.0, third-party notices
The CLI sits in cli/ rather than beside the app on purpose: Windows paths are
case-insensitive, so ferail.exe next to Ferail.exe is one file and the
second one written silently wins. The script asserts the two staged binaries
are distinct so that cannot regress.
Install Inno Setup
(winget install JRSoftware.InnoSetup) and it also emits a …-setup.exe
installer with a Start Menu entry and an uninstaller.
macOS has notarization; Windows has Authenticode + SmartScreen reputation. An unsigned build works perfectly, but anyone who downloads one meets a "Windows protected your PC" interstitial, and reputation accrues to the certificate over time, so a public release wants signing from the first release, not the third:
./scripts/package-win.ps1 -SignCert C:\certs\ferail.pfx -SignPassword ...
# or, for a cert already in the user's store, pass its SHA1 thumbprint:
./scripts/package-win.ps1 -SignCert 9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B$env:FERAIL_SIGN_CERT / $env:FERAIL_SIGN_PASSWORD work too, which is the
shape CI wants. Both the payload and the installer get signed, and the script
prints a Get-AuthenticodeSignature summary at the end. signtool.exe comes
from the Windows SDK; the script finds it without a Developer Prompt.
With libmpv installed (step 1):
cargo run --bin ferail-gpui --features mpv(Release downloads and the packaging scripts already build with this feature;
the flag matters for cargo run/cargo build from source, where it is off by
default.)
Then open Settings → Plugins, set the video player to mpv, and (if it isn't auto-found) point it at your libmpv. Now the viewer plays virtually any container and unlocks live grading + the chroma-keyed transparent video windows.
Ferail ships a few non-GUI utilities:
cargo run --bin ferail -- magic <path>... # identify file types by content
cargo run --bin ferail -- du [--top N] [--packages] <path> # disk-usage summary
cargo run --bin ferail-gpui -- --doctor # health check
cargo run --bin ferail-gpui -- --reset-db <scope> # reset local metadata- First build takes forever. Expected: it's compiling
gpuiand the git dependency tree from source the first time. Incremental builds afterward are quick. Don't deleteCargo.lock; it pins the reproducible set. - macOS: folders show "Access required." You're running the loose binary, which can't prompt. Build and run the bundle (step 5).
- Linux: blank window or a panic on launch. Almost always missing/broken
Vulkan. Install
mesa-vulkan-drivers(or vendor drivers) and confirm withvulkaninfo; in a VM, enable 3D acceleration or a software Vulkan (lavapipe). See docs/features/linux-port.md → Day-one steps. - mpv video doesn't play. Confirm libmpv is installed and that
Settings → Plugins has mpv selected with a valid library path (source
builds also need
--features mpv; release downloads have it).--doctorreports whether libmpv was found.
- README.md: overview, features, and platform status.
- docs/ARCHITECTURE.md: how the code is organized and the one rule that shapes it (the UI must never stop).
- CONTRIBUTING.md: the contribution workflow (AI PRs welcome) and the pre-PR checklist.
- CLAUDE.md: the operating manual if you're driving an AI agent.
- TODO.md: what's unfinished and where to help.