---
title: "Install"
description: "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](#containers-and-kubernetes).

:::warning
Webfold has no public download yet. The source and the first binaries open with the public release. A 0.1.0 build for Linux x86_64 exists in a private repository, so you cannot fetch it. Every method below is a planned route, and each one states its status.
:::

## Status of each method

| Method | Status |
| --- | --- |
| Build from a source checkout with Cargo | Not public yet: the source is private |
| Build with Nix from the repository flake | Not public yet: the source is private |
| curl installer (`install.sh`), Linux and macOS | Waits for the public release |
| PowerShell installer (`install.ps1`), Windows x86_64 | Waits for the public release, and unverified |
| Prebuilt tarball or zip with `SHA256SUMS` | Not public yet. The 0.1.0 build has no checksum file |
| `cargo install --git` from the repository | Not public yet |
| Docker image (Alpine, flaresolverr API) | Not published. A local build needs the source |
| Kubernetes manifests (`deploy/k8s/`) | Not public yet, and unverified |
| Debian and Ubuntu (`.deb`, apt) | Not available yet |
| Fedora and RHEL (`.rpm`, dnf) | Not available yet |
| Arch Linux (AUR) | Not available yet |
| Hosted API | Early access, no install. Join the waitlist |

## System requirements

- **Rust toolchain 1.97.0.** The repository pins it in `rust-toolchain.toml`. Install [rustup](https://rustup.rs) 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.

:::note
The engine's `docs/NIX.md` mentions a Rust channel of 1.99.0 for the Nix build, while `rust-toolchain.toml` pins 1.97.0. Source builds with Cargo use the toolchain file.
:::

## Build from source

:::note
Not public yet. The source repository is private and opens with the public release. The steps below are for a checkout of it.
:::

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

```sh
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`:

```sh
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.

```sh
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

:::note
Waits for the public release. Until then the script stops with a message and changes nothing.
:::

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.

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

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

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

Options:

| Option | Effect |
| --- | --- |
| `--version VERSION` | Install a specific release instead of `latest`. Also `WEBFOLD_VERSION`. |
| `--dir DIR` | Install into `DIR`. Also `WEBFOLD_INSTALL_DIR`. |
| `--dry-run` | Print the URLs and the install plan. Downloads only `SHA256SUMS` and changes nothing else. |
| `--uninstall` | Remove `webfold` and `webfold-mcp` from the install directory. |
| `--help` | Show the 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

:::note
Not public yet. The 0.1.0 build is in a private repository. It has two Linux x86_64 tarballs (glibc and musl) and no checksum file.
:::

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](#windows).
- `SHA256SUMS`, with one line per archive.

Download, verify, and unpack:

```sh
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

:::note
Not public yet. The curl installer and the tarball above are the planned routes. Both need a public release, and 0.1.0 has no macOS build.
:::

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:

```sh
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

:::warning
Unverified. Nothing on this page has been run on Windows. Windows x86_64 (`x86_64-pc-windows-msvc`) is the only Windows target. Windows on ARM is not supported.
:::

### PowerShell installer

:::note
Waits for the public release. The script stops with a message until then.
:::

`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:

```powershell
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
```

| Option | Effect |
| --- | --- |
| `-Version VERSION` | Install a specific release instead of `latest`. Also `WEBFOLD_VERSION`. |
| `-Dir DIR` | Install into `DIR`. Also `WEBFOLD_INSTALL_DIR`. |
| `-DryRun` | Print the URLs and the install plan. Downloads only `SHA256SUMS`. |
| `-Uninstall` | Remove `webfold.exe` and `webfold-mcp.exe` from the install directory. |
| `-Help` | Show the options. |

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

### Manual zip

:::note
Not public yet. The 0.1.0 build has no Windows archive.
:::

```powershell
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

:::note
Unverified. The image is built from `docker/Dockerfile` in the webfold repository, which is private. It has not been built or run yet, and no image is published.
:::

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.

```sh
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:

```sh
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

:::note
Unverified. The manifests are in `deploy/k8s/` in the webfold repository, which is private. They were checked for YAML structure only. No cluster has been used to apply them.
:::

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.

```sh
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:

```sh
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`.

:::warning
A checksum shows that a download is intact. It does not prove who published it, because the checksum file comes from the same host as the archive. Release signatures are not published yet.
:::

## Check the build

```sh
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](/docs/guides/rendering).
- **`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](/docs/reference/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.

:::note
Prefer not to build anything? The [hosted API](/docs/api/overview) exposes the web capabilities over HTTP.
:::