Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation & Uninstall

WebFang is a binaries-only distribution. There is no cargo install webfang and nothing is published to crates.io — the release automation sets git_only = true and publish = false in release-plz.toml, so a cargo install webfang cannot work. Get the binary from GitHub Releases.

Releases · Troubleshooting · CLI Reference · Release Feature Matrix


Quick path

  1. Pick your platform in the asset table and copy its download command.
  2. Verify the checksum with the command for your shell.
  3. Put the binary on your PATH using the per-platform steps (Linux, macOS, Windows).
  4. Confirm it runs: webfang --version.

If step 4 fails, go straight to install-time failures.


1. Pick your asset

Every release publishes twelve archives — three per platform — plus one checksum file. The asset name carries the full Rust target triple — there is no friendly OS alias and no version in the name (the version is in the tag/URL, not the file). Each archive contains a bare binary: no install script, no LICENSE, no README inside.

PlatformCLI asset (inside the release)Format
Linux x86_64webfang-x86_64-unknown-linux-gnu.tar.gz.tar.gz
Linux ARM64webfang-aarch64-unknown-linux-gnu.tar.gz.tar.gz
macOS Apple Siliconwebfang-aarch64-apple-darwin.tar.gz.tar.gz
Windows x86_64webfang-x86_64-pc-windows-msvc.zip.zip
Any platformSHA256SUMS.txtchecksum manifest

The other two archives per platform hold the MCP servers — same targets, same format as the CLI archive for that platform:

PlatformHTTP serverstdio server
Linux x86_64webfang-mcp-x86_64-unknown-linux-gnu.tar.gzwebfang-mcp-stdio-x86_64-unknown-linux-gnu.tar.gz
Linux ARM64webfang-mcp-aarch64-unknown-linux-gnu.tar.gzwebfang-mcp-stdio-aarch64-unknown-linux-gnu.tar.gz
macOS Apple Siliconwebfang-mcp-aarch64-apple-darwin.tar.gzwebfang-mcp-stdio-aarch64-apple-darwin.tar.gz
Windows x86_64webfang-mcp-x86_64-pc-windows-msvc.zipwebfang-mcp-stdio-x86_64-pc-windows-msvc.zip

The CLI archive never contains an MCP binary: webfang-mcp and webfang-mcp-stdio each have their own archive, because every archive holds exactly one binary.

There is no Intel macOS artifact. x86_64-apple-darwin is deliberately not built. The original reason was ONNX-local (no x64 macOS prebuilt for ONNX Runtime); the ONNX removal (ADR-0004 paso 6) makes that reason moot, but the target list was never extended — each release re-trains on the artifact list as-is, so the entry stays. If you are on an Intel Mac, there is nothing to mis-download — see Intel macOS.

Set the version once and reuse it. Copy the tag from the latest release:

VERSION=v2.12.0   # ← the tag you just looked up
Verify these names yourself (any release, any version)
gh release view v2.12.0 --json assets --jq '.assets[].name'

Observed output for v2.11.0:

SHA256SUMS.txt
SHA256SUMS.txt.sigstore.json
THIRD_PARTY_NOTICES.txt
THIRD_PARTY_NOTICES.txt.sigstore.json
webfang-aarch64-apple-darwin.tar.gz
webfang-aarch64-apple-darwin.tar.gz.sigstore.json
webfang-aarch64-unknown-linux-gnu.tar.gz
webfang-aarch64-unknown-linux-gnu.tar.gz.sigstore.json
webfang.spdx.json
webfang.spdx.json.sigstore.json
webfang-x86_64-pc-windows-msvc.zip
webfang-x86_64-pc-windows-msvc.zip.sigstore.json
webfang-x86_64-unknown-linux-gnu.tar.gz
webfang-x86_64-unknown-linux-gnu.tar.gz.sigstore.json

2. Verify the checksum

