Skip to Content
WebFrostdocs
Reference

Web UI

Every page of the WebFrost web interface, what a guest sees, and the keyboard shortcuts.

The server serves the web UI next to the REST API, at http://localhost:3000 by default. It talks to the server only through the API, so it can do what an API key can do, no more.

Addresses

Pages live after a # in the address, so a link to a page or a snapshot works whatever the reverse proxy in front does with paths.

AddressPageGuests
/#/DashboardYes
/#/snapshotsSnapshotsYes
/#/snapshots/:idThe viewer of snapshot :id, on the whole windowYes
/#/search?q=…SearchYes
/#/tagsTagsYes, read-only
/#/schedulesSchedulesNo
/#/importImportNo
/#/settingsSettingsNo
/#/settings/api-keysAPI keysNo
/#/setupFirst-run setup, only until an admin exists
/#/loginSign in

?page= selects a page of results on Snapshots and Search. An unknown address goes to the Dashboard.

First run and sign-in

Until an admin exists, every address leads to setup: a username, a password of at least 8 characters, and, when the server sets WEBFROST_SETUP_TOKEN, a Setup token field. The second step shows your first API key once, with a Copy key button. After that you sign in with that username and password. There is one admin account.

Login bounces back to the login page?

The session cookie is Secure, so 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.

If the server cannot be reached at all, the UI says so and offers Retry instead of a login form.

Pages

Dashboard

The dashboard: an archive field, four statistics cards and the recent activity list
  • An archive field: paste a URL and press Archive. Import links to the import page.
  • Four cards: Total Snapshots, Storage Used (and across how many extractors), Success Rate (last 30 days) and Failed Today (with a link to the snapshot list when there are failures).
  • Pipeline, while snapshots are pending: each one with the extractors that have finished. The page refreshes every 5 seconds until they are done.
  • Recent Activity: the latest 30 finished snapshots, grouped by day: title and address, how many extractors produced output, status and time.

Snapshots

The snapshot list as cards: a screenshot, title, address, status and capture time per snapshot

All snapshots, newest first, 20 per page, as cards (a thumbnail of the first screen, or a frame of the video for a video page, the title, URL, status and capture time) or as rows. Each row shows the URL (with the title and a thumbnail in comfortable rows), a badge per extractor (green when it produced output, dashed and grey when it did not), tags, status and capture time.

  • Filter by URL or title… narrows the rows of the current page.
  • The three buttons next to it switch between Cards (the default), Comfortable rows and Compact rows; the choice is remembered per browser.
  • New Snapshot archives a URL, or links to Import.
  • Check rows or cards (or the header box to select the page) for the bulk bar: Delete the selection, or add a tag to all of it.

Snapshot viewer

The viewer of an archived Wikipedia article

Clicking a snapshot (its card, title or thumbnail) opens it on the whole window, at /#/snapshots/:id: one slim bar on top with Back (or Escape) to the list page you came from, the title, the original URL and the views, and the archived page below it. There is no sidebar and no panel. The buttons on the right show the page full screen (F) and open it in a new tab (still sandboxed). Details (I) is a view like the others.

TabShows
PageThe archived page itself: the SingleFile copy, or the DOM snapshot, in a sandboxed frame that runs no scripts and loads nothing from the network. The page keeps the theme it was archived in, whatever the viewer's system or the app's theme.
ReaderThe article extracted by Readability: title, byline and text, as plain text.
ScreenshotThe full-page screenshot, with zoom from 25 % to 300 % and a download link.
MediaThe video or audio saved by yt-dlp, with its metadata.
FilesDownloads of the HTML, WARC, PDF, SingleFile and DOM snapshot files that exist.
DetailsThe URL (with a copy button), status, capture time, tags (add with +, remove with ×), the extractors that produced output, Archive again, Delete, and the history: every extractor result with its capture time, newest first.

Archive again (signed in only) archives the same address again, in the same theme, and replaces every format with the new run. Use it for a page that changed, or a video a site refused the first time. The button reads Archiving… and is disabled while the snapshot is pending.

