Starting with v0.2.6.1, all Windows releases are digitally signed with a certificate from SignPath Foundation. This means:

• Windows SmartScreen recognizes the publisher — no more "Unknown publisher" warnings
• Antivirus false positives are significantly reduced thanks to the trusted code signature
• Integrity verification — you can verify that the binary hasn't been tampered with

Previous False Positives

Older unsigned builds may still trigger antivirus detections. This was caused by:

• Live Pipeline feature: Uses cmd.exe /C on Windows for shell commands, which ML-based detection can misidentify
• Rust compilation patterns: Rust binaries can trigger heuristic detections due to unique characteristics

We've addressed this through code signing, build profile adjustments (disabled symbol stripping, speed optimization), and reporting to Microsoft's Security Intelligence portal.

If You're Still Affected

If Windows Defender quarantines Ferrite:

1. Upgrade: Download the latest signed release from GitHub Releases
2. Verify the signature: Right-click ferrite.exe → Properties → Digital Signatures → should show "SignPath Foundation"
3. Check VirusTotal: Upload the file to VirusTotal — signed builds should show clean results

Ferrite does NOT access passwords, browser data, or make unsolicited network connections. The only network access is the manual "Check for Updates" button (Settings → About), which contacts the GitHub Releases API when you click it. The application only accesses files you explicitly open.

GitHub Release .dmg / .tar.gz builds are packaged as Ferrite.app but are not signed with an Apple Developer ID and are not notarized (CI limitation). Gatekeeper, especially on macOS 15.x (Sequoia / 15.6+), may block or warn on first launch—see GitHub #130 and the workarounds below.

📖 Full troubleshooting: docs/install/macos.md

Option 1: Homebrew (often smoothest)

brew tap olaproeis/ferrite
brew install --cask ferrite

Homebrew typically avoids quarantine friction compared to raw GitHub downloads.

Option 2: DMG / tar.gz from GitHub Releases + workaround

1. Download from Releases:
   • Apple Silicon: ferrite-macos-arm64.dmg or .tar.gz
   • Intel: ferrite-macos-x64.dmg or .tar.gz
2. Copy Ferrite.app to Applications (or another folder you prefer).
3. First launch — pick one:
   • Terminal (most reliable): xattr -dr com.apple.quarantine /Applications/Ferrite.app — use the real path if the app is not under /Applications.
   • Finder: Control-click Ferrite.app → Open → Open (may not work on every macOS 15.x configuration).
   • System Settings → Privacy & Security: after a blocked launch, use Open Anyway if shown.

Why this happens

Apple expects apps distributed outside the Mac App Store to be signed with a Developer ID certificate and notarized. Ferrite is open source—you can audit the code and build from source—but paid enrollment and CI wiring are still pending for GitHub-hosted macOS builds.

My Role

• Product direction — Deciding what to build and why
• Testing — Running the app, finding bugs, verifying features
• Review — Reading generated code, understanding what it does
• Orchestration — Managing the AI workflow effectively

The Workflow

1. Idea refinement — Discuss concepts with multiple AIs (Claude, Perplexity, Gemini Pro)
2. PRD creation — Generate requirements using Task Master
3. Task execution — Claude Opus handles implementation (preferring larger tasks over many subtasks)
4. Session handover — Structured prompts maintain context between sessions
5. Human review — Every handover is reviewed; direction adjustments made as needed

📖 Full details: AI Development Workflow

Open Process

The actual prompts and documents used to build Ferrite are public:

This transparency is intentional — I want others to learn from (and improve upon) this approach.

MSI Installer (Recommended)

Download ferrite-windows-x64.msi and run it. This will:

• Install Ferrite to C:\Program Files\Ferrite
• Add Start Menu shortcut with icon
• Enable easy uninstall via Windows Settings
• Store settings in %APPDATA%\ferrite\

Portable (ZIP)

Download ferrite-portable-windows-x64.zip and extract anywhere. The zip includes:

• ferrite.exe - the application
• portable/ - folder for all your settings
• README.txt - quick start guide

True portable mode: All configuration, sessions, and data are stored in the portable folder next to the executable. Nothing is written to %APPDATA% or the Windows registry. Perfect for USB drives or trying Ferrite without installation.

Debian/Ubuntu/Mint (.deb)

# Download the .deb file, then install with:
sudo apt install ./ferrite-editor_amd64.deb

# Or using dpkg:
sudo dpkg -i ferrite-editor_amd64.deb

Fedora/RHEL/CentOS (.rpm)

# Download the .rpm file, then install with:
sudo dnf install ./ferrite-editor.x86_64.rpm

# Or using rpm:
sudo rpm -i ferrite-editor.x86_64.rpm

Both .deb and .rpm packages will:

• Install Ferrite to /usr/bin/ferrite
• Add desktop entry (appears in your app menu)
• Register file associations for .md, .json, .yaml, .toml files
• Install icons for the system

Arch Linux (AUR)

Ferrite is available on the AUR:

• Ferrite (release package)
• Ferrite-bin (binary package)

# Release package
yay -Sy ferrite

# Binary package
yay -Sy ferrite-bin

Nix / NixOS (official flake)

