Part 2

Installation

Pick the section that matches your platform. The Windows desktop app is a regular Windows installer; the server is a Docker container that runs on a Raspberry Pi, Windows, or any x86_64 Linux box.

Not sure which edition to install? See Part 1 → Desktop vs. Server. Short version: if you already have a Windows PC that's on all day, get the desktop app; if you want low-power always-on or remote access, get the server.

Windows desktop app

The desktop app is a one-click installer for Windows 10 or 11 (64-bit).

Option A — The installer (recommended)

Download BirdWatchAI_Setup_2.1.2.0.exe from www.birdwatchai.com.
Run it. If .NET 8 Desktop Runtime is missing, the installer offers to open the download page — install .NET, then re-run the setup.
Accept the license agreement.
Choose a destination. The default is C:\Users\<you>\AppData\Local\BirdWatch AI.
Optionally tick Create a desktop icon and / or Start BirdWatch AI when Windows starts (both off by default).
Finish, and optionally launch the app immediately.

The installer adds Start-menu shortcuts for the app and its help, and creates the data folders (Data\Snapshots, Data\Videos, Data\Logs, etc.). On first launch you'll go through the setup wizard.

Option B — Portable ZIP

If you'd rather not run an installer, download the ZIP, extract it anywhere, and run BirdWatchAI.exe directly. All settings, snapshots, and history live in a Data subfolder beside the program — the app is effectively portable.

Running more than one camera? BirdWatchAI allows one running copy per install folder. To monitor several feeders at once, install (or copy the portable build) into separate folders — e.g. BirdWatchAI-Backyard\ and BirdWatchAI-FrontPorch\ — and run each. Each folder keeps its own settings, history, and snapshots.

Uninstalling

Use Windows Add or remove programs. The uninstaller asks whether to also delete your user data (snapshots, videos, logs, settings). Choose No to keep your bird photos and history for next time.

Raspberry Pi server (from a blank SD card)

A linear walkthrough that takes a brand-new Raspberry Pi from "still in the box" to "running BirdWatchAI and watching your feeder." Total time: about 45 minutes, mostly waiting for things to flash, boot, or download. ~15 minutes of which is actually hands-on.

What you need

Hardware

Raspberry Pi 4 (4 GB or 8 GB) or Pi 5. The 2 GB variants technically work but make ONNX classification slow.
microSD card, 32 GB+, class A2 (e.g. SanDisk Extreme, Samsung Pro Endurance). Cheap cards die fast under database write load — get a decent one.
Official USB-C power supply for the Pi 4 / 5. Underpowered supplies cause random lockups under camera + AI load.
Network: Ethernet to your router, or Wi-Fi credentials. Wired is more reliable for an always-on camera.
A camera: any RTSP-capable IP camera (Tapo, Reolink, Amcrest, etc.). The wizard asks for the URL later.

Tools on your Windows PC

A USB SD-card reader.
Raspberry Pi Imager — free, ~50 MB download from raspberrypi.com.

1. Image the SD card from Windows

Plug the SD card into your PC.
Open Raspberry Pi Imager.
Click Choose Device → pick the model you have (Pi 4 or Pi 5).
Click Choose OS → Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit). "Lite" matters — the full desktop OS wastes RAM the server could use.
Click Choose Storage → pick the SD card. Double-check this is the SD card, not your laptop's main drive — Imager will erase it.
Click Next. When it asks "Would you like to apply OS customisation settings?" → click Edit Settings.
General tab:
- Set hostname: birdwatch (or anything — this becomes how you reach the Pi: birdwatch.local).
- Set username and password: pick something memorable; you'll SSH in with these. Don't leave the default username — pi is well-known.
- Configure wireless LAN: tick this if you're using Wi-Fi. Enter your SSID + password. Pick your Wi-Fi country.
- Set locale settings: time zone + keyboard layout. Don't skip the time zone — Pi OS defaults to Etc/UTC if you leave it blank, which makes every dashboard timestamp read several hours off from your wall clock.
Services tab:
- Enable SSH → Use password authentication.
Click Save.
Back at the prompt, click Yes to apply customisations, Yes to confirm erase. Wait ~5 minutes for write + verify. Eject the SD card when it finishes.

2. Boot the Pi

