Build a persistent wildlife-monitoring station, validate its audio pipeline, and publish its dashboard through one controlled tunnel
BirdNET-Go is a self-hosted soundscape analyzer that accepts soundcard or RTSP and RTSPS audio, runs wildlife-detection models locally, and presents detections through a browser dashboard. This guide uses the project's recommended host-network Docker Compose configuration and pins the example to BirdNET-Go release 20261014, which was verified for this tutorial rather than assumed to remain the latest release forever. You will install the required tools, prepare persistent storage and audio access, complete first-run configuration, verify the default dashboard at port 8080, and then expose that tested endpoint through a Localtonet HTTP tunnel. Remote access is added only after authentication, audio processing, model loading, storage, and restart persistence work locally.
📋 What's in this guide
How the BirdNET-Go and Localtonet deployment works
BirdNET-Go performs continuous wildlife monitoring on infrastructure you control. It can ingest a locally attached soundcard or one or more RTSP or RTSPS network streams, run supported detection models, store detections and optional recordings, and display results through a web interface. Its current feature set includes live spectrograms, detection heatmaps, configurable alert rules, MQTT and webhook integrations, system-health diagnostics, database tools, OIDC and SSO support, and multiple models assigned to separate sources.
The installation and remote-access layers have separate responsibilities. Docker Compose starts BirdNET-Go, grants the required audio-device access, and mounts persistent host directories into the container. BirdNET-Go handles audio analysis, data storage, authentication, and application authorization. The Localtonet client then establishes an outbound connection to one of our relay servers and routes a public HTTPS address to the already working local HTTP dashboard.
This separation produces a useful diagnostic boundary. If http://127.0.0.1:8080 does not work on the BirdNET-Go host, or the host's LAN address does not work from the Localtonet client device, creating a tunnel will not repair the underlying service. If local access works but public access fails, you can focus on the Localtonet client, device token, relay selection, tunnel lifecycle, and target address.
Why this tutorial pins release 20261014
The commands and release-specific guidance below are written for BirdNET-Go tag 20261014. Pinning a reviewed tag makes the repository files, Compose definition, onboarding behavior, model notes, and upgrade warnings reproducible. It does not mean 20261014 will remain the newest release, nor should an existing station be downgraded to it without checking data compatibility.
Release 20261014 includes a reworked setup wizard, configurable model selection, corrected false-positive filtering, live audio streaming changes, Privacy Guard improvements, and security fixes from release 20261010. It also stores dynamic thresholds per species and writes a configuration version. The release notes warn that older versions may fail to start with data updated by this release. Back up an existing station before changing versions.
Checking out a repository tag pins the Compose file and accompanying project documentation. Docker still pulls the image reference declared by that file. Before deployment, render the Compose configuration and record the resolved image name and image digest shown by Docker. Retaining the tag, effective Compose output, and image digest gives you a more useful deployment record than the Git tag alone.
Prerequisites and host preparation
BirdNET-Go publishes Linux container images for linux/amd64 and linux/arm64. Suitable hosts include 64-bit x86 Linux systems and supported 64-bit ARM systems such as a capable Raspberry Pi. The project documents Debian, Ubuntu, and Raspberry Pi OS among its quick-install platforms. This tutorial uses Docker Engine with the Docker Compose plugin on a Linux host.
| Requirement | What you need | How to verify it |
|---|---|---|
| Architecture | Linux AMD64 or ARM64 | uname -m should normally report x86_64, aarch64, or arm64. |
| Docker Engine | A running Docker daemon supported by your Linux distribution | Run docker version and confirm both client and server information appear. |
| Compose plugin | Compose V2, invoked as docker compose |
Run docker compose version. |
| Git | Git for cloning and checking out the pinned tag | Run git --version. |
| Audio source | An ALSA-visible soundcard or a reachable RTSP or RTSPS stream | Test it on the host before configuring BirdNET-Go. |
| Storage | Writable space for configuration, the database, detections, clips, models, logs, and backups | Check the repository filesystem with df -h .. |
| Local network access | Port 8080 available for the pinned default, unless deliberately overridden |
Check existing listeners before startup and test the dashboard afterward. |
| Localtonet placement | The client installed on this host or another device that can reach it | Request the dashboard directly from the eventual client device before creating a tunnel. |
Install Docker Engine and the Compose plugin
Use Docker's supported repository procedure for your exact distribution rather than an unofficial convenience package or an obsolete standalone docker-compose binary. On Debian-family systems, the current Docker repository packages are normally docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin. Repository-signing and distribution-codename steps change over time, so follow the matching page in the
official Docker Engine installation documentation.
After installation, enable and start Docker using the service-management procedure for your distribution. Then verify the engine and plugin:
docker version
docker compose version
docker run --rm hello-worldIf your account is not permitted to access the Docker socket, either use the administrative method selected for your host or configure Docker access according to Docker's post-install guidance. Membership in the Docker administrative group is effectively privileged host access. Do not grant it casually.
Install Git and basic diagnostic tools
Install Git through your distribution's package manager. For local testing, curl is useful for checking the dashboard, alsa-utils provides soundcard tools such as arecord, and FFmpeg packages commonly provide ffprobe for testing network streams. These host tools are diagnostic aids and are not additional BirdNET-Go services.
git --version
curl --version
uname -m
df -h .Prepare and test a soundcard
For a USB microphone or audio interface, connect the device before starting the container. On an ALSA-based Linux host, list capture devices:
arecord -l
arecord -L
Record a short host-side sample using the correct ALSA device selected from that output. Replace hw:CARD,DEVICE with a real identifier from your machine:
arecord -D hw:CARD,DEVICE -d 10 -f S16_LE -r 48000 -c 1 birdnet-input-test.wavConfirm that the file is non-empty and contains expected audio before deleting it. If the host cannot capture from the device, resolve cabling, device selection, ALSA ownership, exclusive-use conflicts, and permissions before involving Docker.
The pinned host-network Compose configuration grants the BirdNET-Go container access to /dev/snd. That mapping exposes host sound devices to the container, but it does not correct missing hardware or host-level permission problems. Avoid replacing the specific device mapping with unrestricted privileged mode.
Prepare and test an RTSP or RTSPS source
For a network camera, microphone encoder, or other stream source, verify DNS, routing, credentials, and stream availability from the BirdNET-Go host. If ffprobe is installed, a basic inspection is:
ffprobe -hide_banner "rtsp://USER:PASSWORD@STREAM-HOST/PATH"Do not paste a real stream URL into shell history on a shared machine. Prefer the credential handling available in your environment, and redact user names, passwords, hostnames, paths, and query parameters from screenshots and support logs. For RTSPS, also resolve certificate-validation problems rather than silently downgrading to an insecure stream.
BirdNET-Go supports sample rates up to 256 kHz for ultrasonic bat detection, but successful high-rate monitoring requires an ultrasonic-capable microphone, soundcard, host, and compatible model. Ordinary consumer microphones should not be assumed to capture ultrasonic calls.
Install BirdNET-Go with the pinned host-network Compose file
At release 20261014, the recommended host-network stack is stored at Docker/docker-compose.host.yml. It defines one BirdNET-Go application service rather than a separate database or reverse-proxy stack. The service uses host networking, maps the host's /dev/snd sound-device tree, mounts ./config at /config, mounts ./data at /data, and uses an unless-stopped restart policy.
Host networking means BirdNET-Go shares the Linux host's network namespace. There is no ordinary Docker ports: publication to translate a container port into a different host port. With the pinned file and its default application configuration, the dashboard listens on HTTP port 8080, so the host itself can use http://127.0.0.1:8080 and another LAN device can use http://HOST-LAN-IP:8080 when the listener and local firewall permit it.
The paths ./config and ./data are relative to the Compose project location. Run the commands from the checked-out BirdNET-Go repository and continue using the same Compose file path. Moving the repository or launching a copied file from another directory can point the container at different, empty host folders.
Clone the official repository
Download BirdNET-Go with Git and enter the repository directory.
Check out release 20261014
Fetch release tags, check out the pinned tag, and confirm that Git reports the expected revision.
Create persistent host directories
Create the configuration and data directories used by the Compose mounts. Keep them on storage with enough capacity for the database, models, and retained recordings.
Render and validate the effective configuration
Ask Compose to resolve the pinned file. Confirm the single application service, host network mode, sound-device mapping, persistent mounts, image reference, and restart policy before startup.
Pull and start the declared image
Pull the image selected by the pinned Compose file, start the service in the background, and record the resolved image information for your deployment notes.
Check service state and startup logs
Confirm that the service remains running and that initialization completes without repeated restarts, storage errors, model failures, or audio-device failures.
Clone the project and select the verified example release:
git clone https://github.com/tphakala/birdnet-go.git
cd birdnet-go
git fetch --tags
git checkout 20261014
git describe --tags --exact-matchCreate the host directories used by the pinned Compose file:
mkdir -p config data
ls -ld config dataThe container process must be able to write these directories. Do not solve permission errors by making them world-writable. Start with the directories owned by the account responsible for the deployment, run the container once, and use the exact permission error and container identity to choose a narrow correction if one is required.
Render the effective configuration:
docker compose -f Docker/docker-compose.host.yml configIn the output for this pinned example, confirm the following operational properties:
- There is one BirdNET-Go application service.
- The service uses
network_mode: host. - The host sound-device tree
/dev/sndis made available to the container. - The repository's
configdirectory is mounted at/config. - The repository's
datadirectory is mounted at/data. - The restart policy is
unless-stopped. - The image reference is the one expected for the selected release workflow.
Pull the declared image and start BirdNET-Go:
docker compose -f Docker/docker-compose.host.yml pull
docker compose -f Docker/docker-compose.host.yml up -d
docker compose -f Docker/docker-compose.host.yml ps
docker compose -f Docker/docker-compose.host.yml logs --tail=200
Record the actual image ID and digest after the pull. The service name can be read from docker compose ps, while docker image inspect can provide the immutable image details. This is particularly useful if the Compose file references a moving image tag.
Confirm the effective dashboard listener
The documented default for the pinned host-network configuration is HTTP on port 8080. Test that default first:
curl -I http://127.0.0.1:8080/
ss -ltn | grep ':8080'
A response other than a network connection failure proves that an HTTP listener answered, although redirects or authentication responses may be expected. Open http://HOST-LAN-IP:8080 in a browser on the local network to continue onboarding.
If port 8080 does not answer, do not scan random ports. Review the startup logs, the rendered Compose configuration, and the files under the persistent config directory for an intentional web-listener override. An existing installation may preserve a non-default port or bind address in its configuration. You can also inspect current host listeners with:
ss -ltnpUse the endpoint that is both configured and observed. Host networking exposes the application listener directly on the host, but it does not force BirdNET-Go to bind every interface or override the Linux firewall.
Complete BirdNET-Go first-run configuration
Open the local dashboard and complete the first-run wizard before creating a public route. Release 20261014 includes a reworked onboarding experience, and later releases may rename or rearrange screens. The exact visual order can therefore vary, but a commissioned station needs the concrete outcomes below.
Establish administrative authentication
Create the administrator access requested by the wizard and store its credentials in an appropriate password manager. If you use OIDC or SSO instead, keep local recovery and identity-provider dependencies in mind before relying on remote access.
Set the station location and time zone
Select the station's real region and coordinates with only the precision your monitoring purpose requires. Location affects range filtering and may be sensitive when the dashboard is shared publicly.
Configure one audio source
Select one verified ALSA capture device or enter one tested RTSP or RTSPS stream. Begin with one source so device, credential, sample-rate, and connectivity problems remain easy to isolate.
Enable an appropriate detection model
Use an installed model appropriate for the source, region, wildlife, and available hardware. Confirm that it is assigned to the selected source and loads successfully.
Review recording and storage behavior
Choose whether detections create audio clips, set retention according to your purpose and disk capacity, and verify that BirdNET-Go reports writable storage. Avoid collecting more audio than the station needs.
Finish onboarding and open System Health
Save the configuration, wait for the source and model to initialize, and review audio, inference, network, and datastore health before adding alerts, additional models, or remote access.
Soundcard configuration checks
In the audio-source screen, choose the same physical capture device you tested on the host. Device labels can change when USB hardware is disconnected, connected in a different order, or moved to another port. After saving, verify that BirdNET-Go displays an active stream or spectrogram and that the logs do not report an unavailable ALSA device.
If the device appears on the host but not in BirdNET-Go, confirm that /dev/snd exists, the effective Compose output contains the device mapping, and no other application has exclusive control of the soundcard. Restarting blindly will not fix a wrong device name.
RTSP and RTSPS configuration checks
Enter the exact stream that succeeded in the host-side test. Confirm that BirdNET-Go reports the source as live and observe it long enough to detect intermittent authentication or network failures. Network cameras sometimes expose several profiles with different codecs, channels, and sample rates, so select an audio-bearing profile appropriate for analysis.
Keep stream credentials out of public screenshots and logs. If the source is on another VLAN, confirm that the BirdNET-Go host is allowed to reach the stream without opening unnecessary access in the opposite direction.
Model selection and CPU planning
Release 20261014 can run combinations of installed models, including BirdNET v2.4, Google Perch v2, regional BattyBirdNET classifiers, the BirdNET Geomodel, and supported custom classifiers. BirdNET v2.4 remains included in this release, although its packaging was expected to change in a later release. Model availability and installation behavior should therefore be rechecked when deploying a different tag.
Start with one model suited to the station. Multiple sources and parallel models multiply the analysis workload. Release 20261014 corrected false-positive filtering so stronger settings perform the intended overlapping analysis. At Maximum strength, the analysis step can fall from 1.5 seconds to 0.2 seconds, resulting in up to about 15 times more model runs per source and model.
BirdNET-Go measures analysis time and can reduce overlap when the requested work would exceed its internal safety ceiling. That protection does not make every workload suitable for every device. If CPU use is excessive or audio processing falls behind, lower False Positive Filter Strength under Settings > Analysis, reduce the number of models or sources, and check the effective analysis information displayed there.
Use appropriate microphone placement, notices, consent, retention limits, and local legal guidance. BirdNET-Go's Privacy Guard can help reduce retained human speech, but no automated filter should be treated as a complete privacy guarantee.
Verify the local station before creating a tunnel
A running container is not the same as a healthy monitoring station. Verify the HTTP listener, authentication, audio continuity, model inference, storage, and persistence as separate checks.
Confirm stable container state
Use Compose status and logs to confirm that the service is not repeatedly restarting or failing after initialization.
Test the dashboard on the host
Open the default http://127.0.0.1:8080 endpoint, or the observed override, and confirm the expected authentication flow.
Test from another LAN device
Open http://HOST-LAN-IP:8080 from a separate device. This verifies the address needed when Localtonet will run somewhere other than the BirdNET-Go host.
Confirm audio and model health
Check the live view and System Health page for an active source, loaded model, continuing inference, and no stream-recovery loop.
Confirm storage and detections
Allow the station to produce data, verify that detections and enabled clips appear, and confirm that the host-side data directory grows as expected.
Restart and recheck persistence
Restart the service and confirm that authentication, station settings, source configuration, models, detections, and retained clips remain available.
docker compose -f Docker/docker-compose.host.yml ps
docker compose -f Docker/docker-compose.host.yml logs --tail=200
curl -I http://127.0.0.1:8080/
docker compose -f Docker/docker-compose.host.yml restart
docker compose -f Docker/docker-compose.host.yml ps
docker compose -f Docker/docker-compose.host.yml logs --tail=200If the Localtonet client will run on another device, perform an explicit request from that device before creating the tunnel. Replace the example address with the BirdNET-Go host's real LAN address:
curl -I http://192.168.1.50:8080/
Record the exact working scheme, address, and port. If Localtonet will run on the BirdNET-Go host and loopback works, the target can be 127.0.0.1 and 8080. If Localtonet will run elsewhere, 127.0.0.1 would refer to that other device, so use the tested LAN address instead.
A redirect to onboarding or login still proves that the HTTP service answered. A connection refusal, timeout, or response from an unrelated application does not. Confirm the page identity in a browser before using the endpoint as a tunnel target.
Expose the verified dashboard with Localtonet
Install the Localtonet client on the BirdNET-Go host or another device that can reach the tested local endpoint. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or firewall changes. The public route remains available only while the selected device is connected and the tunnel is running.
Install the current Localtonet client
Sign in to Localtonet, open the current client installation area for the operating system that will run the tunnel, and follow the displayed installation method. The client package and operating-system instructions can change, so use the current Localtonet documentation rather than copying an old binary URL or command from an unrelated tutorial. Create an account first if needed: register for Localtonet.
After installation, start the client and associate it with the device-specific authentication token shown for that device. Treat the token as a credential. Never publish it in a command transcript, screenshot, repository, issue report, or monitoring log.
Recheck BirdNET-Go from the client device
Before opening the Localtonet tunnel form, run the same request from the machine on which the Localtonet client is running:
curl -I http://127.0.0.1:8080/Use loopback only when BirdNET-Go and Localtonet share the same host. From another device, test the BirdNET-Go host's LAN address:
curl -I http://192.168.1.50:8080/Do not proceed until that request reaches the correct BirdNET-Go login or onboarding flow. This check eliminates DNS, routing, local-firewall, and loopback-address mistakes before tunnel configuration.
Install and run the Localtonet client
Use the current operating-system instructions in our documentation and keep the client running on the device that can reach BirdNET-Go.
Authenticate or select the client device
Use the device-specific authentication token for the client that will own the tunnel. Do not reuse a guessed value or expose the token.
Select an available relay server
Choose a server or region currently offered in the dashboard. Available choices can vary by plan, region, and current service availability, so no server code is hardcoded here.
Create an HTTP tunnel
Select the desired HTTP process type and enter the exact local IP address and port tested from the Localtonet client device. For the unmodified pinned deployment on the same host, that target is normally 127.0.0.1 and 8080.
Start the tunnel
Creating a tunnel does not make it active. Use the Start button and confirm that both the selected client device and tunnel report a connected state.
Verify the public HTTPS address
Open the assigned address from a network outside the BirdNET-Go LAN. Test login, ordinary navigation, live views, and the functions you actually intend to use.
HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, with the options available to the account shown in the dashboard. All three serve the selected content through a public HTTPS address. Do not invent custom-domain DNS values or copy them from another account. Follow the values displayed by the current product workflow and the Localtonet HTTP tunnel documentation.
Test live and WebSocket-based features
BirdNET-Go includes live browser functions and a browser terminal that use long-running interactive connections, including WebSockets. A successful page load does not prove that every interactive feature works through a particular deployment.
Test the exact features you need through the public URL. If a live spectrogram, real-time update, or terminal connection fails, first confirm that the same feature works through the local URL. Then inspect the browser developer console and network panel, compare BirdNET-Go logs, and record the exact application and client versions. This is more reliable than assuming universal compatibility or changing unrelated settings.
Secure the remotely reachable dashboard
A Localtonet tunnel provides connectivity to the configured target. It does not replace BirdNET-Go authentication, application authorization, privacy controls, or safe secret management. Enable and test authentication before distributing the public address.
Release 20261014 includes security guidance inherited from 20261010: installations using subnet login bypass behind a reverse proxy must configure the proxy in security.trustedproxies. Do not add broad trusted networks merely to make public login work. If you do not understand how BirdNET-Go sees the proxied client address, leave subnet bypass disabled and require normal authentication.
Reverse-proxy and tunnel traffic can change the source address and forwarded-header context observed by an application. Only configure a trusted proxy value when the deployed BirdNET-Go documentation identifies the required setting and you can restrict it to the actual proxy path. Trusting arbitrary sources can allow forged forwarding headers to affect security decisions.
OIDC and SSO deployments also need a public callback or redirect URL that matches the assigned external scheme and hostname. Generated tunnel addresses and custom domains produce different callback values. Follow the identity provider's exact-match rules and BirdNET-Go's current OIDC configuration guidance. Do not disable callback validation or authentication to work around a mismatch.
Cookie security can depend on the browser-visible HTTPS origin, application base URL, proxy headers, and BirdNET-Go release. If login loops or sessions disappear only through the public URL, compare the browser's cookie and redirect behavior with the local flow. Change only documented BirdNET-Go settings for that release. Avoid weakening secure-cookie or same-site behavior without understanding the exposure.
Protect RTSP credentials, Localtonet device tokens, OIDC client secrets, MQTT credentials, webhook secrets, alert-destination tokens, and database credentials. Keep them out of Git, screenshots, support dumps intended for public sharing, and shell history where practical. Restrict filesystem access to the persistent configuration directory.
BirdNET-Go can contain location information, detection history, recorded audio, diagnostics, integrations, and powerful administration tools. Give administrative access only to people who need it. When remote access is temporary, stop the tunnel afterward. Delete tunnels that are no longer required.
Routine operation, backups, restoration, and updates
Continue using the pinned Compose file for lifecycle operations. Running generic Compose commands from another directory can select a different project or create new relative storage paths.
| Task | Command or action | What to verify |
|---|---|---|
| Check service state | docker compose -f Docker/docker-compose.host.yml ps |
The BirdNET-Go service remains running. |
| Read recent logs | docker compose -f Docker/docker-compose.host.yml logs --tail=200 |
No repeated source, model, database, or restart failure. |
| Follow logs | docker compose -f Docker/docker-compose.host.yml logs -f |
Observe behavior during a controlled test, then exit the viewer without stopping the service. |
| Restart | docker compose -f Docker/docker-compose.host.yml restart |
Configuration and historical data remain available afterward. |
| Stop and remove the container | docker compose -f Docker/docker-compose.host.yml down |
The host-side config and data directories remain intact. |
| Start again | docker compose -f Docker/docker-compose.host.yml up -d |
The same persistent state is mounted and the health checks pass. |
| Disable public access | Stop the Localtonet tunnel | The public route is inactive while local BirdNET-Go operation continues. |
What a BirdNET-Go backup must preserve
The pinned Compose layout stores persistent application state under the host-side config and data directories. Preserve both. Configuration can include station settings, source definitions, authentication-related state, integrations, and model assignments. Data can include the SQLite datastore used by default, detection records, audio clips, model assets, and other application-managed files.
If you configured MySQL instead of the default SQLite database, the database is external to these two directory copies and requires a consistent database-native backup. Likewise, secrets or certificates stored outside the mounted directories must be inventoried and protected separately. A Compose file by itself is not a backup.
BirdNET-Go provides automatic backup functionality and reports backup status, but an application backup should still be validated. Before an upgrade or storage migration:
- Record the running BirdNET-Go tag, effective Compose output, and resolved image digest.
- Create an application-supported database backup.
- Preserve the complete host-side
configanddatadirectories with permissions and timestamps where possible. - Preserve any external database dump, certificates, and separately managed secrets.
- Store a copy away from the active host.
Test restoration instead of trusting file presence
A backup is useful only if it restores. Test on an isolated host or isolated copy of the deployment, not over the only working station. Restore the configuration and data to equivalent mount paths, start the matching BirdNET-Go version, and verify login, station location, audio-source definitions, model assignments, historical detections, recordings, and database health.
Do not connect a restoration test to the live microphone, production stream, alert destinations, MQTT broker, or public tunnel until you have disabled duplicate actions. Otherwise the test can create duplicate detections, alerts, or external writes.
Update deliberately
Before selecting a newer release, read every intervening release note and check for configuration migrations, model packaging changes, security actions, CPU changes, and downgrade restrictions. Release 20261014 specifically warns that its updated configuration and dynamic-threshold data may not start correctly on older releases.
After backing up, check out the reviewed replacement tag, render its Compose file, compare mounts and device access, pull its image, and start it. Then repeat the complete local verification sequence. Confirm authentication, audio, model loading, detections, storage, System Health, restart persistence, and the Localtonet public workflow.
Troubleshooting BirdNET-Go and Localtonet
Docker or Compose is unavailable
If docker version cannot contact the server, confirm that Docker Engine is installed and running and that your account has the intended socket access. If docker compose version fails, install the Compose plugin rather than relying on an obsolete standalone command from an old tutorial.
The Compose file does not validate
Run docker compose -f Docker/docker-compose.host.yml config and read the first error. Confirm that Git is at tag 20261014 and that the file has not been partially copied or edited. Return to a clean checkout instead of adding fields from an unrelated Docker example.
The container repeatedly restarts
Read the complete startup logs and identify the first failure. Common categories include unwritable persistent directories, malformed configuration, unavailable devices, model-loading failures, database errors, or an occupied listener. Confirm that config and data exist and that the expected host paths appear in the rendered Compose output.
Port 8080 does not answer
The pinned default is HTTP on port 8080, but an existing persistent configuration can override defaults. Check the logs, ss -ltnp, and the application configuration under the mounted config directory. Also check whether another host process already owns port 8080. Use the configured and observed listener rather than guessing.
The dashboard works on loopback but not from the LAN
Check whether BirdNET-Go is bound only to loopback, whether the Linux firewall allows the intended LAN path, and whether client isolation or VLAN policy blocks the connection. Host networking does not bypass the host firewall. Do not open the port broadly to the internet. The Localtonet workflow requires only that the selected client device can reach the local target.
The soundcard is missing inside BirdNET-Go
Verify the device with arecord -l on the host, confirm that /dev/snd exists, and check the rendered Compose file for the sound-device mapping. Look for another process holding the device and review the exact permission error. Avoid enabling unrestricted privileged mode as a shortcut.
The RTSP source disconnects or never becomes healthy
Test the same URL from the host with a suitable media probe. Confirm credentials, codec, audio track, network route, firewall policy, and certificate behavior for RTSPS. If the source offers multiple profiles, verify that the chosen profile actually contains audio. Redact credentials before sharing logs.
The dashboard works, but no detections appear
Separate the pipeline into source, model, and filtering checks. Confirm live audio first. Then confirm that an installed model is enabled and assigned to the source. Review confidence thresholds, location filtering, quiet hours, daylight settings, Privacy Guard, and false-positive filtering. A healthy web interface does not prove that inference is receiving usable audio.
CPU use increased after deploying release 20261014
Review False Positive Filter Strength under Settings > Analysis. The corrected filter performs more overlapping analysis at stronger settings, with Maximum potentially producing up to about 15 times more model runs per source and model than a 1.5-second step. Lower the strength, reduce models or sources, and monitor the effective window information reported by BirdNET-Go.
The Localtonet tunnel exists but is unavailable
Confirm that the correct Localtonet device is connected, the selected relay remains available to the account, and the tunnel has been started. Tunnel creation and tunnel startup are separate lifecycle states. Then repeat the direct BirdNET-Go request from the Localtonet client machine.
The public URL returns an error while local access works
Compare the tunnel target with the endpoint tested from the client device. If the Localtonet client runs on another machine, 127.0.0.1 points to that machine rather than the BirdNET-Go host. Use the verified LAN address and port. Also confirm that the target uses HTTP unless you deliberately configured BirdNET-Go itself for HTTPS.
The public page loads, but live updates fail
Test the same function locally, inspect failed browser requests and WebSocket connections, and compare BirdNET-Go logs. Record the exact BirdNET-Go release, browser error, Localtonet client version, and affected route. Do not assume that changing authentication, trusted-proxy, or cookie settings is the correct fix unless the error specifically supports it.
OIDC login loops through the public URL
Confirm that the identity provider's registered redirect URI exactly matches the public scheme, hostname, path, and port expected by the deployed BirdNET-Go version. Then review documented external-base-URL, proxy, trusted-proxy, TLS, and cookie settings for that release. Do not broaden trusted proxies or disable authentication to suppress the symptom.
Frequently asked questions
What is the default BirdNET-Go dashboard address in this tutorial?
For the pinned 20261014 host-network configuration with default application settings, use http://127.0.0.1:8080 on the BirdNET-Go host or http://HOST-LAN-IP:8080 from another local device. Existing persistent configuration can override the listener, so verify it with logs, ss -ltnp, and a direct HTTP request.
Does checking out tag 20261014 guarantee an immutable container image?
It pins the repository files and Compose definition, but Docker pulls the image reference declared by that definition. Record the resolved image name, image ID, and digest after pulling if you need a reproducible deployment record.
What data persists when the BirdNET-Go container is recreated?
The pinned Compose file mounts the host's ./config directory at /config and ./data at /data. Preserve both host directories. If you use an external MySQL database or separately stored secrets and certificates, back those up independently.
Why does the recommended Compose file use host networking?
BirdNET-Go directs Compose users to its host-network configuration as the recommended starting point. The application shares the host network namespace, so its listener is available directly on the host rather than through a Docker port mapping. Bridge configurations remain possible, but their published host port must be used instead.
Can BirdNET-Go run on a Raspberry Pi?
Yes. BirdNET-Go publishes a Linux ARM64 container and documents Raspberry Pi support. Capacity depends on the Pi model, audio sample rate, number of sources, enabled models, filter strength, live views, and other workloads. Begin with one source and one model.
Can the Localtonet client run on another device?
Yes. The other device must be able to reach BirdNET-Go through its LAN address and port. Do not use 127.0.0.1 in that arrangement because it refers to the Localtonet client device itself.
Does Localtonet require router port forwarding?
No. Our client establishes an outbound connection to a Localtonet relay server. The HTTP tunnel can provide a public HTTPS address without inbound router port forwarding, a public IP address, firewall changes, or VPN setup.
Does creating a Localtonet tunnel start it automatically?
No. Create the tunnel, then use the Start button. The public route remains available only while the selected client is connected and the tunnel is running.
Is a public Localtonet URL a substitute for BirdNET-Go authentication?
No. The tunnel provides connectivity to the configured local service. BirdNET-Go must still enforce appropriate authentication and authorization. Review trusted-proxy, subnet-bypass, OIDC, cookie, privacy, and administrative-access behavior before sharing the public URL.
Can I use a custom domain for BirdNET-Go?
Localtonet HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. Availability can vary by account or plan. Use the current dashboard and documentation for exact DNS and validation requirements rather than copying records from another deployment.
Connect your verified BirdNET-Go station with Localtonet
Build the local station first, confirm authentication, audio, model inference, storage, and restart persistence, then create an HTTP tunnel for the exact endpoint tested from the Localtonet client device.
Get Started Free →
