Installing Sailfin

Just want the binary? Head to the Downloads page for pre-built binaries for every supported platform, or keep reading for the recommended install script.

Requirements

Sailfin runs on the following platforms:

Platform	Architectures	Tier
Linux	x86_64	Tier 1 — primary
Linux	arm64 (aarch64)	Tier 2 — supported
macOS	arm64 (Apple Silicon)	Tier 2 — supported
Windows	x86_64	Tier 3 — best effort

These are the platform assets produced by the release workflow. The scripts can detect additional architectures, but installation stops when the selected release does not contain a matching archive. WSL on an x86_64 Windows host uses the Linux x86_64 asset; Git Bash installs the Windows x86_64 asset.

This table describes base support: published toolchains backed by platform validation. It is not a capability-seal claim. Linux arm64 is a Tier 2 base target, but owned syscalls and a fully gated syscall boundary are not supported there.

Windows is a Tier 3 (best-effort) target. A published installer does not by itself promote a platform. Windows x86_64 ships two release assets as of v0.10.3: a native MSVC build with a real TLS 1.3 stack, and a legacy build cross-compiled from Linux whose TLS is stubbed out, so its https:// requests fail before reaching the network. sfn toolchain install, install.ps1, and install.sh all prefer the native MSVC asset and fall back to the legacy one only when no MSVC asset exists for that release/architecture (every release before v0.10.3, and Windows arm64 at any version — there is no native arm64 asset). The merge gate that blocks every source PR proves only that the legacy build boots (--version) and runs sfn check on one example; a separate nightly job self-hosts and packages the native MSVC build, but neither leg runs the full test suite yet, and the native build cannot resolve hostnames over HTTPS today — the fix is merged to main but not yet in a release — so don’t expect sfn toolchain install/publish to work end-to-end on Windows until that ships. For day-to-day Sailfin work on a Windows machine, prefer WSL, which installs and runs the Tier 1 Linux x86_64 toolchain.

Compiler and linker tools

The installer only downloads and places the released sfn binary. To compile, run, or test Sailfin programs, the current backend still needs LLVM tools 17+ or 18+ plus clang and the platform linker. Release binaries do not bundle LLVM/clang.

The installer script itself also requires curl, tar, uname, mktemp, and jq on Linux/macOS because it selects release assets through the GitHub API. install.sh additionally requires an OpenSSL 3.0+ build (raw Ed25519 verification via pkeyutl -rawin needs 3.0) to verify the signed release manifest; it probes $SAILFIN_OPENSSL, openssl on PATH, and the Homebrew openssl@3 keg paths before giving up. install.ps1 needs no external verification tooling — its Ed25519 verifier is embedded pure PowerShell.

If you are building Sailfin itself from source, you also need bash, OpenSSL development libraries, and the source-build dependencies listed in Building from source.

---

Quick Install (recommended)

Linux and macOS

Paste the following into a terminal:

curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | bash

The script will:

1. Detect your OS and architecture
2. Download the latest matching release binary from GitHub Releases
3. Install sailfin and sfn to ~/.local/bin
4. Print confirmation when complete

Bootstrap security: The install script fails closed. It embeds the Sailfin release-signing public key and verifies the release before downloading the archive: it fetches SHA256SUMS and SHA256SUMS.sig, checks the Ed25519 manifest signature (requiring a KAT-passing OpenSSL 3.0+ on Linux/macOS; a self-contained embedded verifier on Windows, no external tooling needed), then checks the archive’s SHA-256 digest. A missing manifest/signature, a fetch that could not be reached at all, or no KAT-passing verifier on the host all abort the install. Set SAILFIN_ALLOW_UNVERIFIED=1 to explicitly consent to installing an unverified artifact anyway (an older unsigned release, or — on Linux/macOS only — a host with no working verifier; install.ps1 embeds its verifier, so no Windows host is in that state) — it never bypasses a failed signature or a digest mismatch. To verify manually instead, follow Verifying Your Download. Subsequent sfn toolchain install downloads verify both the Ed25519 signature and SHA-256 digest automatically (fail-closed).

Example output:

Detected: linux/x86_64
Downloading sfn <version>...
Installed sailfin -> /home/you/.local/bin/sailfin
Installed sfn    -> /home/you/.local/bin/sfn
Done. Run 'sfn --version' to verify.

Windows (PowerShell)

Paste the following into a PowerShell terminal (PowerShell 5.1+ or PowerShell 7+):

irm https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.ps1 | iex

The script installs sailfin.exe and sfn.exe to %LOCALAPPDATA%\sailfin\bin and adds that directory to your user PATH automatically. You do not need to run PowerShell as Administrator.

Example output:

Detected: windows/x86_64
Downloading sfn <version>...
Installed sailfin.exe -> C:\Users\you\AppData\Local\sailfin\bin\sailfin.exe
Installed sfn.exe     -> C:\Users\you\AppData\Local\sailfin\bin\sfn.exe
Added C:\Users\you\AppData\Local\sailfin\bin to user PATH.
Done. Restart your terminal, then run 'sfn --version' to verify.