Each release ships a SHA256SUMS.txt listing the SHA-256 of every archive. Verify the archive you downloaded, before extracting it. The command differs per platform: sha256sum is GNU coreutils and does not exist on stock macOS, and PowerShell has neither it nor shasum.

Linux (GNU coreutils) — checks the archive against the manifest:

sha256sum -c SHA256SUMS.txt --ignore-missing

macOS (shasum, ships with the system) — BSD coreutils has no -c/--ignore-missing; check the one file you downloaded:

shasum -a 256 webfang-aarch64-apple-darwin.tar.gz
grep 'aarch64-apple-darwin' SHA256SUMS.txt

The two hashes must be identical.

Windows (PowerShell) — Get-FileHash, compared against the manifest line:

(Get-FileHash webfang-x86_64-pc-windows-msvc.zip -Algorithm SHA256).Hash.ToLower()
Select-String -Path SHA256SUMS.txt -Pattern 'pc-windows-msvc'

If you have GitHub CLI installed, it fetches both files for you (it does not verify them — do step 2 anyway):

gh release download "${VERSION}" --pattern 'SHA256SUMS.txt'
gh release download "${VERSION}" --pattern 'webfang-x86_64-unknown-linux-gnu.tar.gz'

Every published asset carries a real SLSA provenance attestation, minted keyless by the release workflow, plus a .sigstore.json bundle next to it in the release. Verify a downloaded file against the digest you actually have:

gh attestation verify webfang-x86_64-unknown-linux-gnu.tar.gz \
  --repo XaviCodeDev1000/webfang

SHA256SUMS.txt is the offline check and stays authoritative for integrity. The provenance table in the release body is WebFang's own L1 gate — a summary written by the workflow, not the attestation itself; verify against the API or the .sigstore.json bundle, never against that table.


3. Install

Every recipe below is copy-pasteable as a unit. The three unix steps — download, verify, extract — are identical apart from the asset name, so only the differing part is repeated per platform.

Linux

# 1. Download (x86_64; use aarch64-unknown-linux-gnu on ARM64)
VERSION=v2.12.0
curl -fLO "https://github.com/XaviCodeDev1000/webfang/releases/download/${VERSION}/webfang-x86_64-unknown-linux-gnu.tar.gz"
curl -fLO "https://github.com/XaviCodeDev1000/webfang/releases/download/${VERSION}/SHA256SUMS.txt"

# 2. Verify BEFORE extracting
sha256sum -c SHA256SUMS.txt --ignore-missing

# 3. Extract; the archive holds a single file named `webfang`
tar xzf webfang-x86_64-unknown-linux-gnu.tar.gz

# 4. Put it on PATH (system-wide)
sudo install -m 0755 webfang /usr/local/bin/webfang

#    …or per-user, no sudo:
# mkdir -p ~/.local/bin && install -m 0755 webfang ~/.local/bin/webfang
#   then add to PATH if needed: export PATH="$HOME/.local/bin:$PATH"

# 5. Confirm
webfang --version

Notes:

  • The archive holds a bare binary and preserves its executable bit, so tar xzf alone is usually enough. Use install -m 0755 (as above) to guarantee the bit regardless of how the archive was extracted — a file-manager double-click can drop it.
  • The binary is stripped, but it is not fully static: it links libc/libm (glibc), plus libstdc++ and libgcc_s (BoringSSL is C++). All are standard on glibc distros, but a minimal or musl-based image will fail to load it until they are present. There is no .deb/.rpm and no bundled runtime to install.

macOS (Apple Silicon)

# 1. Download
VERSION=v2.12.0
curl -fLO "https://github.com/XaviCodeDev1000/webfang/releases/download/${VERSION}/webfang-aarch64-apple-darwin.tar.gz"
curl -fLO "https://github.com/XaviCodeDev1000/webfang/releases/download/${VERSION}/SHA256SUMS.txt"

# 2. Verify BEFORE extracting (no sha256sum on stock macOS)
shasum -a 256 webfang-aarch64-apple-darwin.tar.gz
grep 'aarch64-apple-darwin' SHA256SUMS.txt