The viewer opens on Media when the snapshot has a video, otherwise on Page, then Reader, Screenshot or Files, whichever exists first. Move between views with the arrow keys, Home and End. While the snapshot is pending, the viewer refreshes every 5 seconds.

Search results with the matching words highlighted in each snippet

Full-text search over the extracted text, URL, title and tag names, 20 results per page, with the matching words highlighted. The query goes into the address (?q=) as you type.

  • Filter this page: status, date (last 7, 30 or 90 days), extractor and tag. These filters apply to the results already on the page; they do not search the rest of the archive.
  • Save keeps the query as a named saved search, shown as a chip under the search box. Up to 10 are kept, in your browser (localStorage), not on the server.

Tags

Every tag as a chip. Signed in, you create tags (a name and a colour) and delete them; deleting a tag removes it from every snapshot.

Schedules

Create a schedule from a URL and a cron expression, typed or picked from a preset (hourly, every 6 or 12 hours, daily, weekly). Each row shows the schedule (named when it is a preset or a fixed time, such as Daily at 06:00, otherwise the cron expression), a health badge (On schedule, Overdue or Never run), the last and next run, and expands to the next 5 run times. Delete asks for confirmation inline.

The UI creates URL schedules. A schedule that follows an RSS feed is created with the CLI or the API: see Scheduled archiving.

Import

Choose a format (RSS / Atom feed URL, OPML File, Bookmarks HTML, Plain Text URLs), then give the URL, file or list. The result shows how many URLs were found, queued and skipped. The History tab lists the latest 50 imports. See Bulk import.

Settings and API keys

Settings has four cards: API Keys (a link to the keys page), Change Password (signs out every other session), Appearance (the theme) and Server Info (version, storage path and snapshot count).

API keys creates and revokes keys for the REST API. A new key is shown once, when you create it.

Read-only guest view

With WEBFROST_PUBLIC_READ=true, visitors browse the archive without signing in: Dashboard, Snapshots (with the viewer and its downloads), Search and Tags. The sidebar shows a Read-only marker and a Sign in link, and controls that change the archive are hidden. Opening a page that needs an account leads to the login screen, and back to that page after signing in. See Public read before turning it on.

The sidebar has Dashboard, Snapshots, Schedules and Tags, then Import and Settings. At the top, Search… opens the search palette; at the bottom are Dark mode, Shortcuts, the signed-in user and Sign out. The arrow at the top collapses the sidebar to icons, and the choice is remembered.

Below 1024 px wide, the sidebar becomes a drawer opened with the Menu button in the top bar.

Keyboard shortcuts

KeysAction
Ctrl+K (Cmd+K on a Mac)Open the search palette, from anywhere
/Focus the search or filter field of the page (the palette on pages without one)
Ctrl+B (Cmd+B on a Mac)Show or hide the sidebar (the menu on a phone)
?Show or hide the shortcuts
g then hGo to the Dashboard
g then sGo to Snapshots
g then tGo to Tags
g then iGo to Import (signed in only)
EscapeClose the open dialog or drawer; in the snapshot viewer, go back to the list
F / IIn the snapshot viewer: the page full screen / open Details

The second key of a g sequence must follow within 1 second. /, ?, F, I and the g sequences are off while you type in a field.

In the search palette, type to search, move with ↑ and ↓, press Enter to open the selected snapshot (or the Search page when nothing matches), and Escape to close. It shows up to 8 results; See all results opens the Search page.

Theme

On the first visit the UI uses the instance's default theme (WEBFROST_DEFAULT_THEME, light or dark) and, when that is not set, follows the system's light or dark setting. Dark mode in the sidebar (or Appearance in Settings) switches it, and the choice is saved in the browser. A page archived from the UI is captured in the theme the UI has at that moment (screenshot, PDF and Page view); the CLI, schedules and imports use WEBFROST_COLOR_SCHEME.

What the browser remembers

These live in localStorage, per browser, and never reach the server:

KeyHolds
webfrost-themelight or dark
webfrost-sidebar-collapsedWhether the sidebar is collapsed
webfrost-snapshot-densitygrid (cards), comfortable or compact
webfrost-saved-searchesSaved searches

On this page