Windows users: Restart your terminal after installation so that the updated PATH takes effect. If you use Windows Terminal, close and reopen the window.

---

Verifying the Installation

After installing, run:

sfn --version

Expected output:

sfn <version>

If the command is not found, see Troubleshooting below.

---

Pinning a Version

Sailfin is pre-1.0, so pin exact release versions in CI and reproducible setup scripts. Omit VERSION for the latest release asset that matches your platform. Compiler repository development uses the exact seed version in bootstrap.toml, not a hard-coded docs-page version.

Linux and macOS

Replace the example version with the release you want to pin:

VERSION=0.8.0
curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | VERSION="$VERSION" bash

You can also pass the version as an install-script argument:

VERSION=0.8.0
curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | bash -s -- --version "$VERSION"

Windows (PowerShell)

Replace the example version with the release you want to pin:

$env:VERSION = "0.8.0"
irm https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.ps1 | iex

Set $env:VERSION before invoking iex so the script reads it.

Why pin? The Sailfin project is marching toward a 1.0 release. Alpha builds may include regressions as large parts of the compiler and runtime are rewritten. Pinning gives CI and onboarding scripts a reproducible toolchain.

---

Verification and mirror environment variables

Both install scripts accept a few env vars beyond VERSION/REPO/GITHUB_TOKEN:

Variable	Effect
SAILFIN_OPENSSL	Path to an OpenSSL 3.0+ binary to try first as the signature verifier (Linux/macOS only).
SAILFIN_RELEASE_BASE	Overrides where SHA256SUMS, SHA256SUMS.sig, and the archive are fetched from (files read from <base>/<tag>/). Changes location only — verification stays mandatory and the trust anchor is never overridable.
SAILFIN_LOCAL_ARCHIVE	Installs a tarball already on disk instead of a published release. Requires an explicit VERSION.
SAILFIN_LOCAL_ARCHIVE_SHA256	Pins SAILFIN_LOCAL_ARCHIVE to a caller-supplied SHA-256, reaching trust state DIGEST_PINNED instead of requiring the opt-in below.
SAILFIN_ALLOW_UNVERIFIED=1	Consent to install an artifact whose signature chain cannot be established: an unsigned historical release, a local archive with no pinned digest, or (Linux/macOS only) no KAT-passing Ed25519 verifier on the host. Never bypasses a failed signature, a digest mismatch, a malformed manifest, or an unreachable manifest — those abort regardless.

See Verifying Your Download for the full trust-state model.

---

What Gets Installed

The installer places two binaries in the install directory. They are identical — sfn is a shorter alias for sailfin:

Binary	Purpose
sailfin	The full compiler and toolchain
sfn	Alias for sailfin; most examples and docs use sfn

Default install locations

Platform	Directory
Linux / macOS	~/.local/bin
Windows	%LOCALAPPDATA%\sailfin\bin

You can override the install directory by setting GLOBAL_BIN_DIR before running the script:

curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | GLOBAL_BIN_DIR=/usr/local/bin bash

Confirming the binaries are on PATH

/home/you/.local/bin/sfn

which sfn
sfn --version
# sfn <version>

On Windows:

\Users\you\AppData\Local\sailfin\bin\sfn.exe

Get-Command sfn
# CommandType  Name   Source

---

Manual Installation

If you cannot run the install script (e.g., in an air-gapped environment), you can download and place the binary manually. The Downloads page lists every platform binary with direct download links.

Step 1: Find the release asset

Go to the Downloads page or directly to github.com/SailfinIO/sailfin/releases and locate the release you want to install. Release assets follow this naming convention:

sailfin_<version>_<os>_<arch>.tar.gz

Examples:

