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 | shThe 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.
| Variable | Default | Effect |
|---|---|---|
WEBFROST_VERSION | latest release | Install this version, for example 0.1.0 |
WEBFROST_INSTALL_DIR | ~/.local/bin | Where to put the binary |
WEBFROST_DOWNLOAD_BASE | the GitHub release | URL 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 shThe 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 doctorChromium
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 setupsetup 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:
WEBFROST_CHROMIUM_PATH, taken as given: a wrong path is an error, never a silent fallback.- The Chromium
webfrost setupinstalled in the cache directory. - A system Chrome or Chromium:
/Applications/Google Chrome.app,/usr/bin/chromium,chromium-browser,google-chromeonPATH,C:\Program Files\Google\Chrome, and Edge or Chromium in the equivalent places. - Playwright's own browser cache (what
bunx playwright install chromiumfills).
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.1doctor 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 serveThis 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/healthIf something fails, see Troubleshooting.