From 4955c345d53f63394266305744841c4e1bff8123 Mon Sep 17 00:00:00 2001
From: Viktor Liu <17948409+lixmal@users.noreply.github.com>
Date: Wed, 20 May 2026 23:25:56 +0900
Subject: [PATCH] Clean up README header, key features table, and self-hosted
quickstart (#6178)
---
README.md | 153 +++++++++++++++++++++++++-----------------------------
1 file changed, 70 insertions(+), 83 deletions(-)
diff --git a/README.md b/README.md
index dc84af2fd..cc27e2d28 100644
--- a/README.md
+++ b/README.md
@@ -1,147 +1,134 @@
-
-
- Start using NetBird at netbird.io
+
+ Start using NetBird at netbird.io
+
+ See Documentation
+
+ Join our Slack channel or our Community forum
+
- See Documentation
- Join our Slack channel or our Community forum
-
-
-
-
-
- ๐ We are hiring! Join us at careers.netbird.io
-
-
-
-
- New: NetBird terraform provider
-
+
+ ๐ We are hiring! Join us at careers.netbird.io
+
-
-
**NetBird combines a configuration-free peer-to-peer private network and a centralized access control system in a single platform, making it easy to create secure private networks for your organization or home.**
**Connect.** NetBird creates a WireGuard-based overlay network that automatically connects your machines over an encrypted tunnel, leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, and so forth.
**Secure.** NetBird enables secure remote access by applying granular access policies while allowing you to manage them intuitively from a single place. Works universally on any infrastructure.
-### Open Source Network Security in a Single Platform
-
https://github.com/user-attachments/assets/10cec749-bb56-4ab3-97af-4e38850108d2
-### Self-Host NetBird (Video)
+### Self-host NetBird (video)
+
[](https://youtu.be/bZAgpT6nzaQ)
### Key features
-| Connectivity | Management | Security | Automation| Platforms |
-|----|----|----|----|----|
-| | - - \[x] [Admin Web UI](https://github.com/netbirdio/dashboard)
| - - \[x] [SSO & MFA support](https://docs.netbird.io/how-to/installation#running-net-bird-with-sso-login)
| - - \[x] [Public API](https://docs.netbird.io/api)
| |
-| - - \[x] Peer-to-peer connections
| - - \[x] Auto peer discovery and configuration
| - - \[x] [Access control - groups & rules](https://docs.netbird.io/how-to/manage-network-access)
| - - \[x] [Setup keys for bulk network provisioning](https://docs.netbird.io/how-to/register-machines-using-setup-keys)
| - - \[x] Mac
|
-| - - \[x] Connection relay fallback
| - - \[x] [IdP integrations](https://docs.netbird.io/selfhosted/identity-providers)
| - - \[x] [Activity logging](https://docs.netbird.io/how-to/audit-events-logging)
| - - \[x] [Self-hosting quickstart script](https://docs.netbird.io/selfhosted/selfhosted-quickstart)
| - - \[x] Windows
|
-| - - \[x] [Routes to external networks](https://docs.netbird.io/how-to/routing-traffic-to-private-networks)
| - - \[x] [Private DNS](https://docs.netbird.io/how-to/manage-dns-in-your-network)
| - - \[x] [Device posture checks](https://docs.netbird.io/how-to/manage-posture-checks)
| - - \[x] IdP groups sync with JWT
| - - \[x] Android
|
-| - - \[x] NAT traversal with BPF
| - - \[x] [Multiuser support](https://docs.netbird.io/how-to/add-users-to-your-network)
| - - \[x] Peer-to-peer encryption
|| - - \[x] iOS
|
-||| - - \[x] [Quantum-resistance with Rosenpass](https://netbird.io/knowledge-hub/the-first-quantum-resistant-mesh-vpn)
|| - - \[x] OpenWRT
|
-||| - - \[x] [Periodic re-authentication](https://docs.netbird.io/how-to/enforce-periodic-user-authentication)
|| - - \[x] [Serverless](https://docs.netbird.io/how-to/netbird-on-faas)
|
-||||| - - \[x] Docker
|
+| Connectivity | Management | Security | Automation | Platforms |
+|---|---|---|---|---|
+| โ [Kernel WireGuard](https://docs.netbird.io/about-netbird/why-wireguard-with-netbird) | โ [Admin Web UI](https://github.com/netbirdio/dashboard) | โ [SSO & MFA support](https://docs.netbird.io/how-to/installation#running-net-bird-with-sso-login) | โ [Public API](https://docs.netbird.io/api) | โ [Linux](https://docs.netbird.io/get-started/install/linux) |
+| โ [Peer-to-peer connections](https://docs.netbird.io/about-netbird/how-netbird-works) | โ Auto peer discovery and configuration | โ [Access control: groups & rules](https://docs.netbird.io/how-to/manage-network-access) | โ [Setup keys for bulk provisioning](https://docs.netbird.io/how-to/register-machines-using-setup-keys) | โ [macOS](https://docs.netbird.io/get-started/install/macos) |
+| โ Connection relay fallback | โ [IdP integrations](https://docs.netbird.io/selfhosted/identity-providers) | โ [Activity logging](https://docs.netbird.io/how-to/audit-events-logging) | โ [Self-hosting quickstart script](https://docs.netbird.io/selfhosted/selfhosted-quickstart) | โ [Windows](https://docs.netbird.io/get-started/install/windows) |
+| โ [Routes to external networks](https://docs.netbird.io/how-to/routing-traffic-to-private-networks) | โ [Private DNS](https://docs.netbird.io/how-to/manage-dns-in-your-network) | โ [Traffic events](https://docs.netbird.io/manage/activity/traffic-events-logging) | โ [IdP groups sync with JWT](https://docs.netbird.io/manage/team/idp-sync) | โ [Android](https://docs.netbird.io/get-started/install/android) |
+| โ [Domain-based DNS routes](https://docs.netbird.io/manage/dns/dns-aliases-for-routed-networks) | โ [Custom DNS zones](https://docs.netbird.io/manage/dns/custom-zones) | โ [Device posture checks](https://docs.netbird.io/how-to/manage-posture-checks) | โ [Terraform provider](https://registry.terraform.io/providers/netbirdio/netbird/latest) | โ [Android TV](https://docs.netbird.io/get-started/install/android-tv) |
+| โ [Exit nodes](https://docs.netbird.io/manage/network-routes/use-cases/exit-nodes) | โ [Multiuser support](https://docs.netbird.io/how-to/add-users-to-your-network) | โ Peer-to-peer encryption | โ [Ansible collection](https://github.com/netbirdio/ansible-netbird) | โ [iOS](https://docs.netbird.io/get-started/install/ios) |
+| โ [IPv6 dual-stack overlay](https://docs.netbird.io/manage/settings/ipv6) | โ [Multi-account profile switching](https://docs.netbird.io/client/profiles) | โ [SSH with central access policies](https://docs.netbird.io/manage/peers/ssh) | | โ [Apple TV](https://docs.netbird.io/get-started/install/tvos) |
+| โ [Browser SSH & RDP](https://docs.netbird.io/manage/peers/browser-client) | | โ [Quantum-resistance with Rosenpass](https://netbird.io/knowledge-hub/the-first-quantum-resistant-mesh-vpn) | | โ FreeBSD |
+| โ [Reverse proxy with auto-TLS](https://docs.netbird.io/manage/reverse-proxy) | | โ [Periodic re-authentication](https://docs.netbird.io/how-to/enforce-periodic-user-authentication) | | โ [pfSense](https://docs.netbird.io/get-started/install/pfsense) |
+| | | | | โ [OPNsense](https://docs.netbird.io/get-started/install/opnsense) |
+| | | | | โ [MikroTik RouterOS](https://docs.netbird.io/use-cases/homelab/client-on-mikrotik-router) |
+| | | | | โ OpenWRT |
+| | | | | โ [Synology](https://docs.netbird.io/get-started/install/synology) |
+| | | | | โ [TrueNAS](https://docs.netbird.io/get-started/install/truenas) |
+| | | | | โ [Proxmox](https://docs.netbird.io/get-started/install/proxmox-ve) |
+| | | | | โ [Raspberry Pi](https://docs.netbird.io/get-started/install/raspberrypi) |
+| | | | | โ [Serverless](https://docs.netbird.io/how-to/netbird-on-faas) |
+| | | | | โ [Container](https://docs.netbird.io/get-started/install/docker) |
### Quickstart with NetBird Cloud
-- Download and install NetBird at [https://app.netbird.io/install](https://app.netbird.io/install)
-- Follow the steps to sign-up with Google, Microsoft, GitHub or your email address.
-- Check NetBird [admin UI](https://app.netbird.io/).
-- Add more machines.
+- Download and install NetBird at [https://app.netbird.io/install](https://app.netbird.io/install).
+- Follow the steps to sign up with Google, Microsoft, GitHub or your email address.
+- Check the NetBird [admin UI](https://app.netbird.io/).
### Quickstart with self-hosted NetBird
-> This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
-Follow the [Advanced guide with a custom identity provider](https://docs.netbird.io/selfhosted/selfhosted-guide#advanced-guide-with-a-custom-identity-provider) for installations with different IDPs.
+This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. Follow the [Advanced guide with a custom identity provider](https://docs.netbird.io/selfhosted/selfhosted-guide#advanced-guide-with-a-custom-identity-provider) for installations with different IdPs.
**Infrastructure requirements:**
-- A Linux VM with at least **1CPU** and **2GB** of memory.
-- The VM should be publicly accessible on TCP ports **80** and **443** and UDP port: **3478**.
-- **Public domain** name pointing to the VM.
+- A Linux VM with at least **1 CPU** and **2 GB** of memory.
+- The VM should be publicly accessible on TCP ports **80** and **443** and UDP port **3478**.
+- A **public domain** name pointing to the VM.
**Software requirements:**
-- Docker installed on the VM with the docker-compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or docker with docker-compose in version 2 or higher.
-- [jq](https://jqlang.github.io/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](https://curl.se/) installed.
- Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
+- Docker with the Compose plugin (Compose v2 or higher). See the [Docker installation guide](https://docs.docker.com/engine/install/).
**Steps**
- Download and run the installation script:
```bash
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
```
-- Once finished, you can manage the resources via `docker-compose`
### A bit on NetBird internals
-- Every machine in the network runs [NetBird Agent (or Client)](client/) that manages WireGuard.
-- Every agent connects to [Management Service](management/) that holds network state, manages peer IPs, and distributes network updates to agents (peers).
-- NetBird agent uses WebRTC ICE implemented in [pion/ice library](https://github.com/pion/ice) to discover connection candidates when establishing a peer-to-peer connection between machines.
-- Connection candidates are discovered with the help of [STUN](https://en.wikipedia.org/wiki/STUN) servers.
-- Agents negotiate a connection through [Signal Service](signal/) passing p2p encrypted messages with candidates.
-- Sometimes the NAT traversal is unsuccessful due to strict NATs (e.g. mobile carrier-grade NAT) and a p2p connection isn't possible. When this occurs the system falls back to a relay server called [TURN](https://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT), and a secure WireGuard tunnel is established via the TURN server.
-
-[Coturn](https://github.com/coturn/coturn) is the one that has been successfully used for STUN and TURN in NetBird setups.
+- Every machine in the network runs the [NetBird agent](client/), which manages WireGuard.
+- Every agent connects to the [Management Service](management/), which holds network state, manages peer IPs, and distributes updates to agents.
+- Agents use ICE (via [pion/ice](https://github.com/pion/ice)) to discover connection candidates for peer-to-peer connections.
+- Candidates are discovered with the help of [STUN](https://en.wikipedia.org/wiki/STUN) servers.
+- Agents negotiate a connection through the [Signal Service](signal/), exchanging end-to-end encrypted messages with candidates.
+- When NAT traversal fails (e.g. mobile carrier-grade NAT) and a direct p2p connection isn't possible, the system falls back to a [Relay Service](relay/) and a secure WireGuard tunnel is established through it.
- 
+
See a complete [architecture overview](https://docs.netbird.io/about-netbird/how-netbird-works#architecture) for details.
### Community projects
-- [NetBird installer script](https://github.com/physk/netbird-installer)
-- [NetBird ansible collection by Dominion Solutions](https://galaxy.ansible.com/ui/repo/published/dominion_solutions/netbird/)
-- [netbird-tui](https://github.com/n0pashkov/netbird-tui) โ terminal UI for managing NetBird peers, routes, and settings
+- [NetBird installer script](https://github.com/physk/netbird-installer)
+- [netbird-tui](https://github.com/n0pashkov/netbird-tui) - terminal UI for managing NetBird peers, routes, and settings
+- [caddy-netbird](https://github.com/lixmal/caddy-netbird) - Caddy plugin that embeds a NetBird client for proxying HTTP and TCP/UDP traffic through NetBird networks
**Note**: The `main` branch may be in an *unstable or even broken state* during development.
For stable versions, see [releases](https://github.com/netbirdio/netbird/releases).
### Support acknowledgement
-In November 2022, NetBird joined the [StartUpSecure program](https://www.forschung-it-sicherheit-kommunikationssysteme.de/foerderung/bekanntmachungen/startup-secure) sponsored by The Federal Ministry of Education and Research of The Federal Republic of Germany. Together with [CISPA Helmholtz Center for Information Security](https://cispa.de/en) NetBird brings the security best practices and simplicity to private networking.
+In November 2022, NetBird joined the [StartUpSecure program](https://www.forschung-it-sicherheit-kommunikationssysteme.de/foerderung/bekanntmachungen/startup-secure) sponsored by the Federal Ministry of Education and Research of the Federal Republic of Germany. Together with the [CISPA Helmholtz Center for Information Security](https://cispa.de/en), NetBird brings security best practices and simplicity to private networking.
-### Testimonials
-We use open-source technologies like [WireGuardยฎ](https://www.wireguard.com/), [Pion ICE (WebRTC)](https://github.com/pion/ice), [Coturn](https://github.com/coturn/coturn), and [Rosenpass](https://rosenpass.eu). We very much appreciate the work these guys are doing and we'd greatly appreciate if you could support them in any way (e.g., by giving a star or a contribution).
+### Acknowledgements
+We build on open-source technologies like [WireGuardยฎ](https://www.wireguard.com/), [Pion ICE](https://github.com/pion/ice), and [Rosenpass](https://rosenpass.eu). We greatly appreciate the work these projects are doing, and we'd love it if you could support them too (e.g., by starring or contributing).
### Legal
-This repository is licensed under BSD-3-Clause license that applies to all parts of the repository except for the directories management/, signal/ and relay/.
+This repository is licensed under the BSD-3-Clause license, which applies to all parts of the repository except for the directories management/, signal/ and relay/.
Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.
_WireGuard_ and the _WireGuard_ logo are [registered trademarks](https://www.wireguard.com/trademark-policy/) of Jason A. Donenfeld.
-
- 
- 
- 
+
-