Set up Chirp

A station in the yard, a server that keeps everything, and the app to explore it. Most people finish in an afternoon.

Pick your path

1 · What you need for a station

Full hardware notes: chirp-device/SETUP.md ↗.

2 · Prepare the Pi

1. Install Raspberry Pi Imager ↗ on your computer and flash Raspberry Pi OS (64-bit) to the card.
2. In Imager's settings, set a hostname (e.g. chirppi), a username and password, your Wi-Fi and turn on SSH. This is the simplest way to get the Pi online.
3. Put the card in the Pi, plug in the microphone, then power it on. Give it two minutes.
4. From your computer: ssh [email protected]
5. Update it:

   sudo apt update && sudo apt full-upgrade -y && sudo reboot

3 · Install the station software

1. Download Chirp:

   sudo apt install -y git
   git clone https://github.com/joshsalvi/chirp.git
   cd chirp/chirp-device

2. Run the installer. It sets up Python, the audio libraries, BirdNET and the chirp-device service (10–20 minutes):

   ./install.sh

3. Only with a Google Coral accelerator:

   ./install-coral.sh

4 · Connect the station to a server

Pick one. The station needs the server's address and a device key. Location, thresholds and other settings then come from the server automatically.

Option A · Hosted site (approval email)

1. Request a site at ourchirp.com/about. When it's approved you get an email with your device key and a ready-made config.yaml snippet.
2. On the Pi: nano ~/chirp/chirp-device/config.yaml, find the upload: and server_sync: sections and paste in the values from the email. Save with Ctrl-O, Enter, Ctrl-X.

Option B · Auto-configure from the server Same network

For a server on your home network. The server finds the Pi and writes its settings for you.

1. Sign in as an admin and open Devices. Tap Discover.
2. The server scans your network for stations running Chirp. Next to yours, tap Auto-configure.
3. Enter the Pi's SSH username and password. The server makes a device key, writes it to config.yaml and restarts the station.
4. The station appears in Devices within a minute.

Option C · Manual key

1. As an admin, open Devices → New Device Key. Copy the key (it's shown once).
2. On the Pi, edit ~/chirp/chirp-device/config.yaml:

   upload:
     enabled: true
     server_url: "https://YOUR-SERVER/api/v1/recordings/upload"
     api_key: "chirp-…"
   
   server_sync:
     enabled: true
     server_url: "https://YOUR-SERVER"
     api_key: "chirp-…"
     device_name: "Garden Pi"

   Use the same key in both places. For ourchirp.com, YOUR-SERVER is ourchirp.com; for a home server it can be http://192.168.1.50:8768.

5 · Test and start

1. Check the microphone and detection:

   cd ~/chirp/chirp-device
   source venv/bin/activate
   python main.py --list-devices      # the mic should be listed
   python main.py --test-audio        # whistle; levels should jump
   python main.py --test-detection    # BirdNET loads and runs

2. Start it for good (it also starts on every boot):

   sudo systemctl restart chirp-device
   journalctl -u chirp-device -f      # watch it work; Ctrl-C to stop watching

3. Open your site. The station shows as online in Devices, and recordings appear within a minute of the first bird.

Server · Hosted on ourchirp.com

Nothing to install. Request a site; once it's approved you get your sign-in, invite code and device key by email. Then follow the station steps above with Option A.

Server · Run your own

One Docker container hosts any number of sites, each with its own members. Any always-on machine with Docker works: a NAS, Unraid, a mini PC or a spare computer.

1. Install Docker ↗ with Compose.
2. Download Chirp and copy the settings file:

   git clone https://github.com/joshsalvi/chirp.git
   cd chirp/chirp-server-instances
   cp .env.simple.example .env

3. Edit .env: set CHIRP_SECRET_KEY (make one with openssl rand -hex 32) and CHIRP_GLOBAL_ADMIN_USERNAME to the username you'll register.
4. Start it (the first build takes 5–10 minutes):

   docker compose -f docker-compose.simple.yml up -d --build

5. Open http://YOUR-SERVER-IP:8768, tap Create account with that username, then New Location to create your site. Restart once (docker compose -f docker-compose.simple.yml restart) to become server-wide admin.
6. In Settings → General, set the location, time zone and web address. Add an eBird key in Integrations and email under Alerts & Email.
7. Connect your station with Option B or C.

HTTPS, iPhone push and Live Detect

• HTTPS is needed for Live Detect's microphone and for browser notifications. The simplest route is a free Cloudflare Tunnel: guide ↗.
• iPhone push from your own server goes through a relay on ourchirp.com. Request a relay token, then paste it in Settings → Alerts & Email → iPhone Push. Your server doesn't need to be reachable from the internet for this.

The older single-site server Deprecated

chirp-server (one site per container) still runs but gets no new features. New setups should use chirp-server-instances above. To move an existing one: download a backup from the old server's Settings → Storage & Backup, then in the new server's location picker tap Import from Database File. Detections, the life list, notes and accounts come across; audio files stay on the old server.

App · iPhone and browser

1. iPhone: the Chirp app is coming to the App Store. Until then, open ourchirp.com (or your server's address) in Safari, tap Share → Add to Home Screen.
2. Computer or Android: open your site in any browser. Chrome and Edge offer Install app in the address bar.
3. Sign in, or tap Create account and enter your invite code.
4. Allow notifications when asked, then choose what you hear about in Settings → My Notifications.

Invite your household

1. As the site's admin, open Users. Your invite code is at the top; tap Copy invite and send it.
2. They create an account with the code and join as viewers.
3. Change someone's role on the same page: viewer (look and take notes), submitter (also uploads and iNaturalist), admin (everything).

Troubleshooting

More fixes on the troubleshooting page. Still stuck? Contact us. For day-to-day use, see the user guide.