NetBird for Cloudron

Cloudron app package for NetBird -- a self-hosted WireGuard mesh VPN with SSO, MFA, and granular access controls.

What is NetBird?

NetBird connects devices into a secure peer-to-peer WireGuard mesh network. The entire control plane is open-source and self-hostable.

Feature	Details
Protocol	WireGuard (kernel or userspace)
Architecture	Peer-to-peer mesh (no hub-and-spoke)
NAT traversal	ICE + STUN + built-in relay fallback
Auth	Embedded IdP + any OIDC provider (Cloudron SSO, Keycloak, Google, Entra ID, etc.)
Access control	Group-based policies with posture checks
API	Full REST API + Terraform provider
License	BSD-3 (client), AGPL-3.0 (server)

What this package provides

This Cloudron app packages the NetBird combined server (v0.65.3+), which includes:

• Management API -- peer registry, ACLs, setup keys, network routes
• Signal server -- WebRTC ICE negotiation for P2P connection setup
• Relay server -- fallback for peers behind strict NAT
• STUN server -- NAT type detection (UDP 3478)
• Embedded IdP -- built-in user management (Dex) with /setup onboarding page
• Dashboard -- web UI for administration

NetBird clients connect to this server to join the mesh.

Requirements

Resource	Minimum
Cloudron	v7.6.0+
Memory	512 MB (configurable in manifest)
Ports	TCP 80/443 (handled by Cloudron) + UDP 3478 (STUN, exposed via udpPorts)

Important: UDP port 3478 must be accessible from all NetBird clients for NAT traversal.

Installation

From source (development)

# Install Cloudron CLI
npm install -g cloudron

# Login to your Cloudron instance
cloudron login my.cloudron.example

# Clone and build
git clone https://github.com/marcusquinn/cloudron-netbird-app.git
cd cloudron-netbird-app
cloudron build

# Install
cloudron install --location netbird

From Cloudron App Store

Not yet available. See Contributing if you'd like to help get it there.

First Run

1. Open https://netbird.your-cloudron.example in your browser
2. You'll be redirected to the setup page (/setup)
3. Create your admin account (email + password)
4. Log in with the credentials you just created
5. Navigate to Setup Keys to create a key for connecting devices
6. Install the NetBird client on your devices and connect:

# Install client
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect to your self-hosted management server
sudo netbird up \
  --setup-key YOUR_SETUP_KEY \
  --management-url https://netbird.your-cloudron.example

The /setup page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.

Adding Cloudron SSO (Optional)

After initial setup, you can add Cloudron as an external identity provider so users can log in with their Cloudron credentials.

The manifest sets optionalSso: true, so Cloudron shows an "Enable SSO" toggle during installation. SSO must be enabled at install time (or via reconfigure) for the CLOUDRON_OIDC_* environment variables to be available.

1. Ensure SSO is enabled for the app (Cloudron dashboard > App Settings > Enable SSO)
2. Log into the NetBird dashboard with your admin account
3. Go to Settings > Identity Providers > Add Identity Provider
4. Select Generic OIDC and fill in:
   • Name: Cloudron
   • Issuer: Run cloudron exec --app netbird -- printenv CLOUDRON_OIDC_ISSUER
   • Client ID: Run cloudron exec --app netbird -- printenv CLOUDRON_OIDC_CLIENT_ID
   • Client Secret: Run cloudron exec --app netbird -- printenv CLOUDRON_OIDC_CLIENT_SECRET
5. Save -- the login page will now show a "Cloudron" button alongside local email/password

Notes:

• Local email/password authentication remains available alongside Cloudron SSO
• Multiple identity providers can coexist (Cloudron + Google + Keycloak, etc.)
• NetBird supports JWT group sync for mapping Cloudron groups to access control groups

Architecture