Insert the SD card into the Pi.
Plug in the Ethernet cable, or trust the Wi-Fi you configured above. (You can switch later.)
Plug in power.
Wait ~2 minutes. First boot expands the filesystem and applies your customisations. The activity LED blinks rapidly during this and settles when ready.

3. SSH in from Windows

From PowerShell or Windows Terminal:

ssh birdwatch@birdwatch.local

(Replace birdwatch on both sides with your chosen username + hostname.) Accept the fingerprint, enter your password.

If .local doesn't resolve Some Windows configs disable mDNS. Find the Pi's IP in your router's admin page (look for the hostname you set), then ssh birdwatch@<that IP>.

Wi-Fi didn't come up on first boot?

Pi Imager's Wi-Fi pre-config doesn't always survive Bookworm's switch to NetworkManager. The reliable recovery: plug in Ethernet temporarily, SSH in over the wire, then run sudo nmtui. In the menu: Activate a connection → pick your SSID → enter the password → OK → Back → Quit. Verify with nmcli device status — wlan0 should show connected.

If nmcli device wifi list returns nothing (no networks visible), the Wi-Fi country code isn't set:

sudo raspi-config nonint do_wifi_country US   # or your country code
sudo nmcli device wifi list                   # should now list networks

Pi 5 radios refuse to scan until a country code is registered.

4. Update the OS and install git

sudo apt update && sudo apt upgrade -y && sudo apt install -y git

Takes 2–5 minutes depending on how stale the image was. Raspberry Pi OS Lite doesn't ship with git — we install it now so the next step works.

5. Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo reboot

The reboot is what lets you run docker without sudo. Faster than logging out and back in.

The SSH session will drop. Wait ~30 s and reconnect:

ssh birdwatch@birdwatch.local

6. Install BirdWatchAI Server

git clone https://github.com/JoeBarraco/birdwatchai-server-releases.git ~/birdwatch
cd ~/birdwatch
docker compose up -d

The first docker compose up -d pulls the ~600 MB image from GitHub Container Registry. On Wi-Fi that's typically 1–5 minutes; on fast Ethernet, well under a minute. When it's done:

docker ps

Should list a container named birdwatch with status Up X seconds.

7. Open the dashboard

In your browser, on the same network:

http://birdwatch.local:8080

