Install

Install the webfold CLI and MCP server on Linux, macOS and Windows: requirements, the curl and PowerShell installers, prebuilt tarballs, Docker and Kubernetes, source builds, checksums, upgrades, uninstalling and troubleshooting.

Webfold ships two programs: webfold, the command-line tool, and webfold-mcp, the MCP server. Both come from the same source tree. The repository also builds a container image and Kubernetes manifests for the flaresolverr-compatible HTTP API; see Containers and Kubernetes.

Status of each method

System requirements

• Rust toolchain 1.97.0. The repository pins it in rust-toolchain.toml. Install rustup and it selects the pinned version when you run Cargo inside the checkout. The workspace also declares rust-version = "1.87" for some of its crates.
• Operating system. The engine describes native support for Linux, macOS and Windows. Its continuous integration runs on Linux (ubuntu-latest), so Linux is the best-tested platform. macOS and Windows are compiled in CI, but no workflow runs the tests there. The curl installer supports Linux (x86_64, aarch64) and macOS (x86_64, arm64). The PowerShell installer supports Windows x86_64 only.
• Network access during the build. Cargo fetches crates from crates.io and some pinned dependencies from git. A build behind a proxy or without access to GitHub will fail while fetching them. Some of the pinned git dependencies are private repositories (under Ptyktos/ in Cargo.toml). A build needs read access to them, so it can fail for anyone without that access.
• Optional: Linux 5.13 or newer for the sandbox. webfold sandbox runs commands inside a Landlock filesystem restriction. It is not in the default feature set; build with --features sandbox. On kernels older than 5.13 the sandbox is a no-op.
• Build time. No minimum RAM or disk figure is published. The engine’s Nix notes give a cold build of the full dependency set at about 25 minutes on 4 CPUs.

Build from source

From the root of a checkout, build the CLI and the MCP server in release mode:

cargo build --release --locked --bin webfold --bin webfold-mcp
./target/release/webfold --version

The binaries are in target/release/. Copy them somewhere on your PATH, or use cargo install below.

The default feature set includes native networking, bundled fonts for the screenshot renderer, the embedded view engine, OSINT commands and sealed secrets. Document libraries and the JSONL, Parquet and Iceberg sinks are part of the native feature.

Install with cargo

From the checkout, cargo install copies the binaries into ~/.cargo/bin:

cargo install --locked --path . --bin webfold
cargo install --locked --path . --bin webfold-mcp

Make sure ~/.cargo/bin is on your PATH.

Build with Nix

The repository contains a flake.nix that builds the product binaries from pinned inputs. You need Nix with flakes enabled. The builder must run with the sandbox on. Run this from a checkout, which is not public yet.

nix build .#webfold
./result/bin/webfold --version
nix build .#webfold-mcp -o result-mcp

Nix only sees git-tracked files, so add any new local files to git before building.

Install with the curl installer

The installer supports Linux on x86_64 and aarch64, and macOS on Intel and Apple silicon. It downloads the tarball named in the release’s SHA256SUMS file, checks its sha256 hash, and installs the binaries. It never calls sudo. On macOS it uses shasum -a 256 when sha256sum is not installed.

curl -fsSL https://webfold.ai/download/latest/install.sh | sh

To read the script before running it, or to see what it would do:

curl -fsSLO https://webfold.ai/download/latest/install.sh
sh install.sh --dry-run
sh install.sh

Options:

The default install directory is ~/.local/bin. When run as root it is /usr/local/bin. Use --dir to choose another location. The script prints every URL before it fetches it, and it sends no telemetry.

If the install directory is not on your PATH, the script prints the line to add to your shell profile.

Prebuilt tarball

The planned layout of a public release is:

• webfold-<version>-<target>.tar.gz, one per target:
  • x86_64-unknown-linux-gnu
  • aarch64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin
• webfold-<version>-x86_64-pc-windows-msvc.zip for Windows, see Windows.
• SHA256SUMS, with one line per archive.

Download, verify, and unpack:

curl -fsSLO https://webfold.ai/download/latest/SHA256SUMS
curl -fsSLO https://webfold.ai/download/latest/webfold-<version>-x86_64-unknown-linux-gnu.tar.gz
sha256sum -c SHA256SUMS --ignore-missing
tar -xzf webfold-<version>-x86_64-unknown-linux-gnu.tar.gz
install -m 755 webfold webfold-mcp ~/.local/bin/

