Furst/GUIDE.md

Using furst

A practical walkthrough. For what each piece is, see README.md and the per-tool READMEs.

---

Install

./install.sh

That builds the workspace, installs four binaries to ~/.local/bin, writes starter configs, fetches the blocklists, and offers to register furst as your default browser. It is safe to re-run; it never overwrites a config you have edited.

./install.sh --help              # all options
./install.sh --prefix /usr/local/bin
./install.sh --no-default-browser --no-service
./install.sh --uninstall

Then install the handlers the rules refer to:

sudo pacman -S mpv yt-dlp zathura zathura-pdf-mupdf nsxiv surf

Nothing breaks if you skip some — a rule whose command is missing falls through to the next one. furst --list shows which are absent.

---

What happens when you click a link

Nothing to launch. The router is your default browser, and the reader starts itself on demand. Only the proxy runs as a service.

click a link, anywhere
      │
      ▼
   furst  ─── youtube, vimeo, twitch ──► mpv, H.264 forced, no browser at all
      │        *.pdf                  ──► zathura
      │        *.png *.jpg *.gif      ──► nsxiv
      │        meet, figma, netflix   ──► firefox
      │        mailto: magnet:        ──► xdg-email, transmission
      │
      └────── everything else ────────► furst-serve  ──► surf
                                        (reader, minimal HTML)

Every reader page has a bar: refresh · original · browser. Links inside an article stay in the reader. When a page genuinely needs the real web, click browser and it opens in Firefox.

Two URLs worth bookmarking:

http://127.0.0.1:7714/	reader home — your links, feeds, search box
http://furst.proxy/	proxy status — rules, requests, share blocked

---

Making the proxy stick

The proxy is the one piece that must already be running. install.sh sets up a systemd user service for it:

systemctl --user status furst-proxy

Programs find it through the environment, so add this to ~/.zshrc:

eval "$(furst-proxy --env)"

surf, curl, wget and most CLI tools read those variables. Firefox does not — set its proxy manually in Settings → Network Settings → Manual, to 127.0.0.1 port 8228, and tick Also use this proxy for HTTPS.

Check it is working: curl -s -x http://127.0.0.1:8228 http://furst.proxy/ should return the status page.

---

Commands worth knowing

furst --explain <url>      # why did that open there?   ← the one you'll use most
furst --list               # every rule, and what isn't installed

furst-read --text <url>    # article as plain text; pipe it to less
furst-read --html <url>    # article as minimal HTML

furst-serve --status       # is the reader running?
furst-serve --clear        # drop cached pages

furst-proxy --test <host>  # would this host be blocked?
furst-proxy --update       # refresh blocklists (weekly is automatic)

furst --explain is the habit that makes everything else legible:

$ furst --explain https://youtu.be/abc123
scheme  https
host    youtu.be
path    /abc123

-> [video] mpv --ytdl-format=bestvideo[vcodec^=avc1][height<=?720]+... https://youtu.be/abc123
   [reader] furst-serve --open https://youtu.be/abc123
   [default] surf https://youtu.be/abc123

The arrow marks what will actually run. Anything above it that is missing from $PATH is skipped, and marked as such.

---

Fixing things

Extraction is heuristic, so some pages will come out wrong. In order of effort:

An article looks truncated or empty. Click original in the bar, or add &fresh=1 to the URL to bypass the cache.

A site consistently extracts badly. Look at what it kept:

curl -s https://site.example/article | furst-read --stdin --text https://site.example/article

The knobs are POSITIVE and NEGATIVE in furst-read/src/extract.rs — lists of substrings matched against class and id. Adding the site's content wrapper class to POSITIVE usually fixes it. Rebuild and reinstall with ./install.sh.

A site should never go to the reader. Add its host to the heavy rule in ~/.config/furst/rules.toml.

Something legitimate is blocked. Confirm it, then allow it:

furst-proxy --test cdn.example.com
# add to ~/.config/furst/proxy.toml:
#   allow = ["cdn.example.com"]
systemctl --user restart furst-proxy

Allow rules win over everything, at any subdomain depth.

Search says the engine refused. DuckDuckGo rate-limits repeat visitors. Point [search] url in ~/.config/furst/home.toml at a SearXNG instance:

[search]
url = "https://searx.be/search?q={q}"

A page renders blank in the reader. It is probably client-rendered. There is no JavaScript here by design — use browser.

---

Tuning the rules

~/.config/furst/rules.toml is matched top to bottom, first match wins, and a rule whose command is missing falls through to the next.

[[rule]]
name = "my-forum"
hosts = ["forum.example.com"]
run = ["furst-serve", "--open", "{url}"]

[[rule]]
name = "hn-in-terminal"
hosts = ["news.ycombinator.com"]
terminal = true                    # wraps in $TERMINAL -e
run = ["my-tui-client", "{url}"]

host pattern	matches
example.com	the apex and every subdomain
*.example.com	the same thing
=example.com	that exact host only
*	anything

Placeholders: {url} {url_enc} {host} {path} {scheme}. If no argument mentions {url} or {url_enc}, the URL is appended last.

Order matters — put specific rules above the catch-all reader rule at the bottom.

---

Where things live

~/.config/furst/rules.toml	routing rules
~/.config/furst/home.toml	reader home links, feeds, search engine
~/.config/furst/proxy.toml	proxy port, blocklists, block/allow
~/.cache/furst/pages	rendered pages — furst-serve --clear
~/.cache/furst/lists	blocklists, refreshed weekly
~/.local/share/applications/furst.desktop	the default-browser registration

---

Ports

7714	reader (FURST_PORT)
8228	proxy (port in proxy.toml)

Both bind 127.0.0.1 only. Neither is a network service; do not expose them.