Skip to Content
WebFrostdocs
Getting started

Quickstart

Install the webfrost binary and archive your first page in a few minutes, or run the server with Docker Compose.

Two ways to run WebFrost: the webfrost binary (a single file for macOS and Linux) or the Docker image. The binary also gives you the command-line tools; the image bundles Chromium, yt-dlp and ffmpeg, so every extractor works out of the box.

Install

curl -fsSL https://webfrost.dev/install.sh | sh
# or: brew install gtkatakura/tap/webfrost

Details and manual downloads: Install.

Get a browser

webfrost setup     # a headless Chromium, if you have none
webfrost doctor    # what is installed, what is missing

setup does nothing when a Chrome or Chromium is already on the machine.

Start the server

webfrost serve     # server, web UI and scheduler on :3000

Open http://localhost:3000. On the first visit a setup wizard asks for a username and a password of at least 8 characters, then signs you in. The session secret is generated for you and stored in the data directory (~/.webfrost).

Archive, search, import, schedule

In another terminal:

webfrost add https://example.com
webfrost search "example domain"
webfrost import bookmarks.html
webfrost schedule add https://example.com --cron "0 * * * *"

The CLI and the server use the same archive, so what add saves shows up in the web UI.

Plain HTTP on a LAN address

If you open http://192.168.x.x:3000 and login bounces back to the login page, the session cookie is the cause: it is marked Secure, and browsers drop it on plain-HTTP origins other than localhost. Serve WebFrost over TLS, or set WEBFROST_INSECURE_COOKIES=true for an HTTP-only deployment. See Deploy.

Common settings

Compose reads these from .env; webfrost serve reads them from the environment. Only SESSION_SECRET is required, and serve generates one when it is not set.

VariableDefaultPurpose
SESSION_SECRETnoneAt least 32 random characters. Required by the Docker image.
PORT3000Port to listen on (host port in Compose)
WEBFROST_CONCURRENCY3Pipelines run in parallel
WEBFROST_TRUST_PROXYfalsetrue behind a reverse proxy
WEBFROST_PUBLIC_READfalseLet anonymous visitors browse read-only
TZUTCTime zone for cron schedules
IMAGE_TAGlatestImage tag to pull (Compose)

Every variable is listed in Configuration.

Next

On this page