Replace <version> with the release number shown in SHA256SUMS. Versioned downloads use https://webfold.ai/download/<version>/<file> in the same way.

macOS

macOS on Intel (x86_64-apple-darwin) and Apple silicon (aarch64-apple-darwin). The curl installer chooses the right tarball from uname -m. To do it by hand, download the tarball for your machine, check it, and unpack it:

curl -fsSLO https://webfold.ai/download/latest/SHA256SUMS
curl -fsSLO https://webfold.ai/download/latest/webfold-<version>-aarch64-apple-darwin.tar.gz
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf webfold-<version>-aarch64-apple-darwin.tar.gz
install -m 755 webfold webfold-mcp ~/.local/bin/

Release signing and notarization are not published yet. The checksum shows that the download is intact, not who published it.

cargo install --git is not available, because there is no public repository to install from. It has not been run on macOS.

Windows

PowerShell installer

install.ps1 runs on Windows PowerShell 5.1 and on PowerShell 7. It checks the release zip against SHA256SUMS with Get-FileHash before it reads the archive. It refuses archive members whose paths leave the install directory. It installs to %LOCALAPPDATA%\Programs\webfold\bin and needs no administrator rights. If that directory is not on your user PATH, the script offers to add it and changes nothing unless you say yes.

Download the script, read it, and run it as a file:

Invoke-WebRequest https://webfold.ai/download/latest/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -DryRun
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

Do not pipe the script into Invoke-Expression. Run it as a file so that you can read what it does first.

Manual zip

Invoke-WebRequest https://webfold.ai/download/latest/SHA256SUMS -OutFile SHA256SUMS
Invoke-WebRequest https://webfold.ai/download/latest/webfold-<version>-x86_64-pc-windows-msvc.zip -OutFile webfold.zip
(Get-FileHash .\webfold.zip -Algorithm SHA256).Hash
Select-String -Path SHA256SUMS -Pattern x86_64-pc-windows-msvc
Expand-Archive -LiteralPath .\webfold.zip -DestinationPath .\webfold

Compare the two hashes, ignoring case. Then copy webfold.exe and webfold-mcp.exe to a directory on your PATH.

Build from source

Not public yet, and not run on Windows. It will need the Rust toolchain from rustup, the MSVC build tools, and access to the private git dependencies pinned in Cargo.toml.

Containers and Kubernetes

The container image and the Kubernetes manifests serve the flaresolverr-compatible HTTP API. They do not run the webfold command-line tool. The image runs one binary, flaresolverr, which listens on port 8191 and answers POST /v1 and GET /health. The API has no authentication, so expose it only to trusted callers.

Docker

The image is based on Alpine and runs as a non-root user. Build it locally. BuildKit is required, because the build uses a secret. The build fetches private git dependencies, so you need a token with read access to them, passed as CARGO_SUBSTRATE_TOKEN. The secret is mounted only during the build step and is not written into an image layer.

DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile \
  --secret id=cargo_substrate_token,env=CARGO_SUBSTRATE_TOKEN \
  -t webfold-flaresolverr:dev .

Run it, bound to localhost on the host, then check the health endpoint and send a request:

docker run --rm -p 127.0.0.1:8191:8191 webfold-flaresolverr:dev

curl -fsS http://127.0.0.1:8191/health
curl -fsS -H 'Content-Type: application/json' \
  -d '{"cmd":"request.get","url":"https://example.com"}' \
  http://127.0.0.1:8191/v1

The image sets HOST=0.0.0.0 so the port can be published. The host side is limited to 127.0.0.1 for that reason.

Kubernetes

The base manifest refers to the image webfold-flaresolverr:0.1.0, which is not published. Build and push your own copy first, then set its registry and tag in an overlay. deploy/k8s/overlays/example shows the fields.

kubectl apply -k deploy/k8s/overlays/example
kubectl -n webfold get pods,svc

# Allow a client namespace to reach the API
kubectl label namespace <client-namespace> webfold.dev/ingress-client=true

The manifests create:

• a ClusterIP Service named webfold-flaresolverr in the webfold namespace, on port 8191. It is not exposed outside the cluster. Use your own ingress or gateway for that.
• a default-deny ingress policy for the namespace. Only namespaces labelled webfold.dev/ingress-client=true can reach port 8191.
• an egress policy that allows DNS and HTTPS on port 443 and excludes the cloud metadata address 169.254.169.254.

Some network plugins also block kubelet probe traffic under a default-deny policy. If the probes fail after you apply the policy, allow the node address range on port 8191 for your plugin.

Debian, Ubuntu, Fedora, RHEL and Arch

These packages are not available yet. No .deb, apt repository, .rpm, dnf repository, or AUR package has been published. The curl installer, the tarball and a source build are not public yet either.

Verify checksums

Every release lists the sha256 of each archive in SHA256SUMS. Verify an archive before you unpack it:

sha256sum -c SHA256SUMS --ignore-missing

On macOS, use shasum -a 256 -c SHA256SUMS --ignore-missing. On Windows, compare the output of Get-FileHash -Algorithm SHA256 with the line for the zip in SHA256SUMS.

Check the build

webfold --version
webfold doctor          # build profile, pinned dependency revisions, git HEAD, environment check
webfold doctor --json

doctor performs no network I/O. Run it first when a build behaves differently from the documentation.

Upgrade

• Curl installer or tarball: run the installer again. It replaces the binaries with the latest release. To pin a version, pass --version.
• PowerShell installer or zip: run install.ps1 again, with -Version to pin a release.
• Source checkout: git pull, then rebuild with cargo build --release --locked, or run cargo install --locked --path . --bin webfold --force again.

Uninstall

• Curl installer or tarball: sh install.sh --uninstall, or remove the files directly with rm ~/.local/bin/webfold ~/.local/bin/webfold-mcp.
• PowerShell installer: powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall. It removes the two .exe files and leaves PATH unchanged. Remove the install directory from your PATH yourself if you added it.
• Cargo: cargo uninstall webfold and cargo uninstall webfold-mcp.
• Docker: docker rmi webfold-flaresolverr:dev removes the local image.
• Kubernetes: kubectl delete -k deploy/k8s/overlays/example.
• Source checkout: delete the checkout. Build outputs stay inside target/ in that checkout.

Optional pieces

• A Chromium for --render. Webfold never launches a browser. If you want rendered-page extraction, run a Chromium yourself and point Webfold at its CDP endpoint. See Rendered pages.
• curl, gunzip and pdffold. The proxy fetch route can invoke curl, WARC decompression can invoke gunzip, and PDF commands can invoke pdffold. They are part of the trusted perimeter; see Security.

Troubleshooting

“Webfold has no public download yet. The source and first binaries open with the public release: …” The installer got HTTP 404 for SHA256SUMS. No public release exists yet, or the version you asked for does not exist. Nothing was installed. If you passed --version, the message names the version it could not find.

“webfold has no prebuilt binary for … yet.” The curl installer supports Linux (x86_64, aarch64) and macOS (x86_64, arm64). The PowerShell installer supports Windows x86_64 only. On other systems there is no binary. The message points to this page.

“running scripts is disabled on this system” (Windows). Run the installer with powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1. This applies only to that run and does not change your execution policy.

“checksum mismatch … nothing was installed.” The archive does not match SHA256SUMS. The download may have been cut short or changed in transit. Run the installer again. If it keeps failing, report it with the URL it printed.

“need curl or wget” or “need sha256sum or shasum”. Install the missing tool. The installer refuses to install a binary it cannot verify.

Permission denied when installing to /usr/local/bin. Install into your home directory instead: sh install.sh --dir ~/.local/bin. The installer never uses sudo.

webfold: command not found after installing. The install directory is not on your PATH. Add it, for example export PATH="$HOME/.local/bin:$PATH", then open a new shell.

A source build fails while fetching dependencies. Check your network access to crates.io and GitHub, and check that rustup installed the pinned toolchain from rust-toolchain.toml. Run rustup show inside the checkout to see which toolchain is active.

The build behaves differently from the documentation. Run webfold doctor and compare the git revision it prints with the commit you intended to build.