some file

Upgrade Your Self-Hosted NetBird Installation

Updated

Check for Updates

The NetBird Dashboard displays an update indicator at the bottom of the left navigation menu when a new version is available:

update-available

You can also check the current version programmatically via the API (requires authentication):

curl 'https://your-netbird-domain/api/instance/version' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <your-access-token>'

Example response:

{
    "dashboard_available_version": "2.28.0",
    "management_available_version": "0.64.1",
    "management_current_version": "0.64.0",
    "management_update_available": true
}

Check Release Notes

Before upgrading, review the release notes for any breaking changes or migration steps:

Management, Signal, and Relay are all part of the same repository and share the same version numbers.

Upgrade Steps

To upgrade NetBird to the latest version:

  1. Run the backup steps described in the backup section.
  2. Review the release notes (see above) for any breaking changes.
  3. Pull the latest NetBird docker images: 
    docker compose pull netbird-server dashboard
    If you have the Reverse Proxy enabled, also pull the proxy image: 
    docker compose pull proxy
  4. Restart the NetBird containers with the new images: 
    docker compose up -d --force-recreate netbird-server dashboard
    If you pulled the proxy image above, include it in the restart: 
    docker compose up -d --force-recreate netbird-server dashboard proxy

Keep the Management and proxy versions in sync. Starting with v0.76.1, if the Reverse Proxy component runs a newer version than Management, Agent Network LLM cost metering is silently disabled (the proxy skips cost computation and only logs a warning). Upgrade Management before or together with the proxy.

Because the netbirdio/reverse-proxy:latest image tag does not tell you what is actually running, check the resolved proxy version with:

docker compose exec proxy /go/bin/netbird-proxy --version

Compare it with the management_current_version field returned by GET /api/instance/version before upgrading.

For upgrades from older versions (pre-v0.26.0), see the Legacy upgrade notes below.

Migration Notes

Set reverseProxy.trustedPeers on older deployments

Deployments created with the Quickstart script (or a marketplace image based on it, such as Vultr) before September 2026 are missing the reverseProxy.trustedPeers setting in the generated config.yaml. Without it, server versions up to v0.79 record your reverse proxy's address instead of the real client IP for each peer connection. Versions after v0.79 (netbird#7589) instead fall back to accepting forwarded client-IP headers from any source and log a spoofing warning at startup.

To fix an existing deployment, edit config.yaml (in /opt/netbird on marketplace images) and pin trustedPeers to the address your reverse proxy connects to Management from. For the bundled Traefik setup, replace <bundled-traefik-address> below with its configured static container address in CIDR notation (/32 for a single IPv4 address). If the address is not static, use the configured proxy network's CIDR instead:

  reverseProxy:
    trustedHTTPProxies:
      - "<bundled-traefik-address>"
    trustedPeers:
      - "<bundled-traefik-address>"

If you run your own external reverse proxy (Nginx, Caddy, Nginx Proxy Manager, etc.), use that proxy's address or network instead. Then restart the server container:

docker compose restart netbird-server

With this in place, only your reverse proxy is trusted to supply forwarded client-IP headers and peer connection IPs are recorded correctly. Deployments created with the current Quickstart script include this setting out of the box.

Legacy Setup (Separate Containers)

If your deployment uses the older setup with separate containers (management, signal, relay, coturn), pull and recreate those containers instead:

docker compose pull management dashboard signal relay

docker compose up -d --force-recreate management dashboard signal relay

If you have the Reverse Proxy enabled, also pull and recreate the proxy:

docker compose pull proxy && docker compose up -d --force-recreate proxy

Get In Touch

Feel free to ping us on Slack if you have any questions.