Asset name	Platform
sailfin_${VERSION}_linux_x86_64.tar.gz	Linux x86_64
sailfin_${VERSION}_linux_arm64.tar.gz	Linux arm64 (aarch64)
sailfin_${VERSION}_macos_arm64.tar.gz	macOS Apple Silicon
sailfin_${VERSION}_windows_x86_64-msvc.tar.gz	Windows x86_64 (native MSVC — prefer this one)
sailfin_${VERSION}_windows_x86_64.tar.gz	Windows x86_64 (legacy mingw cross build — TLS is stubbed, so https:// never works)

Windows x86_64 has shipped both assets since v0.10.3; earlier releases have only the plain windows_x86_64.tar.gz name. If you are downloading manually, prefer the -msvc asset when it exists for your version.

Step 2: Verify the download

Download the tarball together with SHA256SUMS and SHA256SUMS.sig, then verify the manifest signature and the tarball digest before extracting it. The download verification guide provides copy-pasteable OpenSSL commands and publishes the canonical signing key and fingerprint.

VERSION=0.8.0

# Download (replace the filename with the one that matches your platform)
curl -LO "https://github.com/SailfinIO/sailfin/releases/download/v${VERSION}/sailfin_${VERSION}_linux_x86_64.tar.gz"
curl -LO "https://github.com/SailfinIO/sailfin/releases/download/v${VERSION}/SHA256SUMS"
curl -LO "https://github.com/SailfinIO/sailfin/releases/download/v${VERSION}/SHA256SUMS.sig"

Do not extract the archive unless both verification steps succeed.

Step 3: Extract and place the binary

VERSION=0.8.0

# Extract
tar -xzf "sailfin_${VERSION}_linux_x86_64.tar.gz"

# The archive contains bin/sailfin and bin/sfn
# Move them to a directory on your PATH
mkdir -p ~/.local/bin
cp bin/sailfin ~/.local/bin/sailfin
cp bin/sfn     ~/.local/bin/sfn
chmod +x ~/.local/bin/sailfin ~/.local/bin/sfn

Step 4: Verify the installed command

sfn --version
# sfn <version>

---

Building from Source

Building from source is useful when:

• You are contributing to the compiler
• You need a build for an unsupported platform
• You want to test unreleased changes

Prerequisites

• git, bash
• curl, tar, mktemp, uname, jq
• LLVM tools 17+ or 18+ (llvm-link, llvm-as)
• clang and the platform linker
• shasum -a 256 or sha256sum

See the compiler/runtime development setup for per-platform package commands and the complete supported build flag table.

Steps

# Clone the repository
git clone https://github.com/SailfinIO/sailfin.git
cd sailfin

# Install a released sfn (a clean checkout has none, and the next step needs one)
./install.sh

# Build the native compiler by self-hosting from the released seed pinned in bootstrap.toml
sfn dev bootstrap build

# Install the local self-build to ~/.local/bin
build/bin/sfn dev bootstrap install --from build/bin/sfn --prefix "$HOME/.local"

After installing, verify with:

sfn --version

You can also run the binary directly without installing:

build/bin/sfn --version

Use another --prefix to choose a different installation root. Packagers can add --destdir <staging-root>; a /usr/local prefix then lands beneath the stage as <staging-root>/usr/local/bin/sfn. The native install command refuses to overwrite an unmarked or externally changed live entry because it may be owned by a package manager. It also installs the runtime and compiler capsule closure beside the executable so the PATH command works outside the source checkout.

Note: sfn dev bootstrap build routes through <seed> build -p compiler — the Sailfin-native driver — and requires bash, clang, LLVM tools, and jq. The prior scripts/build.sh orchestrator is no longer in-tree.

---

Updating

To update to the latest release, re-run the install script. It overwrites the existing binaries in-place:

# Linux / macOS: update to latest
curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | bash

# Linux / macOS: update to a specific version
VERSION=0.8.0
curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | VERSION="$VERSION" bash

# Windows: update to latest
irm https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.ps1 | iex

As with the initial install, pinning to a known release version is recommended for CI and reproducible environments.

---

Uninstalling

Delete the binaries from the install directory:

# Linux / macOS
rm ~/.local/bin/sailfin ~/.local/bin/sfn

# Windows
Remove-Item "$env:LOCALAPPDATA\sailfin\bin\sailfin.exe"
Remove-Item "$env:LOCALAPPDATA\sailfin\bin\sfn.exe"

You may also want to remove %LOCALAPPDATA%\sailfin (Windows) or the now-empty ~/.local/bin entries from your shell profile, if applicable.

---

Troubleshooting

sfn: command not found after installation

The install directory is not on your PATH. Check which shell you are using and add the directory:

bash (~/.bashrc or ~/.bash_profile):

export PATH="$HOME/.local/bin:$PATH"

zsh (~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

After editing the file, reload it:

source ~/.bashrc   # or ~/.zshrc

On macOS, if you installed globally to /usr/local/bin, that directory is usually already on PATH. Confirm with echo $PATH.

Permission denied when running the binary (Linux / macOS)

The binary may not be marked executable. Fix it:

chmod +x ~/.local/bin/sailfin ~/.local/bin/sfn

Missing LLVM or clang during a build

Install the source-build dependencies for your platform:

# Ubuntu / Debian
sudo apt-get install clang-18 llvm-18 jq

# Fedora / RHEL
sudo dnf install clang llvm llvm-devel jq

# macOS (Homebrew)
brew install jq llvm

If Homebrew LLVM is installed but llvm-link is not detected, put it on PATH:

export PATH="$(brew --prefix llvm)/bin:$PATH"

GitHub API rate limiting during install

The install script calls the GitHub Releases API to find the latest version. If you hit rate limits (common in CI environments), set a GitHub token:

curl -fsSL https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.sh | GITHUB_TOKEN=ghp_your_token_here bash

Alternatively, pin the version explicitly with VERSION=<version> — this constructs the asset name directly and can avoid the release-list lookup.

Windows: script execution policy

If PowerShell refuses to run the install script, you may need to allow remote scripts for the current session:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
irm https://raw.githubusercontent.com/SailfinIO/sailfin/main/install.ps1 | iex

This change only affects the current PowerShell session and does not persist.

---

Next Steps

• Downloads — Pre-built binaries for every platform
• Verifying Your Download — Verify release signatures and checksums
• Editor Setup — Install the Sailfin VS Code extension for syntax highlighting and snippets
• Hello, World! — Write and run your first Sailfin program
• Tour of Sailfin — A guided introduction to the language