Documentation

Installation

Requirements

Installation requires Rust/cargo to build the binary.

Install via systemd (Linux)

Installs the binary to /usr/local/bin, configures a systemd service running under your user account, and stores data in ~/.local/share/bigbrowser.

The script generates a config file with a secure API key and default settings.

Supports –port, –bind, –data-dir, and –skip-build overrides. See the script header for details.

git clone https://git.bigbrowser.tech bigbrowser
cd bigbrowser
sudo ./scripts/install.sh

Building from source

git clone https://git.bigbrowser.tech bigbrowser
cd bigbrowser
cargo build --release

The binary will be at ./target/release/bigbrowser.

Generate an API key

The API key is used by the browser extension.

openssl rand -hex 32

Create a config file

Create bigbrowser.toml:

# Required: API key for the browser extension
api_key = "<your-api-key>"

# Server address (default: 127.0.0.1:3000)
addr = "127.0.0.1:3000"

# SQLite database path (default: bigbrowser.db)
# database_url = "bigbrowser.db"

# Web UI authentication (disabled by default, use --hash-admin-password to generate the hash)
# authenticated = true
# password_hash = "<generated-hash>"

Settings can also be set via environment variables with the BIGBROWSER_ prefix (e.g. BIGBROWSER_API_KEY).

Run the server

Run from the directory containing bigbrowser.toml:

bigbrowser

Visit http://127.0.0.1:3000 to verify the server is running.

Install the browser extension

Download the browser extension and configure it:

  • Instance URL: http://127.0.0.1:3000 (or your server address)
  • API key: the key from your config
  • Device name: pick an identifier for this browser, e.g. desktop

Configuration

Web UI authentication

By default, the web UI has no authentication. To enable it:

First, generate a password hash:

bigbrowser --hash-admin-password

Then enable authentication in the config and set the password_hash:

authenticated = true
password_hash = "<generated-hash>"

Concepts

Visits

Everytime you visit/navigate to a page, a visit is recorded and the context of the page is indexed.

Index

The search index is composed of the latest visits of every visited page.

Trails

Trails capture the navigation sequence within a browsing session, from a starting page through each link followed. They can be visualized as a graph.

Bookmarks

You can bookmark pages via the web extension, bookmarks are totally separate from the browser’s built-in bookmarks.

Bookmarks can be searched by prefixing search queries with a *.

* query

Snapshots

Captured snapshots provide a fully offline version of a visited web page, with all resources inlined.

Search Query Syntax

  • Searches across page content, titles, URLs, and code blocks
  • Title matches are boosted (higher ranking)
  • Exact URL matches are included in results
  • Multiple terms use OR logic by default (use + for AND)
  • Words are automatically stemmed (e.g., “running” matches “run”, “runs”, “ran”)
chocolate recipes

Operators

Required terms

+recipe cake chocolate

Only matches pages containing “recipe”

The + operator can be used to make AND logic queries:

+recipe +cake

Excluded terms

recipe -baking

Matches pages with “recipe” but not “baking”

Phrase search:

"getting started"

Matches the exact phrase

Wildcards

develop*

Matches “developer”, “development”, “developing”, etc.

Filters

Bookmark search

* tutorial

Search bookmarked pages matching “tutorial”

Fuzzy search

~ recieve

Will match “receive” despite the typo

Domain filter

domain:example.com tutorial

Search only within example.com

Date filters

tutorial @today          # Today's visits
tutorial @7d             # Last 7 days
tutorial @2w             # Last 2 weeks
tutorial @3m             # Last 3 months
tutorial @1y             # Last year

Combining Filters

You can combine multiple filters:

* domain:docs.example.com +tutorial @30d

Searches bookmarked pages from docs.example.com containing “tutorial” from the last 30 days

Domain Filters

Domain filters let you control which websites bigbrowser records and indexes.

Filter Modes

Skip Content

  • Records visits to the URL
  • Skips content extraction and indexing
  • Useful for sites you visit frequently but don’t need to search (webmail, internal tools)

Exclude

  • Does not record visits at all
  • Useful for sensitive sites like banking or personal accounts

Pattern Types

Exact Match

example.com
  • Matches: example.com only
  • Does not match: www.example.com or sub.example.com

Domain + Subdomains

.example.com
  • Matches: example.com, www.example.com, api.example.com, etc.
  • Use this to filter an entire domain including all subdomains

Examples

Skip webmail content indexing:

.fastmail.com    (skip content)

Visits are recorded but content isn’t extracted or searchable.

Exclude sensitive sites:

.bank.com        (exclude)
intranet.work    (exclude)

No visits recorded at all.

Filter specific subdomain:

mail.google.com  (skip content)

Filters only the mail subdomain, allows other Google services.

Managing Filters

Filters can be managed from the extension popup and in the UI’s settings section.