Reference

Advanced install

Check a download's signature, build Ferret from source, get an older version, and see how updates work. You don't need any of this to install Ferret.

#All downloads

Files are served from Cloudflare R2, not GitHub Releases, and only the 10 most recent versions are kept. The download page lists every one of them.

OSFiles
macOS (Apple silicon / Intel)Ferret-<version>-mac-arm64.dmg, Ferret-<version>-mac-x64.dmg
Windows (x64 / arm64)Ferret-<version>-win-x64.exe, Ferret-<version>-win-arm64.exe (installer)
Linux (x64)Ferret-<version>-linux-x86_64.AppImage, Ferret-<version>-linux-amd64.deb

Releases up to 0.1.x were published under the old name, as MOVIE-ADE-<version>-…. The Ferret-… names start with 0.2.0.

#Verify the download (signed SHA256SUMS)

Every release has a SHA256SUMS file and its signature SHA256SUMS.sig. The signature is made with the Ferret release key, which is kept apart from the download server, so a changed installer on the download server can't come with a valid signature. The public key is not taken from the download server: get it from the repository (build/release-signing/allowed_signers (opens in a new tab)) or copy it from here:

[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEpXERU8ST0MEOIMbzoL4zShkjIrMB4++NL3xBohKAS9

Its fingerprint is SHA256:c7dvwwJQyY9qSstkmrO8JoVZ90DCaFZBAzjqV04N8zQ. The same files are attached to each release on GitHub. Check the signature with ssh-keygen (included in macOS, Windows 10 and later, and Linux), then compare the hash of your download with the signed list:

# the download server (currently the R2 public URL; it may move to a custom domain)
BASE=https://pub-588d93b3e875464f98d6cf98dc711a0c.r2.dev
VERSION=$(curl -s $BASE/latest.json | jq -r .version)
curl -sO $BASE/releases/$VERSION/SHA256SUMS
curl -sO $BASE/releases/$VERSION/SHA256SUMS.sig

# save the public key above as allowed_signers, then:
ssh-keygen -Y verify -f allowed_signers -I [email protected] -n ferret-release -s SHA256SUMS.sig < SHA256SUMS
# → Good "ferret-release" signature for [email protected] …

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing
# Linux
sha256sum -c SHA256SUMS --ignore-missing
# Windows (PowerShell): compare with the line for your file in SHA256SUMS
Get-FileHash .\Ferret-<version>-win-x64.exe -Algorithm SHA256

Stop if ssh-keygen doesn't print Good "ferret-release" signature or the hash isn't in the list. Ferret's Check for Updates does the same check with the key built into the app and doesn't offer a version whose signature doesn't match. On macOS you can also check the Developer ID signature and notarization with spctl -a -vv /Applications/Ferret.app. For releases up to 0.3.0, compare with the hashes in releases/<version>/manifest.json.

#Older macOS versions

For versions up to 0.2.0 build 2: if macOS says the developer cannot be verified, close the dialog, open System Settings → Privacy & Security, click Open Anyway next to the Ferret message, and confirm with Open. If it says the app "is damaged", remove the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/Ferret.app

#Build from source

Requires Node.js 20+ (CI and local development use 22), pnpm, and git.

git clone https://github.com/JapanMarketing-Dev/ferret.git
cd ferret
pnpm install          # postinstall prepares node-pty for Electron
pnpm dev              # run in development mode

To package installers (output in dist/release/, config in electron-builder.config.cjs). The Linux build only runs on Linux.

pnpm dist:mac     # dmg (arm64, x64)
pnpm dist:win     # NSIS installers (x64, arm64)
pnpm dist:linux   # AppImage + deb (x64)

The build:<os>:dev scripts produce an unpacked app only (--dir), which is faster for local testing.

On Windows, pnpm install uses node-pty's bundled prebuilt binaries instead of rebuilding (that would need the Visual Studio C++ build tools). Set ADE_FORCE_NATIVE_REBUILD=1 to force a rebuild.

If the terminal reports that node-pty could not be loaded, run pnpm rebuild:native.

#Updates

Ferret checks for a new version when it starts, every 6 hours, and when you click Check for Updates (footer → Updates). It fetches latest.json from the download server (R2) and checks the signature of that version's SHA256SUMS with the release key built into the app. A version whose signature doesn't match is not offered.

When a newer version is found, Ferret downloads it in the background and shows the progress in Updates. The download is used only if its size and SHA-256 match the signed list. Once it is ready, Updates shows that it will be installed the next time you close Ferret: quit Ferret as usual, and the next time you open it, it is the new version. You don't need to download or run an installer yourself, and Ferret never restarts on its own, so agents keep working until you close it.

To install right away, click Restart to Update in Updates or in the footer. If an agent is working in a terminal or a recording is running, Ferret asks first; the recording so far is saved before the restart.

Install typeWhat is downloadedHow it is installed
macOSFerret-<version>-mac-<arch>.zip, listed in UPDATE-SHA256SUMS and signed with the same release keyhanded to the macOS updater (Squirrel.Mac), which also checks that the new app has the same Developer ID signature; installed when you close Ferret (or with Restart to Update)
Windowsthe installer (.exe)runs without any windows after you close Ferret; with Restart to Update it then opens the new version
Linux (AppImage)the new .AppImagereplaces the AppImage you started when you close Ferret; with Restart to Update it then opens the new version
Linux (deb)the .debOpen Installer saves it to your Downloads folder and opens it in your software installer

To update only when you choose, turn off Update automatically in Updates (or set "autoUpdate": false in settings.json). Ferret then doesn't download or install anything on its own: click Download when a new version is shown, then Restart to Update. Development builds (pnpm dev) don't download in the background; Download saves the checked installer to your Downloads folder.

Edit this page on GitHub (opens in a new tab)