Find the right NetBird repository
Start where the behavior is owned. A change that appears to be one dashboard control can also require a management API update, generated client changes, and documentation, so identify the boundaries before you open a pull request.
Repository-local instructions are authoritative. Read CONTRIBUTING.md, AGENTS.md, CLAUDE.md, pull request templates, and workflow files in the target repository before you start.
Common contribution paths
Use these four paths to narrow the search. The detailed maps below explain the ownership boundaries.
- Build the product for the agent, control plane services, networking, and desktop application.
- Improve the experience for the web dashboard and mobile clients.
- Make the docs clearer for product guides, troubleshooting, API pages, navigation, and docs components.
- Extend the ecosystem for operators, infrastructure as code, packaging, and community projects.
Build the product
Most core product work belongs in netbirdio/netbird. This repository contains the agent, CLI, desktop application, management and signaling services, relay, shared protocols, networking code, installers, and end-to-end tests.
Inside the core repository
| Path | Owns |
|---|---|
client/, client/cmd/, client/server/ | Agent lifecycle, CLI, daemon, and background-service behavior |
client/ui/ | The Wails and React desktop application |
client/internal/routemanager/, route/ | Routing and route management across operating systems |
client/firewall/ | Platform firewall backends and rule management |
client/internal/dns/, dns/ | DNS management and resolver behavior |
client/ssh/, client/mdm/, client/system/ | Built-in SSH, MDM-delivered policy handling, and host information |
management/ | Accounts, users, peers, groups, Networks, Policies, setup keys, identity integration, persistence, and the management API |
signal/ | Peer signaling and connection negotiation |
relay/ | Encrypted traffic relay and relay protocol behavior |
proxy/ | The identity-aware proxy used by Agent Network |
client/proto/, shared/management/proto/, shared/signal/proto/, flow/ | Protocol definitions, generated bindings, and flow-event types |
shared/ | Management, signal, relay, authentication, and API types shared across components |
stun/, encryption/, sharedsock/, util/ | Shared connectivity, encryption, socket, and utility primitives |
e2e/ | End-to-end suites and their shared test harness |
infrastructure_files/, release_files/, tools/ | Self-hosting assets, release packaging, and development tooling |
Look at package-level tests and nearby files before changing shared code. A small edit to a protocol, API type, routing primitive, DNS package, authentication helper, or persistence model can affect several binaries and platforms.
Improve the experience
| Area | Repository | Typical changes |
|---|---|---|
| Web dashboard | netbirdio/dashboard | Administration UI, API client usage, forms, tables, permissions, and account workflows |
| Android client | netbirdio/android-client | Android application, VPN service, mobile UI, and Android-specific networking |
| iOS and tvOS client | netbirdio/ios-client | Apple-platform UI, network extension, core submodule integration, packaging, and release builds |
The desktop application is not in a separate UI repository. Its Wails and React source lives under client/ui in netbirdio/netbird.
Mobile repositories combine platform code with core NetBird components. Read their project files, submodule instructions, signing requirements, and CI workflows before choosing a build or test matrix.
Make the docs clearer
Product documentation lives in netbirdio/docs. It includes conceptual and task guides, troubleshooting, the API documentation site, navigation, and reusable MDX components.
For a typo, broken link, or small clarification, open the relevant page on docs.netbird.io, select Edit on GitHub near the bottom, and propose the focused change in your browser. For a larger contribution, fork the repository, create a branch, and follow the documentation build and preview workflow.
Technical docs changes need evidence. Check the current product source, UI, schema, or tested behavior before changing a command, option, default, UI label, port, platform limitation, or version boundary. API pages under src/pages/ipa/resources are generated; update their OpenAPI source and use the documented generator instead of editing the output directly.
Extend the ecosystem
| Area | Repository | Typical changes |
|---|---|---|
| Kubernetes operator | netbirdio/kubernetes-operator | Custom resources, controllers, generated manifests, Helm packaging, and end-to-end cluster behavior |
| Terraform provider | netbirdio/terraform-provider-netbird | Resources, data sources, provider schema, generated reference docs, and acceptance tests |
| NetworkManager plugin | netbirdio/network-manager-vpn-plugin | Linux NetworkManager integration, editor UI, D-Bus behavior, and packaging |
| Helm charts | netbirdio/helms | Kubernetes deployment templates and chart values |
| Home Assistant add-on | netbirdio/addon-netbird | Add-on packaging and Home Assistant deployment behavior |
| Ansible collection | netbirdio/ansible-netbird | NetBird configuration through Ansible modules and roles |
| Community projects list | netbirdio/awesome-netbird | Curated community tools, integrations, and learning resources |
For specialized SDKs, integrations, packaging, and experimental tools, browse the netbirdio organization. Confirm that the repository is active, accepts the kind of contribution you plan to make, and is not a fork, mirror, generated artifact, or example repository.
A repository name does not establish release ownership or contribution policy. Read its local files and recent activity before proposing a broad change, especially in packaging, fork, mirror, or example repositories.
Changes that cross repository boundaries
Plan related work together, but keep each pull request scoped to one repository:
- A management API change can require the core OpenAPI output, dashboard client, Terraform schema, and docs to change together.
- A CLI or configuration change can affect installers, packaging, mobile clients, and documentation.
- A Kubernetes custom resource change can require generated code, CRDs, RBAC, manifests, examples, and operator documentation.
- A dashboard workflow can need core API support and a matching procedural update in the docs.
- A release-format change can affect downstream package and deployment repositories even if their source code does not change.
Link related pull requests and state the expected merge or release order when one depends on another. Test compatible revisions together, and do not copy generated output across repositories without recording its source and generation command.
Before you open a pull request
Confirm these points in the target repository:
- The issue or discussion is current, the direction is agreed when required, and nobody else is already doing the work.
- The default branch and pull request base are correct.
- The repository accepts external changes in the area you plan to edit.
- You know which files are generated and which command updates them.
- You can run the relevant tests without exposing credentials or damaging your normal network environment.
- You understand the pull request template, title format, contribution agreement, license, and sign-off rules that apply there.
Next, use the build and test guide, then work through the pull request checklist.