# 3. Extract; the archive holds a single file named `webfang`
tar xzf webfang-aarch64-apple-darwin.tar.gz

# 4. Put it on PATH (system-wide)
sudo install -m 0755 webfang /usr/local/bin/webfang

#    …or per-user:
# mkdir -p ~/.local/bin && install -m 0755 webfang ~/.local/bin/webfang

# 5. Clear the quarantine flag (see note), then confirm
xattr -d com.apple.quarantine webfang 2>/dev/null || true
webfang --version

Gatekeeper. A binary downloaded with curl/Safari and then extracted carries the com.apple.quarantine extended attribute, and macOS kills it on first run with "cannot be opened because the developer cannot be verified". It is not corrupt and the checksum will match. Remove the attribute with xattr -d com.apple.quarantine webfang (or xattr -dr com.apple.quarantine <dir>), then run it. Right-click → Open works too, once.

Intel macOS (unsupported)

No artifact exists for Intel macOS, and that is deliberate — it is a decision, not a release gap, so do not go looking for an Intel macOS archive among the assets.

Building from source works on the normal developer path (Rust 1.91 toolchain, cmake for BoringSSL — see from source). The old ONNX excuse no longer applies (ADR-0004 paso 6 removed the ai feature and the local engine), so a source build has no semantic holes: --clean-ai resolves its endpoint through --embedding-provider, Obsidian vault search included. What you lose on one machine is only runtime network policy — except under --offline, where NO embeddings provider is usable: the guard rejects every one of them, a remote endpoint or a loopback one, and the run exits with 78. Since 3.0.0 there is no local engine to fall back to, so --clean-ai and --offline are mutually exclusive. And --offline gates the SEMANTIC-CLEANING providers, not the crawler's network: it means "no semantic cleaning", not "no network" — it only works offline when no embeddings provider is selected at all (no --embedding-provider, and no provider with the embedding capability in the config), otherwise the run fails with exit 78 (ADR-0004 §46, corrected 2026-10-21).

Behind a corporate proxy?

WebFang ignores the proxy environment (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY) by design — for the AI endpoints and for crawling alike (#2500, see data flow). If your network only egresses through a proxy, run a local forwarding sidecar, point the provider's base_url at it, and opt that provider into loopback endpoints; the sidecar talks to the corporate proxy, WebFang does not. webfang doctor states this posture on every run.

Windows

# 1. Download (PowerShell 5.1+)
$Version = "v8.0.0"
$Asset   = "webfang-x86_64-pc-windows-msvc.zip"
Invoke-WebRequest "https://github.com/XaviCodeDev1000/webfang/releases/download/$Version/$Asset" -OutFile $Asset
Invoke-WebRequest "https://github.com/XaviCodeDev1000/webfang/releases/download/$Version/SHA256SUMS.txt" -OutFile SHA256SUMS.txt

# 2. Verify BEFORE extracting
(Get-FileHash $Asset -Algorithm SHA256).Hash.ToLower()
Select-String -Path SHA256SUMS.txt -Pattern 'pc-windows-msvc'

# 3. Extract; the archive holds a single file named `webfang.exe`
Expand-Archive -Path $Asset -DestinationPath .

# 4. Put it on PATH (per-user, no admin)
$Bin = "$env:USERPROFILE\bin"
New-Item -ItemType Directory -Force -Path $Bin | Out-Null
Move-Item -Force webfang.exe "$Bin\webfang.exe"
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$Bin",
    "User")

# 5. Open a NEW terminal, then confirm
webfang --version

Notes:

  • The binary is webfang.exe on Windows, webfang everywhere else. The command is webfang either way.
  • %USERPROFILE%\bin avoids needing Administrator rights. The PATH edit only reaches new terminals — re-open yours before step 5.
  • If the system-wide %ProgramFiles%\webfang route is preferred, copy webfang.exe there instead.