(Or http://<pi-ip>:8080 if .local doesn't resolve.) You'll land on the first-time setup wizard — see Part 3.

What just happened

Your detection history + config live at ~/birdwatch/data/ on the Pi. Back this folder up if you care about the data — losing it means losing every detection and your settings.
The container has restart: unless-stopped, so it auto-starts on boot and recovers from crashes. No need to start it manually after a reboot.
The dashboard polls this repo's releases every 30 minutes. When a newer release publishes, the ⬆ Update available button appears on the Engine status card.

Windows + Docker server

The server edition also runs on Windows under Docker Desktop. Pick this if you'd rather drive BirdWatchAI from a web dashboard than the WinForms app, or if you want to access it remotely from your phone over Tailscale / a VPN. Total time: ~30–45 minutes, mostly waiting for Docker Desktop to download.

What you need

Windows 10 64-bit (build 1903+) or Windows 11
8 GB RAM minimum, 16 GB recommended (Docker Desktop is RAM-hungry)
20 GB free disk space (Docker image + WSL2 storage)
Wired Ethernet recommended for reliability
An RTSP-capable IP camera. (The wired Pi camera path doesn't apply on Windows.)

1. Install Docker Desktop

Download from docker.com/products/docker-desktop.
Run the installer. Accept defaults — Use WSL 2 based engine must be checked (default on Windows 10 2004+ and Windows 11).
Restart Windows when prompted.
After login, Docker Desktop auto-launches (whale icon in the system tray). First launch takes 1–2 minutes.
Open Docker Desktop → Settings → General and verify Start Docker Desktop when you sign in is ticked. This is what makes the BirdWatch stack come back automatically after a reboot.

2. Install Git for Windows (recommended)

Download from git-scm.com/download/win and accept all defaults.

If you'd rather not install Git, download the BirdWatchAI release repo as a ZIP and extract it to C:\Users\<you>\BirdWatch\. Trade-off: you'll have to re-download the zip when docker-compose.yml changes (every few months).

3. Clone the release repo

Open PowerShell or Command Prompt:

cd %USERPROFILE%
git clone https://github.com/JoeBarraco/birdwatchai-server-releases.git BirdWatch
cd BirdWatch

4. Start the stack

docker compose up -d

First run downloads the ~600 MB BirdWatchAI image plus the small Watchtower image. Expect 1–5 minutes on typical home internet. Then:

docker ps

You should see two containers: birdwatch and birdwatch-watchtower.

5. Open the dashboard

http://localhost:8080

6. Verify auto-start on boot

The default setup brings everything back without you doing anything: Docker Desktop auto-starts from step 1.5; the containers have restart: unless-stopped. Test with a reboot.

Daily-ops helper scripts

The repo ships a few .cmd files at the root that wrap common docker compose operations. Double-click any of them, or run from a shell:

Script	What it does
`birdwatch-start.cmd`	`docker compose up -d`
`birdwatch-stop.cmd`	`docker compose stop`
`birdwatch-update.cmd`	`docker compose pull && docker compose up -d` — the dashboard's ⬆ Update available button does the same thing one-click.
`birdwatch-logs.cmd`	Live log tail. `Ctrl`+`C` to stop tailing (container keeps running).

Optional: Scheduled Task for extra-reliable startup

The default flow above is enough for most installs. Add a Scheduled Task if you want belt-and-suspenders — something that polls for Docker to become ready and re-runs docker compose up -d if for any reason the auto-restart didn't fire.

Open PowerShell as Administrator, from %USERPROFILE%\BirdWatch:

.\setup-scheduled-task.ps1

That script registers a task named BirdWatchAI Server Autostart that runs birdwatch-start.cmd at user login, after waiting up to 5 minutes for Docker Desktop to come up. Idempotent. Remove with:

Unregister-ScheduledTask -TaskName "BirdWatchAI Server Autostart" -Confirm:$false

Hands-off mode (no Windows login required)

Docker Desktop requires a logged-in Windows session — the engine doesn't run as a system service. If you want truly headless operation:

Auto-login: configure Windows to auto-log into a dedicated account at boot (netplwiz → uncheck "Users must enter a username and password…"). Docker Desktop's "Start when I sign in" then handles the rest. Trade-off: anyone with physical access has that account's permissions. Acceptable for a dedicated homelab box, not a shared PC.
Docker without Docker Desktop: install the Docker engine directly on WSL2. Much more involved and out of scope here — search "Docker on WSL2 without Docker Desktop".

For a dedicated Pi or x86 Linux host, headless is the default — that's why the Pi instructions don't bother with this.

Other Linux (x86_64)

Any x86_64 Linux box with Docker works. The instructions are the same as on a Pi from step 5 onward:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in so the docker permission applies.

git clone https://github.com/JoeBarraco/birdwatchai-server-releases.git ~/birdwatch
cd ~/birdwatch
docker compose up -d

Then open http://<your-host-ip>:8080.

The same things apply: data lives in ~/birdwatch/data/, the container restarts automatically, the dashboard polls for updates every 30 min.

Licensing & the free trial

BirdWatchAI includes a 14-day free trial (desktop) / 30-day free trial (server) with full functionality. After the trial you'll need a license key — a one-time purchase, no subscription.

What you'll see on first run (desktop)

If you've never started a trial: a welcome dialog asks whether to begin your 14-day free trial. Choose Yes, or enter a license key instead.
While trialing: the title bar shows Trial (N days remaining), and a small watermark appears on saved video overlays.
When the trial expires: you'll be prompted to enter a license key; without a valid key the app will close.

Activating a license

Open the License Activation dialog (desktop: appears automatically; server: Settings → License).
Paste your license key.
Click Activate. On success you'll see "Licensed to: <your name>" and the green ✓ Licensed status.

A license may be perpetual (no expiry) or time-limited (shows days remaining). You can Deactivate a license on one machine to move it to another. The license is saved as license.key in the program / data folder.

About the trial clock The trial start date is stored in two protected locations so the trial can't be reset by deleting a single file. The license key itself is cryptographically signed, so keys cannot be forged or edited.

The full pricing and license details — including bundled camera kits ("The Full Nest") — live on the pricing section of the home page.