Cloudron Server
+-------------------------------------------------------+
|  Cloudron nginx (TLS termination, port 443)            |
|    |                                                   |
|    v                                                   |
|  +---------------------------------------------------+ |
|  | App Container (this package)                       | |
|  |                                                    | |
|  |  nginx :8080 (internal reverse proxy)              | |
|  |    |-- /signalexchange/  -> gRPC :80 (grpc_pass)   | |
|  |    |-- /management/      -> gRPC :80 (grpc_pass)   | |
|  |    |-- /relay, /ws-proxy -> WebSocket :80           | |
|  |    |-- /api, /oauth2     -> HTTP :80                | |
|  |    |-- /* (incl /setup)  -> dashboard (static SPA)  | |
|  |                                                    | |
|  |  netbird-server :80 (combined binary)              | |
|  |    Management + Signal + Relay + embedded IdP      | |
|  |    STUN :3478/udp (exposed directly)               | |
|  |                                                    | |
|  +---------------------------------------------------+ |
|                                                        |
|  PostgreSQL addon (Cloudron-managed)                   |
+-------------------------------------------------------+

Configuration

All configuration is generated at runtime by start.sh. There are no config files to edit manually -- the app reads Cloudron environment variables and writes config.yaml, nginx.conf, and dashboard config files on each start.

Database

Uses Cloudron's PostgreSQL addon automatically. No manual database setup required.

Identity Provider

Built-in: NetBird's embedded IdP (Dex) handles initial setup and local user management. The /setup page creates the first admin account.

Optional: Cloudron SSO or any OIDC provider can be added via the dashboard after initial setup. Multiple providers can coexist. See Adding Cloudron SSO.

Health Check

The manifest uses /api/accounts as the health check endpoint. This is served by the management API through the internal nginx proxy. The combined server also exposes a health endpoint on port 9000, but that port is not routed through nginx.

Persistent Data

All persistent data is stored in /app/data/ (Cloudron's localstorage addon) and included in Cloudron backups:

Path	Contents
/app/data/config/config.yaml	Combined server configuration (regenerated on each start)
/app/data/config/nginx.conf	Internal nginx configuration (regenerated on each start)
/app/data/config/.encryption_key	Database encryption key (generated on first run, persisted)
/app/data/config/.auth_secret	Relay authentication secret (generated on first run, persisted)
/app/data/netbird/	Server state and data
/app/data/dashboard/	Dashboard OIDC config (config.json, .env)
/app/data/.initialized	First-run marker file

The encryption key encrypts setup keys and API tokens at rest in PostgreSQL. Both .encryption_key and .auth_secret are included in Cloudron backups. Do not lose them -- losing the encryption key means regenerating all setup keys and API tokens, while losing the auth secret may disrupt relay server authentication.

Development

# Build and install
cloudron build
cloudron install --location netbird

# Iterate after changes
cloudron build && cloudron update --app netbird

# View logs
cloudron logs -f --app netbird

# Shell into the container
cloudron exec --app netbird

# Debug mode (writable filesystem)
cloudron debug --app netbird

# Uninstall
cloudron uninstall --app netbird

Testing Checklist

• Fresh install completes without errors
• Dashboard loads at app URL
• /setup page appears on first run (no users exist)
• Admin account creation works via setup page
• Login with created credentials works
• Setup key creation works in dashboard
• Client connects with setup key and management URL
• Peers can ping each other through the mesh
• Peers behind NAT connect via relay
• gRPC connections work (signal + management)
• WebSocket connections work (relay + ws-proxy)
• App survives restart (cloudron restart --app netbird)
• Backup/restore preserves all state
• Memory stays within 512 MB limit
• STUN port (UDP 3478) is accessible from clients
• (Optional) Cloudron SSO can be added as external IdP via dashboard

File Structure

cloudron-netbird-app/
  CloudronManifest.json    # Cloudron app metadata and addon requirements
  Dockerfile               # Build instructions (downloads netbird-server + dashboard)
  start.sh                 # Runtime entry point (config generation, process launch)
  supervisord.conf         # Process management (nginx + netbird-server)
  logo.png                 # App icon (256x256)
  PACKAGING-NOTES.md       # Architecture decisions, lessons learned, testing plan
  CHANGELOG.md             # Version history
  CONTRIBUTING.md          # Contribution guidelines
  LICENSE                  # MIT
  .editorconfig            # Editor formatting rules

Known Limitations

1. STUN port: UDP 3478 must be directly accessible -- it cannot go through Cloudron's HTTP reverse proxy. Ensure your firewall allows inbound UDP 3478.
2. Reverse proxy feature not supported: NetBird's Reverse Proxy feature requires Traefik with TLS passthrough, which is incompatible with Cloudron's nginx TLS termination. See the TLS passthrough feature request on the Cloudron forum. All core mesh VPN functionality (P2P tunnels, NAT traversal, access control, DNS, routes, dashboard) works normally.
3. Single account mode: All users join the same network. This is appropriate for most self-hosted deployments.
4. Not yet tested on a real Cloudron instance: This package needs real-world validation. See Contributing.

Upstream

• NetBird: https://github.com/netbirdio/netbird
• NetBird Docs: https://docs.netbird.io
• NetBird Self-Hosting: https://docs.netbird.io/selfhosted/selfhosted-quickstart
• NetBird Configuration: https://docs.netbird.io/selfhosted/configuration-files
• NetBird External Reverse Proxy: https://docs.netbird.io/selfhosted/external-reverse-proxy

Contributing

Contributions are welcome. The main areas that need work:

1. Testing on a real Cloudron instance -- the packaging needs real-world validation
2. Auth flow testing -- verify the embedded IdP setup page and login work end-to-end
3. gRPC/WebSocket testing -- verify signal and management connections work through the nginx proxy
4. App Store submission -- once tested, submit to the Cloudron App Store

Submitting to the Cloudron App Store

1. Test thoroughly on a real Cloudron instance
2. Post on the Cloudron forum packaging category to request a project on git.cloudron.io
3. The Cloudron team creates a repo under git.cloudron.io/packages/netbird-app
4. Push the package and submit for review

Note: git.cloudron.io does not allow personal project creation. The Cloudron team manages the packages/ namespace.

License

This Cloudron app package is licensed under the MIT License.

NetBird itself is licensed under BSD-3 (client) and AGPL-3.0 (server). See the NetBird repository for details.