Visual C++ runtime. The Windows artifact is built with MSVC, which links the dynamic CRT by default. A machine without the Visual C++ Redistributable fails at startup with "The code execution cannot proceed because VCRUNTIME140.dll was not found". That is the redistributable being absent, not a broken download — install the Microsoft Visual C++ Redistributable 2015-2022 (x64) from Microsoft and re-run. Verify your checksum first either way, so the two causes stay distinguishable.

MCP servers (from the release artifact)

Two of the three archives per platform hold an MCP server. Both expose the same 36 tools; what differs is how a client reaches them.

BinaryTransportUse it when
webfang-mcpStreamable HTTP, 127.0.0.1:8080/mcp by defaulta local service that several clients share over HTTP
webfang-mcp-stdiostdin/stdout (JSON-RPC)a desktop client — Claude Desktop, OpenCode, Cline — spawns the server as a subprocess

Installing them is the CLI's recipe unchanged: same SHA256SUMS.txt verification, same extraction, same PATH. Only the asset name changes.

stdio. There is nothing to start by hand — the client owns the process. Point its command at the installed binary; an absolute path is safest, because a desktop client usually does not inherit your shell's PATH:

webfang-mcp-stdio

HTTP. Run it as a local service:

webfang-mcp --allow-anonymous                       # loopback only, no token
webfang-mcp --auth-token "$WEBFANG_MCP_AUTH_TOKEN"  # clients send Authorization: Bearer <token>
webfang-mcp --allow-anonymous --bind 127.0.0.1:9090  # move it off the default port

webfang-mcp refuses to start without either --allow-anonymous or --auth-token. An unset credential used to mean "anyone who can reach the socket", so the token-less default is a hard error, not a warning. --allow-anonymous is a loopback affordance only: a routable bind still requires --auth-token, and the transport is plain HTTP, so terminate TLS in front of it before exposing it beyond localhost.

Both binaries accept --export-roots <dir> (repeatable or comma-separated). Absolute output_dir / checkpoint_dir paths in a tool call are rejected unless they fall under a declared root — relative paths always work, so you only need this when a client passes absolute ones.


Platform requirements

PlatformRequirementWhy
Linux x86_64 / ARM64glibc 2.39 or newer; no musl build existsThe artifacts are built on GitHub's ubuntu-latest runner (Ubuntu 24.04, glibc 2.39) and link glibc directly. The floor is inherited from the builder, not a chosen target — so a distro older than Ubuntu 24.04 has no compatible artifact.
macOSApple Silicon onlyIntel macOS has no artifact (decision pre-dating the ONNX removal; the target list was never extended).
WindowsVisual C++ Redistributable 2015-2022 (x64)MSVC's default dynamic CRT.
Any~17 MB download, no installer, no bundled runtimestripped binary; needs only standard system libraries (glibc + libstdc++/libgcc_s).

If a Linux binary dies immediately with /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.xx' not found, the distro is older than the floor above. There is no musl/static artifact to fall back to; build from source instead.


What is not in the release binary

The release build is one invocation that compiles the CLI and both MCP servers with no capability features enabled:

cargo build --release --locked --features "webfang_cli/mcp" \
  --target <target-triple> -p webfang_cli -p webfang_mcp --bins

The mcp feature of that command is inert (an explicit-empty marker): the webfang CLI carries zero MCP code — the servers are the separate webfang-mcp / webfang-mcp-stdio binaries in their own archives. (The former ai feature no longer exists at all, ADR-0004 paso 6: remote-embedding semantic cleaning ships in the default build — migration guide.)

The full capability-by-capability matrix — what each of the three binaries can do, and the flags that bring each capability back when building from source — lives in the Release Feature Matrix. The short version, before you file a bug:

Missing from the release binariesConsequence
chromium feature--js-strategy full is rejected at preflight (it needs a Chromium downloader). The default static strategy and the 3-layer hybrid strategy are unaffected.
persistence featureThe SQLite checkpoint store is absent. File-based --resume state is unaffected.
console featuretokio-console is not available. Tracing via --trace-file is.
adaptive-selectors featureAdaptive selector learning is off — its flags do not exist in this build.

