> ## Documentation Index
> Fetch the complete documentation index at: https://docs.birdbrain.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and first capture

> Install Birdbrain and the companion Chrome extension, take your first capture, and keep the app updated.

Birdbrain is an open source web investigation and capture tool. The Chrome extension captures
a page when you ask it to. The desktop app organizes those captures into cases you can
annotate, search, and export, with hashes, timestamps, and audit manifests attached.

**This is beta software.** Expect rough edges, and export anything you can't afford to
lose (see [Known limitations](#known-limitations)).

[Download Birdbrain](/docs/download) has the platform table, where security advisories appear,
and what the project wants reported.

## Your data and your archives

Use synthetic or low-stakes material where you can. Real project data is tolerated, not
endorsed. It goes in at your own risk, and [Updating](#updating) describes what backs
that risk and where the limits are.

* Birdbrain does **not** encrypt the database or capture files at rest. Confidentiality of
  the live store relies on your operating system's full-disk encryption (BitLocker, LUKS).
* The project has no channel for sending a `.birdbrain` case archive to the maintainer, and a bug
  report never needs one. See [Reporting a problem](#reporting-a-problem) for what a
  diagnostic bundle does and doesn't contain.

## Install the app

Releases live at
[github.com/thebristolsound/birdbrain/releases](https://github.com/thebristolsound/birdbrain/releases),
the public repository that also holds the source code.
You need no GitHub account to download a build. Take the current release and the
file for your platform; [Download Birdbrain](/docs/download) says which file that is. Once
it's installed, **Settings → About** shows the version you're running.

### Windows

1. Download `Birdbrain-Setup-<version>.exe` and run it.
2. Windows SmartScreen will warn about an unrecognized app (our builds aren't
   code-signed yet). Click **More info → Run anyway**.
3. The installer finishes and launches Birdbrain.

### Ubuntu

The AppImage is the primary Linux build. It needs no install step, and updates replace it
in place:

```bash theme={null}
chmod +x Birdbrain-<version>.AppImage
sudo apt install libfuse2t64
./Birdbrain-<version>.AppImage
```

AppImages need FUSE 2, and Ubuntu stopped installing it by default. Without it the app
does not start, and the error reads like a broken download rather than a missing
library. On 22.04 and earlier the package is called `libfuse2` instead of `libfuse2t64`;
if `apt` cannot find one, use the other.

If you would rather not install anything, this runs the same build without FUSE:

```bash theme={null}
./Birdbrain-<version>.AppImage --appimage-extract-and-run
```

The alternative is the `.deb`:

```bash theme={null}
sudo apt install ./birdbrain_<version>_amd64.deb
```

Then launch **Birdbrain** from your app launcher, or run `birdbrain` in a terminal. The
`.deb` gets best-effort support, and installing an update on it needs your system
password. See [Updating](#updating).

### macOS

macOS support is experimental, and needs macOS 13 or later. The build is unsigned, not
notarized, and not launch-tested before it is published. A release whose macOS build fails
still ships, without it.

1. Download `Birdbrain-<version>-arm64.dmg` on Apple Silicon, or `Birdbrain-<version>.dmg` on
   an Intel Mac. If the release lists neither file, it has no macOS build.
2. Open the disk image and drag **Birdbrain** to **Applications**.
3. The build is not signed or notarized, so macOS blocks the first launch, and may say the app
   is "damaged and can't be opened". That message is the download quarantine, not a corrupt
   file. Clear the quarantine once in Terminal, then open Birdbrain as usual:

   ```bash theme={null}
   xattr -dr com.apple.quarantine /Applications/Birdbrain.app
   ```

The app does not install updates on macOS. To update, download the new disk image from the
releases page and repeat the steps.

## Install the Chrome extension

The extension isn't on the Chrome Web Store yet, so it loads in developer mode. The
extension card on the Birdbrain dashboard has a **Setup Guide** that walks through the steps
and an **Open extension folder** button that opens the right folder for you. If a case is
open, click the house icon (**Home**) at the top of the left sidebar to reach the dashboard.

The short version:

1. Open `chrome://extensions` in Chrome.
2. Switch on **Developer mode** (toggle in the top-right corner).
3. On the Birdbrain dashboard, click **Open extension folder**. This opens the copy of the
   extension that belongs to the Birdbrain build you just installed. Always load this one, not
   a copy downloaded or unzipped from somewhere else, so the extension and the desktop app
   stay the same version.
4. Click **Load unpacked** and select that folder, the one containing `manifest.json`.
5. The Birdbrain icon appears in your Chrome toolbar. Back in the app, a green
   **Connected** badge appears in the top bar.

Chrome keeps running the copy it loaded until you reload it, so an app update needs one
more step from you (see [Updating](#updating)).

The desktop app must be running for the extension to work. The extension sends captures only
to the app, over `127.0.0.1:19845`. The app itself contacts outside services. For example, it
sends each capture's hash to a timestamp authority unless you switch off
**Settings → Operator → Trusted timestamping**. The
[network egress section](https://github.com/thebristolsound/birdbrain/blob/main/SECURITY.md#network-egress)
of the security policy describes them.

## Your first capture

1. In the app, go to the dashboard and click **Start New Case**. Name the
   case anything.
2. Browse to any page in Chrome.
3. Click the Birdbrain toolbar icon, then click **Capture now**. You can also right-click the
   page and choose **Birdbrain → Capture Full Page**.
4. The capture appears in the app under your case's **Captures** tab, with
   provenance details (hashes, timestamps) attached.

From there, explore: annotate screenshots, add notes and tags, define selectors, search the
text of every capture in the case from the search box in the top bar (`Ctrl F`), and export the
case when you're done.

## Updating

**Settings → Updates → Check automatically** is on out of the box, and while it is on
Birdbrain checks for updates by itself: shortly after launch, then every few hours while it's
running. Anything it finds downloads by itself too. Because you're on a prerelease build, it
starts on the **Beta** channel, so new betas count as updates.

Switch **Check automatically** off and no background check runs at all. An update will never
surface on its own, and opening the Updates panel won't go looking for one either. You have to
click **Settings → Updates → Check for updates** yourself, then click **Download** on whatever
it turns up. That button works whatever the toggle says. Nothing ever restarts on its own. A
downloaded update installs when you click **Restart to update**, or quietly at your next quit.

**The `.deb` is the exception.** Updates download the same way, but installing one runs
`dpkg` behind a system password prompt, so it never installs at quit, only when you click
**Restart to update** and enter your password. That's why the AppImage is the primary
Ubuntu build, and why on the `.deb` it is worth watching the releases page.

**macOS is the other exception.** Nothing downloads or installs by itself, and there is no
**Download** button. Update by hand as described in [macOS](#macos).

You can always install by hand instead: download from the releases page and install over the
old version. Your data survives either way. It lives in your user data directory, separate
from the app.

After every app update, also reload the extension: `chrome://extensions` → click the
reload icon on the Birdbrain card. Chrome does not pick up changed extension files on
its own, so until you reload, the extension is still the previous version, and captures it
makes may not match what the app expects.

The folder **Open extension folder** opens is a copy the app keeps in its user data
directory and refreshes whenever the app version changes. The path stays the same across
updates, so a card you loaded from it keeps working after a reload. If you installed
Birdbrain before that folder moved, though, your card still points at the old app install
folder. The dashboard shows **Open extension folder** only while no extension is connected, so
if the old card still connects, the button is not there. Open the folder yourself instead. It
is the `extension` folder in Birdbrain's user data directory. To find that directory, go to
**Settings → Diagnostics → Log** and click **Reveal log file**. Your file manager shows the log
file inside a `logs` folder. Go up one level, and the `extension` folder is beside `logs`.
**Load unpacked** that `extension` folder, then remove the older Birdbrain entry pointing
somewhere else. Leave both loaded and Chrome runs the stale one.

If you put real project data in, this is what stands behind it, and the limits below are
why we recommend synthetic or low-stakes material instead.

When a new version needs to upgrade the case database, Birdbrain copies the
database first, into a `db-snapshots` folder next to it in your user data
directory, and only then applies the upgrade. If the copy fails, the
upgrade does not run at all. You get an error saying so, and your data stays
exactly as it was. Birdbrain keeps three snapshots, spread across the schema
versions present rather than newest-first, so a run of failed upgrades does not
immediately fill the folder with copies of the same half-migrated state. It
prunes older ones, so copy any snapshot you want to keep out of that
folder. You can put one back from **Settings → Database → Utilities →
Pre-Migration Snapshots**.

**Restoring a snapshot cannot be undone.** The copy overwrites your current
database, and Birdbrain does not keep the old one anywhere. Birdbrain provides no undo
button and no aside file to rename back. If you might want the current state
again, take a copy first with **Settings → Database → Utilities → Backup
Database**, which writes the database wherever you choose, and export anything
recorded since the snapshot that matters. Export is the only backup that
includes capture files; **Backup Database** copies the database alone.

**A failed restore is not a guarantee either.** If the restore fails, treat the
result as unknown. A restore error does not prove the previous database is still
intact, and case data can end up inconsistent. Check the case before carrying
on, or restore a backup. The exception is a refusal whose message ends "Nothing was
changed.", such as Restore from File turning down a file that is not a Birdbrain
database: Birdbrain stopped before replacing anything, and your database stays as it was.

Two more things a restore does not do, both worth knowing before you click it:

* **It does not take you back to the old schema.** Birdbrain re-opens the
  restored copy and applies the same upgrade to it again, so you end up on the
  current schema holding the older records. That is what you want when an upgrade
  died half-way through, but it is not a downgrade.
* **It only replaces the database.** Capture files, screenshots and MHTML stay on
  disk. Anything recorded after the snapshot disappears from the app while its
  files remain, unreferenced.

## Known limitations

* **Unsigned builds.** SmartScreen warnings on Windows are expected.
* **Updates never restart the app for you.** Installing is your click, or your next quit on
  Windows and the AppImage. The `.deb` never installs at quit; it's always your click plus
  your system password.
* **The extension is sideloaded.** Chrome may occasionally nag about developer-mode
  extensions.
* **One running copy at a time.** The extension reaches the app on `127.0.0.1:19845`, and only
  one program can hold that port. Launching Birdbrain while it is already running brings the
  copy you have to the front instead of starting a second one, so you can't collide with
  yourself. If some other program on your machine is holding that port, Birdbrain refuses to
  start rather than open a window that can't receive captures, and names the port in the error
  it shows. Close whatever is using it, then start Birdbrain again.
* **Local-only data.** Captures live only on your machine, and export is the only backup that
  includes capture files. Export anything you can't lose before updating or uninstalling.
* **Deleting a capture is not redacting it.** The files go, but the case manifest is
  append-only: the deleted capture's URL, capture time and hashes stay in it permanently and
  ship in every export that includes the audit trail. If a URL is sensitive, deleting the
  capture does not take it out of the evidence package. Treat a case as contaminated by
  anything you captured into it.
* **Chrome/Chromium only.** No Firefox or Safari extension yet.
* **macOS is experimental.** The build is unsigned and not notarized, and the app does not
  install updates on macOS.
* **"Verified" is not a live check.** Capture details shows the result of the last
  verification run, not the state of the file right now. Click **Re-verify** to get a
  current statement.

## Reporting a problem

Report what you find as an
[issue on the Birdbrain repository](https://github.com/thebristolsound/birdbrain/issues). It is
public, and no response target is stated.

If you find a security vulnerability, do not open a public issue. Report it privately through
the repository's [Security tab](https://github.com/thebristolsound/birdbrain/security),
as its
[security policy](https://github.com/thebristolsound/birdbrain/blob/main/SECURITY.md#reporting-a-vulnerability)
describes.

Birdbrain keeps a local diagnostic log and can bundle it into a report for you:

1. Go to **Settings → Diagnostics → Report a problem**.
2. Fill in what you did, what you expected, and what happened.
3. Click **Create report**. Pick where to save it. Birdbrain writes a `.zip`
   there and opens the folder for you.

The zip saves **only to your computer**. Birdbrain never uploads it or sends
it anywhere. Attach it to the issue yourself, the same way you'd attach any
other file. It contains:

* the diagnostic log, plus the previous log file if the log has rotated
* what you typed in the report form, the time you made the report, and, if you opened it with
  **Report this** on an error message, that error's log entry ID
* your installation identifier
* a record of your last 20 app launches: a random ID for each, when it started and ended,
  whether it closed cleanly, whether its crash prompt was shown, and the version, platform and
  install format it ran
* a snapshot of the app's state: the Birdbrain, Electron, Chrome and Node versions, your
  operating system, processor type and install format, how long the app has been running, each
  app process's type, ID, CPU and memory use, how far the app is lagging now and at worst in the
  last minute, recent freezes and named slow operations with their times and durations, your
  database's schema version and the newest one this build supports, how many cases, captures,
  notes, selectors and extracted data items you have, the size of your case database files,
  whether your signing key is stored encrypted, and whether trusted timestamping is on

It does **not** contain your captures, your case database, or your settings file. That is why no
bug report needs a case archive, and there is no channel for sending one.

Birdbrain writes the same installation identifier into the manifest entry of every capture you
take, so attaching the bundle to a public issue links that issue to the evidence packages you
export.

If Birdbrain closed unexpectedly last time (a crash, a forced quit, a power loss),
it will offer to create a report automatically the next time you open it. Click
**Create a report** on that prompt to file it the same way.

You can also open **Settings → Diagnostics → Log** any time to see recent log
entries in the app itself, filterable by level, with a button to reveal the raw
log file on disk.

### What to put in the issue

1. **Version.** The build you're running. **Settings → About** shows it, **Settings →
   Diagnostics** repeats it, and it's in the installer filename too.
2. **OS.** For example Windows 11 or Ubuntu 24.04.
3. **What you did.** Steps, in order.
4. **What you expected.**
5. **What happened.** Plus a screenshot if it's visual.

Attach a diagnostic bundle alongside your description. Good repro steps plus a report
bundle is the single most useful thing you can give us. Small, frequent reports beat one
big write-up.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.