🐦 BirdWatchAI Manual Part 3 · Installation Community Feed
Part 3

Installation

Pick the section that matches your platform. The Windows desktop app is a regular Windows installer and is no longer being developed; the server is a Docker container that runs on a Raspberry Pi, Windows, macOS, 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)

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

Tools on your Windows PC

1. Image the SD card from Windows

  1. Plug the SD card into your PC.
  2. Open Raspberry Pi Imager.
  3. Click Choose Device → pick the model you have.
  4. 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.
  5. Click Choose Storage → pick the SD card. Double-check this is the SD card, not your laptop's main drive — Imager will erase it.
  6. 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.
  7. 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

  1. Insert the SD card into the Pi.
  2. Plug in the Ethernet cable, or trust the Wi-Fi you configured above. (You can switch later.)
  3. Plug in power.
  4. 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
Some Pi 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 4.

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.
Optional — reach your Pi from anywhere (Tailscale) The dashboard is only on your home network by default. To open it securely from outside — your phone on cellular, a laptop at work — install Tailscale on the Pi (curl -fsSL https://tailscale.com/install.sh | sh, then sudo tailscale up) and on the devices you'll watch from, then browse to http://<tailscale-ip>:8080. No port-forwarding, and it works even behind CGNAT. Full steps: Part 8 → Remote access with Tailscale.

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

1. Install Docker Desktop

  1. Download from docker.com/products/docker-desktop.
  2. Run the installer. Accept defaults — Use WSL 2 based engine must be checked (default on Windows 10 2004+ and Windows 11).
  3. Restart Windows when prompted.
  4. After login, Docker Desktop auto-launches (whale icon in the system tray). First launch takes 1–2 minutes.
  5. 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:

ScriptWhat it does
birdwatch-start.cmddocker compose up -d
birdwatch-stop.cmddocker compose stop
birdwatch-update.cmddocker compose pull && docker compose up -d — the dashboard's ⬆ Update available button does the same thing one-click.
birdwatch-logs.cmdLive 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:

  1. 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.
  2. 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.

Optional — reach your server from anywhere (Tailscale) To open the dashboard securely from outside your home network, install Tailscale on the Windows host (installer from tailscale.com/download, then sign in from the system tray) and on the devices you'll watch from, then browse to http://<tailscale-ip>:8080. No port-forwarding required. Full steps: Part 8 → Remote access with Tailscale.

macOS + Docker server

The server edition runs on a Mac under Docker Desktop — Intel or Apple Silicon, both native. Pick this if you already have a Mac that stays on all day. Total time: ~20–30 minutes, mostly waiting for Docker Desktop to download.

What you need

1. Install Docker Desktop

You don’t need a Docker account The installer’s “sign in / sign up” prompts are all optional — skip them. BirdWatchAI’s image pulls from a public registry that needs no login.
  1. Download the right build from docker.com/products/docker-desktop: Apple Silicon (M1/M2/M3/M4) or Intel chip. Not sure which you have? Apple menu → About This Mac — “Chip” reads either “Apple M…” or “Intel Core…”.
  2. Open the downloaded .dmg, drag Docker into Applications, then launch it from Launchpad. First launch takes 1–2 minutes — accept the privileged-helper prompt when it asks for your password.
  3. Open Docker Desktop → Settings → General and tick Start Docker Desktop when you log in. This is what makes the BirdWatch stack come back automatically after a reboot.
  4. Leave Use Rosetta for x86_64/amd64 emulation (Apple Silicon only) at its default. The BirdWatchAI image is native arm64, so emulation never kicks in.
  5. Skip the optional sign-in and tutorial prompts.

2. Confirm Git is available

Open Terminal (Cmd+Space → “Terminal”) and run:

git --version

If it prints a version, you’re set. If macOS offers to install the Command Line Tools instead, click Install and wait ~5 minutes — that brings in Git plus a few other Unix utilities.

If you’d rather not install the Command Line Tools, download the release repo as a ZIP and extract it into your home folder. Trade-off: you’ll have to re-download the zip when docker-compose.yml changes (every few months).

3. Clone the release repo

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

(If you used the zip route, cd to wherever you extracted it instead.)

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. If only one appears, the compose file predates the Watchtower sidecar — run git pull, then docker compose up -d again.

5. Open the dashboard

http://localhost:8080

The first-time setup wizard greets you — camera, location, notifications, license. Part 4 walks through it.

6. Verify auto-start on reboot

The default setup brings everything back without you doing anything: Docker Desktop auto-starts from step 1.3, and the containers have restart: unless-stopped. Test it by rebooting, logging back in, waiting ~30 seconds for Docker, then opening http://localhost:8080.

Daily-ops helper scripts

The repo ships a few .command files at the root that wrap the common docker compose operations. Double-click any of them in Finder, or run them from a Terminal in the repo folder:

ScriptWhat it does
birdwatch-start.commanddocker compose up -d
birdwatch-stop.commanddocker compose stop (containers stay defined, just stopped)
birdwatch-update.commanddocker compose pull && docker compose up -d — the dashboard’s ⬆ Update available button does the same thing one-click.
birdwatch-logs.commandLive log tail. Ctrl+C to stop tailing (the container keeps running).
First time you run a .command file Gatekeeper may refuse it — “…cannot be opened because it is from an unidentified developer”. Right-click the file in Finder → Open → Open, and macOS remembers your approval thereafter. Or chmod +x birdwatch-*.command from Terminal.

Hands-off mode (no login required)

Docker Desktop on macOS needs a logged-in user session — the Linux VM runs inside the GUI session, not as a system daemon. If you want truly headless operation (the Mac boots, nobody logs in, BirdWatch is up):

  1. Auto-login: System Settings → Users & Groups → Automatically log in as… → pick the BirdWatch user. Docker Desktop’s “Start when I log in” handles the rest. Trade-off: anyone with physical access has that account’s permissions.
  2. colima — Docker without Docker Desktop, able to run as a launchd service with no GUI session. Much more involved and out of scope here; search “colima docker macos headless” for the standard recipe.

For a dedicated always-on server, a Raspberry Pi is genuinely simpler — headless is its default. See Raspberry Pi server above.

Two macOS-only gotchas worth knowing up front

“Docker.app is damaged” on Apple Silicon — some Macs need Rosetta 2 even for Apple-Silicon-native apps. Run softwareupdate --install-rosetta --agree-to-license in Terminal, then relaunch Docker Desktop.

Detection timestamps off by hours — containers run inside Docker Desktop’s Linux VM, which can interpose its own timezone over the /etc/localtime mount the compose file ships with. Check with docker exec birdwatch date; if it disagrees with your wall clock, add TZ: America/New_York (or your zone) under the birdwatch: service’s environment: block in docker-compose.yml, then run docker compose up -d --force-recreate birdwatch.

Optional — reach your server from anywhere (Tailscale) To open the dashboard securely from outside your home network, install Tailscale on the Mac (from tailscale.com/download or the Mac App Store, then sign in from the menu bar) and on the devices you’ll watch from, then browse to http://<tailscale-ip>:8080. No port-forwarding required. Full steps: Part 8 → Remote access with Tailscale.

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). After the trial you'll need a license key — a one-time purchase, no subscription.

FAQ

Q: Do I have to pay to try BirdWatchAI?
No. A free trial starts automatically — 14 days on the desktop app, 30 days on the server. After that it's a one-time license key, not a subscription.

One thing the server trial doesn't include

Everything runs locally during the trial — detection, notifications, snapshots, clips, statistics and badges. The exception is publishing your sightings to the shared community feed at birdwatchai.com, which needs an activated license, because it stores your photos and clips on our servers under a community identity.

Nothing is lost by trying first. Sightings recorded during the trial stay in your local history, and once you activate, 📤 Share all unshared on the History page pushes the whole backlog to the community in one go. If you switch sharing on before activating, the Community settings page says so rather than leaving you with a ticked box and an empty feed.

What you'll see on first run (desktop)

Activating a license

  1. Open the License Activation dialog (desktop: appears automatically; server: Settings → License).
  2. Paste your license key.
  3. 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.