From source (developers)

Not an installation route for end users — this is the contributor path. It downloads and compiles every dependency, BoringSSL included.

Prerequisites: Rust 1.91 (rust-toolchain.toml pins it), a C/C++ compiler, git, and cmake. cmake is mandatory: the HTTP client wreq → btls → btls-sys (formerly boring2/boring-sys2) compiles BoringSSL from C++ source on first build, and without cmake the failure surfaces deep inside a build script with an error that says nothing about the real cause.

git clone https://github.com/XaviCodeDev1000/webfang.git
cd webfang
cmake --version        # must print a version; install cmake if empty
cargo build --release --locked --features mcp -p webfang_cli
./target/release/webfang --version
  • -p webfang_cli builds only the CLI. Omitting it builds every workspace member.
  • The first build compiles BoringSSL from source and takes minutes, not seconds. This is normal.
  • Build-time egress: since the ONNX removal (ADR-0004 paso 6) the only third-party endpoint a build touches is crates.io. (Pre-paso-6 builds also pulled ONNX Runtime from cdn.pyke.io.)

Uninstall

WebFang never removes anything for you. Each binary is one file; the cache and output trees it creates are entirely your responsibility.

1. Remove the binary

Install locationCommand
Linux, /usr/local/binsudo rm /usr/local/bin/webfang
Linux, ~/.local/binrm ~/.local/bin/webfang
macOS, /usr/local/binsudo rm /usr/local/bin/webfang
Windows, %USERPROFILE%\binRemove-Item "$env:USERPROFILE\bin\webfang.exe"

If you also installed the MCP servers, they are removed the same way: the same directory, the same commands, with webfang replaced by webfang-mcp and webfang-mcp-stdio (.exe on Windows). They share no state of their own — the caches below are the only other thing a run leaves behind.

2. Remove the data

Check where things actually live first. The biggest artifacts live under the webfang cache base; the expected output tree lives next to your runs. (The historical ~372 MB ONNX model cache is a pre-ADR-0004-paso-6 item: the current binary never creates it — see the legacy note below.) Start at the webfang cache base:

# Where the webfang cache base resolves on THIS machine — run the line
# that matches your platform, and note the printed path.
echo "${XDG_CACHE_HOME:-$HOME/.cache}"           # Linux
# echo "${XDG_CACHE_HOME:-$HOME/Library/Caches}"   # macOS
# echo "$env:LOCALAPPDATA"                         # Windows (PowerShell)

Every webfang/… row in the table below is relative to that base — the table does not repeat the webfang/ prefix on Windows, so %LOCALAPPDATA%\webfang\state is the state directory, not %LOCALAPPDATA%\webfang\webfang\state.

The config base is the sibling you will also want when cleaning up: ~/.config (Linux), ~/Library/Application Support (macOS), %APPDATA% (Windows).

⚠️ The model cache was NOT under any of those bases — legacy, pre-paso-6 (ADR-0004). It was the only entry in this table that did not live under the webfang cache base, and § below keeps its exact location on each platform for cleanup after an upgrade from an old release. XDG_CACHE_HOME moves the webfang roots; it never moved the model.

Also note XDG_CACHE_HOME / XDG_CONFIG_HOME are honored only when they hold an absolute path — a relative or empty value is ignored, and the platform default is used instead. The echo above prints the variable even when WebFang ignores it; a path that looks wrong is probably this.

