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
- Pick your platform in the asset table and copy its download command.
- Verify the checksum with the command for your shell.
- Put the binary on your
PATHusing the per-platform steps (Linux, macOS, Windows). - 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.
| Platform | CLI asset (inside the release) | Format |
|---|---|---|
| Linux x86_64 | webfang-x86_64-unknown-linux-gnu.tar.gz | .tar.gz |
| Linux ARM64 | webfang-aarch64-unknown-linux-gnu.tar.gz | .tar.gz |
| macOS Apple Silicon | webfang-aarch64-apple-darwin.tar.gz | .tar.gz |
| Windows x86_64 | webfang-x86_64-pc-windows-msvc.zip | .zip |
| Any platform | SHA256SUMS.txt | checksum manifest |
The other two archives per platform hold the MCP servers — same targets, same format as the CLI archive for that platform:
| Platform | HTTP server | stdio server |
|---|---|---|
| Linux x86_64 | webfang-mcp-x86_64-unknown-linux-gnu.tar.gz | webfang-mcp-stdio-x86_64-unknown-linux-gnu.tar.gz |
| Linux ARM64 | webfang-mcp-aarch64-unknown-linux-gnu.tar.gz | webfang-mcp-stdio-aarch64-unknown-linux-gnu.tar.gz |
| macOS Apple Silicon | webfang-mcp-aarch64-apple-darwin.tar.gz | webfang-mcp-stdio-aarch64-apple-darwin.tar.gz |
| Windows x86_64 | webfang-mcp-x86_64-pc-windows-msvc.zip | webfang-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.jsonbundle 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.txtis 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.jsonbundle, 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 xzfalone is usually enough. Useinstall -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 linkslibc/libm(glibc), pluslibstdc++andlibgcc_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/.rpmand 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/Safariand then extracted carries thecom.apple.quarantineextended 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 withxattr -d com.apple.quarantine webfang(orxattr -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.exeon Windows,webfangeverywhere else. The command iswebfangeither way. %USERPROFILE%\binavoids needing Administrator rights. The PATH edit only reaches new terminals — re-open yours before step 5.- If the system-wide
%ProgramFiles%\webfangroute is preferred, copywebfang.exethere 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.dllwas 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.
| Binary | Transport | Use it when |
|---|---|---|
webfang-mcp | Streamable HTTP, 127.0.0.1:8080/mcp by default | a local service that several clients share over HTTP |
webfang-mcp-stdio | stdin/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
| Platform | Requirement | Why |
|---|---|---|
| Linux x86_64 / ARM64 | glibc 2.39 or newer; no musl build exists | The 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. |
| macOS | Apple Silicon only | Intel macOS has no artifact (decision pre-dating the ONNX removal; the target list was never extended). |
| Windows | Visual C++ Redistributable 2015-2022 (x64) | MSVC's default dynamic CRT. |
| Any | ~17 MB download, no installer, no bundled runtime | stripped 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 binaries | Consequence |
|---|---|
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 feature | The SQLite checkpoint store is absent. File-based --resume state is unaffected. |
console feature | tokio-console is not available. Tracing via --trace-file is. |
adaptive-selectors feature | Adaptive 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_clibuilds 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 location | Command |
|---|---|
Linux, /usr/local/bin | sudo rm /usr/local/bin/webfang |
Linux, ~/.local/bin | rm ~/.local/bin/webfang |
macOS, /usr/local/bin | sudo rm /usr/local/bin/webfang |
Windows, %USERPROFILE%\bin | Remove-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_HOMEmoves the webfang roots; it never moved the model.Also note
XDG_CACHE_HOME/XDG_CONFIG_HOMEare honored only when they hold an absolute path — a relative or empty value is ignored, and the platform default is used instead. Theechoabove prints the variable even when WebFang ignores it; a path that looks wrong is probably this.
| Path (relative to the base above) | Created by | Size | Auto-cleaned? |
|---|---|---|---|
webfang/state/<domain>.json | --resume | KBs, grows with processed-URL count | No — relocatable via --state-dir / WEBFANG_STATE_DIR |
webfang/state/<domain>.json.lock | every RecordStore write | 0 B | No — permanent by design. See the note below. |
webfang/state/<domain>.json.bak | migrating a stale state version | same as state | No — an existing backup is kept as-is |
~/.webfang/crawl.db — absolute, under $HOME, not the cache base | crawl/scrape runs that persist to SQLite (only with the persistence feature — absent from the release binary): extraction fingerprints, resources, chunks, notes | grows with fingerprinted pages | Rows 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 below | pre-paso-6 releases only (ADR-0004) — current builds never write it | 0 for current builds; up to 372 MB / ~1.2 GB for old ones | No — relocatable via HF_HOME, a HuggingFace variable, not WEBFANG_* |
<output_dir>/ — Markdown, export.jsonl, rag_dataset/, _inbox/ | every run | unbounded — your data | Opt-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 it | KBs | No — relocatable via WEBFANG_CONFIG or XDG_CONFIG_HOME |
The
.locksentinel is supposed to survive.<domain>.json.lockis created on demand and intentionally never unlinked; the real mutual exclusion is an advisoryflockthe kernel releases when the process exits, including after akill -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.
| Platform | Default 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 onPATH. -
webfang --versionprints a version. -
On macOS,
com.apple.quarantineis cleared if the first run was killed. -
I know where my
output/directory is, and that uninstalling will not remove it.
Next step
- Troubleshooting — install-time failures, slow crawls, WAF blocks, SSRF refusals.
- CLI Reference — the complete flag reference.
- Debugging & Observability — tracing, correlation IDs, and
the
jqquery cookbook.