Skip to Content
WebFrostdocs
Getting started

Install

Install the webfrost binary on macOS or Linux, set up Chromium, and run the server.

WebFrost is one file, webfrost: the CLI, the server, the web UI and the scheduler. It needs no Bun, Node or Docker. To run from a source checkout instead, see Development. To run only the server in a container, see the Quickstart.

Install

Windows

There is no Windows binary yet. Run WebFrost with Docker Desktop and the Docker quickstart.

macOS and Linux, x64 and arm64:

curl -fsSL https://webfrost.dev/install.sh | sh

The script downloads the archive for your machine from the latest GitHub release, checks its SHA-256 against the release's checksums.txt (and installs nothing if it does not match), and puts webfrost in ~/.local/bin. It never uses sudo. If that directory is not on your PATH it tells you how to add it.

VariableDefaultEffect
WEBFROST_VERSIONlatest releaseInstall this version, for example 0.1.0
WEBFROST_INSTALL_DIR~/.local/binWhere to put the binary
WEBFROST_DOWNLOAD_BASEthe GitHub releaseURL that holds the archives and checksums.txt. For testing and mirrors.
curl -fsSL https://webfrost.dev/install.sh | WEBFROST_VERSION=0.1.0 WEBFROST_INSTALL_DIR=/usr/local/bin sh

The Linux binaries need glibc. On Alpine and other musl systems use the Docker image.

The binary is 90 to 120 MB, because it contains the Bun runtime, the web UI and every dependency.

Check it:

webfrost --version
webfrost doctor

Chromium

WebFrost needs a Chromium or Chrome for four extractors: PDF, screenshot, DOM snapshot and SingleFile. Without one the snapshot still finishes done with WARC, Readability and HTML, and each missing extractor is recorded as failed.

webfrost setup

setup looks for a browser first and installs nothing if it finds a working one. Otherwise it downloads Playwright's headless Chromium (about 100 MB) into WebFrost's own cache directory: ~/.cache/webfrost on Linux ($XDG_CACHE_HOME/webfrost when that is set), ~/Library/Caches/webfrost on macOS, %LOCALAPPDATA%\webfrost on Windows (WEBFROST_CACHE_DIR overrides it). Nothing is installed system-wide.

Every command looks for the browser in this order, and uses the first match:

  1. WEBFROST_CHROMIUM_PATH, taken as given: a wrong path is an error, never a silent fallback.
  2. The Chromium webfrost setup installed in the cache directory.
  3. A system Chrome or Chromium: /Applications/Google Chrome.app, /usr/bin/chromium, chromium-browser, google-chrome on PATH, C:\Program Files\Google\Chrome, and Edge or Chromium in the equivalent places.
  4. Playwright's own browser cache (what bunx playwright install chromium fills).

Linux libraries

The downloaded browser needs system libraries (glib, nss, atk, gbm and others). A desktop Linux has them; a minimal server or container may not. setup and doctor start the browser on a blank page to check, and when a library is missing they print the command that installs them on your system (apt-get, with the right package names for Debian and Ubuntu, dnf or pacman). Run it, then webfrost setup again. Installing Chromium itself (apt install chromium) works too: setup will find it.

yt-dlp and ffmpeg

Optional. They add video and audio archiving: yt-dlp downloads the media and ffmpeg merges the streams.

# macOS
brew install yt-dlp ffmpeg

# Debian, Ubuntu
sudo apt install yt-dlp ffmpeg

# Fedora (ffmpeg is in RPM Fusion)
sudo dnf install yt-dlp ffmpeg

Both have to be on PATH. Without yt-dlp, media extraction is skipped and no failure is recorded.

Check the setup

webfrost doctor
[ok  ] WebFrost: v0.1.0 (compiled binary, Bun 1.4.4, linux/x64)
[ok  ] Data directory: /home/you/.webfrost (writable, will be created on first use)
[ok  ] Database: no archive.db yet (created on first use)
[ok  ] Chromium: /home/you/.cache/webfrost/browsers/... (Google Chrome for Testing 147.0.7727.15; cache)
[warn] yt-dlp: not found (optional: needed to archive video and audio)
       -> sudo apt install yt-dlp   (Fedora: sudo dnf install yt-dlp; or pipx install yt-dlp)
[ok  ] ffmpeg: /usr/bin/ffmpeg (ffmpeg version 7.1)
[ok  ] Port 3000: free on 127.0.0.1

doctor exits 1 when something required is missing: a writable data directory, a database that opens, or a working Chromium. Missing yt-dlp or ffmpeg, or a busy port, is only a warning. --json prints the same checks for scripts.

Run the server

webfrost serve

This starts the REST API, the web UI and the scheduler in one process, on http://localhost:3000. Open it and create the admin user in the setup wizard, or from the CLI:

webfrost admin create --username admin
# Password: (typed without echo)

serve reads the same environment variables as the Docker image: PORT, HOST, WEBFROST_DIR, SESSION_SECRET, AUTH_DISABLED and the rest of the configuration. --port and --host override PORT and HOST.

The session secret

SESSION_SECRET signs login cookies. When it is not set, serve generates one on first run and keeps it in <data dir>/session-secret, readable only by you (mode 0600), so logins survive restarts. Keep the data directory private and back it up with the archive, or set SESSION_SECRET yourself to manage it elsewhere.

Data directory

The CLI and the server share one archive: WEBFROST_DIR, or ~/.webfrost when it is not set. Prefer an absolute path if you set it. The database stores file references as paths, so a relative ./data only works while you start every command from the same directory.

Stop it with Ctrl+C: the scheduler stops first, then running archives get up to 20 seconds (WEBFROST_SHUTDOWN_TIMEOUT_MS) to finish, and anything unfinished resumes the next time you start.

Verify

webfrost add https://example.com
webfrost list
curl http://localhost:3000/health

If something fails, see Troubleshooting.

On this page