Path (relative to the base above)Created bySizeAuto-cleaned?
webfang/state/<domain>.json--resumeKBs, grows with processed-URL countNo — relocatable via --state-dir / WEBFANG_STATE_DIR
webfang/state/<domain>.json.lockevery RecordStore write0 BNo — permanent by design. See the note below.
webfang/state/<domain>.json.bakmigrating a stale state versionsame as stateNo — an existing backup is kept as-is
~/.webfang/crawl.db — absolute, under $HOME, not the cache basecrawl/scrape runs that persist to SQLite (only with the persistence feature — absent from the release binary): extraction fingerprints, resources, chunks, notesgrows with fingerprinted pagesRows older than N days are pruned (plus VACUUM) when a run passes --retention-days N; otherwise delete the file while no run is active. Relocatable via --db-path / WEBFANG_DB_PATH
huggingface/hub/ — legacy only, see belowpre-paso-6 releases only (ADR-0004) — current builds never write it0 for current builds; up to 372 MB / ~1.2 GB for old onesNo — relocatable via HF_HOME, a HuggingFace variable, not WEBFANG_*
<output_dir>/ — Markdown, export.jsonl, rag_dataset/, _inbox/every rununbounded — your dataOpt-in: files older than N days are pruned when a run passes --retention-days N. Relocatable via -o / WEBFANG_OUTPUT; defaults to output/ in the current directory
webfang/config.toml (under the config base: ~/.config, ~/Library/Application Support, %APPDATA%)you, by editing itKBsNo — relocatable via WEBFANG_CONFIG or XDG_CONFIG_HOME

The .lock sentinel is supposed to survive. <domain>.json.lock is created on demand and intentionally never unlinked; the real mutual exclusion is an advisory flock the kernel releases when the process exits, including after a kill -9. Its presence after an uninstall is correct behaviour, not a failed removal. See troubleshooting.md.

To remove the webfang-owned cache roots and leave everything else alone:

# Linux / macOS: cache + state, but NOT the model cache
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/webfang"     # Linux
rm -rf "${XDG_CACHE_HOME:-$HOME/Library/Caches}/webfang"  # macOS
# Windows: cache + state, but NOT the model cache
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\webfang"

The model cache is the exception (legacy)

Since the ONNX removal (ADR-0004 paso 6) the current binary never creates this cache: there is no local model to fetch, and no hf-hub dependency remains. If you are upgrading from a pre-paso-6 release, the directory a previous binary filled still exists, is inert, and is entirely yours to delete; the details:

hf_hub (used by pre-paso-6 releases) does not use WebFang's platform helper. Its default is dirs::home_dir()/.cache/huggingface/hub — literally ~/.cache/… on every platform, including macOS and Windows, where the webfang cache base is ~/Library/Caches and %LOCALAPPDATA% respectively. It is only moved by HF_HOME, and no WEBFANG_* or XDG_* variable relocates it.

PlatformDefault model cache (no HF_HOME)With HF_HOME=/some/dir
Linux~/.cache/huggingface/hub/some/dir/hub
macOS~/.cache/huggingface/hub — not ~/Library/Caches/…/some/dir/hub
Windows%USERPROFILE%\.cache\huggingface\hub — not %LOCALAPPDATA%\…/some/dir/hub

To confirm before deleting, and to remove it:

# Unix
echo "${HF_HOME:-$HOME/.cache/huggingface}"
rm -rf "${HF_HOME:-$HOME/.cache/huggingface}"
# Windows
$HF = if ($env:HF_HOME) { $env:HF_HOME } else { "$env:USERPROFILE\.cache\huggingface" }
$HF
Remove-Item -Recurse -Force $HF

If HF_HOME is set, the default location is empty and deleting it recovers nothing — which is why the confirmation line comes first, and why the two are never collapsed into one rm.

Never delete a webfang directory without reading the path you built above — a relative or empty base would resolve to somewhere unintended, and <output_dir> is user data with no backup.


Checklist

A fresh install is done when all of these are true:

  • I picked the asset whose target triple matches my machine (Apple Silicon, not "Intel").
  • The SHA-256 of my archive matches its line in SHA256SUMS.txt.
  • The binary is executable (chmod +x / install -m 0755) and on PATH.
  • webfang --version prints a version.
  • On macOS, com.apple.quarantine is cleared if the first run was killed.
  • I know where my output/ directory is, and that uninstalling will not remove it.

Next step