# Run Ferrite directly from GitHub (no install)
nix run github:OlaProeis/Ferrite

# Drop into a shell that exposes ferrite in PATH
nix shell github:OlaProeis/Ferrite

From a local clone:

# Build package output
nix build .#ferrite
./result/bin/ferrite

# Enter development shell (Rust toolchain + system deps)
nix develop

Other Linux (tar.gz)

tar -xzf ferrite-linux-x64.tar.gz
./ferrite

Known Issues

Keyboard not working on Ubuntu 24.04 LTS (GNOME/Wayland)

Keyboard input does not work when Ferrite is launched under GNOME on Wayland (Ubuntu 24.04 LTS and similar). As a workaround, launch Ferrite with WAYLAND_DISPLAY unset to force X11 mode:

env -u WAYLAND_DISPLAY ferrite

To make this permanent for your desktop launcher, create a user-level desktop entry override:

mkdir -p ~/.local/share/applications
cp /usr/share/applications/ferrite-editor.desktop ~/.local/share/applications/ferrite-editor.desktop

Then edit ~/.local/share/applications/ferrite-editor.desktop and change the Exec line to:

Exec=env -u WAYLAND_DISPLAY ferrite %F

DMG Installer (Recommended)

Download the .dmg for your Mac:

• Apple Silicon (M1/M2/M3/M4): ferrite-macos-arm64.dmg
• Intel: ferrite-macos-x64.dmg

Open the DMG and drag Ferrite.app to the Applications folder. Launch from Launchpad or Spotlight.

From tar.gz (Alternative)

# Apple Silicon
tar -xzf ferrite-macos-arm64.tar.gz
cp -R Ferrite.app /Applications/

# Intel
tar -xzf ferrite-macos-x64.tar.gz
cp -R Ferrite.app /Applications/

Gatekeeper (GitHub downloads): Unsigned / non-notarized CI builds may be blocked on macOS 15.x. See docs/install/macos.md — quickest fix: xattr -dr com.apple.quarantine /Applications/Ferrite.app (adjust path). Tracked: #130.

Prerequisites

• Rust 1.70+ - Install from rustup.rs
• Platform-specific dependencies:

Nix users: you can skip manual dependency installation and use nix develop from the repository root (see flake.nix).

Windows:

• Visual Studio Build Tools 2019+ with C++ workload

Linux:

# Ubuntu/Debian
sudo apt install build-essential pkg-config libgtk-3-dev libxcb-shape0-dev libxcb-xfixes0-dev

# Fedora
sudo dnf install gcc pkg-config gtk3-devel libxcb-devel

# Arch
sudo pacman -S base-devel pkg-config gtk3 libxcb

macOS:

xcode-select --install

Build

# Clone the repository
git clone https://github.com/OlaProeis/Ferrite.git
cd Ferrite

# Build release version (optimized)
cargo build --release

# The binary will be at:
# Windows: target/release/ferrite.exe
# Linux/macOS: target/release/ferrite

# macOS: Create .app bundle (optional)
cargo install cargo-bundle
cargo bundle --release
# Bundle will be at: target/release/bundle/osx/Ferrite.app

macOS "Open With" Limitation: The app bundle includes file type associations, so Ferrite appears in Finder's "Open With" menu. However, opening files this way (or by dragging files onto the app icon) is not yet supported due to eframe/winit limitations. Workaround: Open files via Terminal: open -a Ferrite path/to/file.md or use File > Open within the app.

Development Builds: Building from the main branch gives you the latest features before they're officially released. These builds are untested and may contain bugs. For stable versions, download from GitHub Releases.

# Run from source
cargo run --release

# Or run the binary directly
./target/release/ferrite

# Open multiple files as tabs
./target/release/ferrite file1.md file2.md

# Show version
./target/release/ferrite --version

# Show help
./target/release/ferrite --help

See docs/cli.md for full CLI documentation.

File Operations

Navigation

Editing

View

Terminal Workspace

Terminal shortcuts are context-aware; they work when the terminal panel is focused.

Settings are stored in platform-specific locations:

• Windows: %APPDATA%\ferrite\
• Windows Portable: portable\ folder next to ferrite.exe
• Linux: ~/.config/ferrite/
• macOS: ~/Library/Application Support/ferrite/

Portable Mode (Windows): If a portable folder exists next to the executable, Ferrite automatically uses it for all configuration instead of %APPDATA%. This makes Ferrite fully self-contained - perfect for USB drives.

Workspace settings are stored in .ferrite/ within the workspace folder.

Settings Panel

• Appearance: Theme, font family, font size, default view mode
• Editor: Word wrap, line numbers, minimap, bracket matching, code folding, syntax highlighting, auto-close brackets, line width
• Files: Auto-save, recent files history

# Fork and clone
git clone https://github.com/YOUR_USERNAME/Ferrite.git
cd Ferrite

# Create a feature branch
git checkout -b feature/your-feature

# Make changes, then verify
cargo fmt
cargo clippy
cargo test
cargo build

# Optional (Nix users): validate flake outputs
nix flake check

# Commit and push
git commit -m "feat: your feature description"
git push origin feature/your-feature