Self-hosting quickstart guide (5 min)

NetBird is open-source and can be self-hosted on your servers.

It relies on components developed by NetBird Authors Management Service, Management UI Dashboard, Signal Service, a 3rd party open-source STUN/TURN service Coturn, and an identity provider (available options will be listed later in this guide).

If you would like to learn more about the architecture please refer to the Architecture section.

Quick self-hosting with Zitadel IdP

In this guide, we will guide you through deploying NetBird with Zitadel as the identity provider for user management using a single-line setup script and docker containers.


Infrastructure requirements:

  • A Linux VM with at least 1CPU and 2GB of memory.
  • The VM should be publicly accessible on TCP ports 80, 443, 33073 and 10000; and UDP ports: 3478, 49152-65535.
  • Public domain name pointing to the VM.

Software requirements:

  • Docker installed on the VM with the docker compose plugin (Docker installation guide) or docker with docker-compose in version 2 or higher.
  • jq installed. In most distributions Usually available in the official repositories and can be installed with sudo apt install jq or sudo yum install jq
  • curl installed. Usually available in the official repositories and can be installed with sudo apt install curl or sudo yum install curl

Download and run the script

Download and run the installation script in a single line:

export; curl -fsSL | bash

If you want to check the script before running it, you can download it and run it locally:

curl -sSLO
# check the script
# run the script

Once the script execution is complete, you can access your netbird instance via the URL using the credentials displayed in your terminal.

Add users

If you want to add additional users, you can access Zitadel's management console via the URL with the same credentials. Follow the Users guide from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide Configure identity providers.


To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.

The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:

mkdir backup
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json backup/

To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:

docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management

You can follow the Cockroach backup guide to backup Zitadel's database, which holds user information.


To upgrade NetBird to the latest version, you need to review the release notes for any breaking changes and follow the upgrade steps below:

  1. Run the backup steps described in the backup section.
  2. Pull the latest NetBird docker images:
    docker compose pull management dashboard signal
  3. Restart the NetBird containers with the new images:
    docker compose up -d --force-recreate management dashboard signal


To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:

# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
# remove downloaded and generated config files
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json


  • I'm trying to register a user but I didn't receive a verification code. What's the problem?

    The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network. If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See this guide or details.

Get in touch

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