About Nebula Commander

Nebula Commander is a self-hosted control plane for Nebula overlay networks.

What it does

  • Networks & nodes — Create networks, manage nodes, IP allocation, and certificates
  • Web UI — React dashboard with OIDC (e.g. Keycloak) or dev token authentication
  • Device client (ncclient) — pip install nebula-commander for enroll and run; see ncclient documentation

Status (as of v0.9.0)

What’s implemented already

  • Networks, nodes, IP allocation, and certificate management — including automatic re-signing when a node’s group changes, no re-enrollment needed
  • Nebula v2 certificates, with P256 as an opt-in curve
  • Firewall group rules, with a visual group access diagram
  • Magic DNS: split-horizon DNS via dnsmasq (Linux/Docker) and NRPT (Windows), with wildcard alias support and automatic detection of the host’s DNS manager on Linux
  • Client UI via web interface — a full React dashboard for networks, nodes, groups, DNS, users, invitations, and the audit log, with a consistent square-card layout across the list pages
  • Subnet routers and exit nodes (Nebula’s unsafe_routes), configurable from both sides: the gateway that advertises a route, and a simple “Use Subnet Router”/“Use Exit Node” picker on any other node that wants to consume one. The gateway’s “Used by” list takes whole groups or individual hosts. On Linux and Windows clients an exit node is a full tunnel with a kill switch and an “Allow local network access” toggle — see Subnet Routers and Exit Nodes
  • Public endpoint on any node, not just lighthouses and relays, added to every peer’s static_host_map so nodes with a known address connect directly, plus additional reachable addresses (port forwards, second uplinks) a node reports to its lighthouses — see Public Endpoints & Reachable Addresses
  • Per-account color theming — every user can customize button, status, badge, and background colors independently for light and dark mode, and save named presets to switch between — see Appearance
  • Device client (ncclient): CLI, native desktop apps for Windows (WinUI 3, with a background service) and Linux (GTK4, as .deb/.rpm/Flatpak), a Docker image, a signed apt/rpm package repository (amd64 and arm64), and NixOS modules (services.ncclient, services.ncclient-desktop), plus mobile support (iOS/Android via the official Mobile Nebula app). Only administrators can change a device’s network settings: an elevated administrator on Windows, the sudo/wheel group on Linux
  • One device in several networks — a device can be enrolled in networks on different servers at once, each with its own Nebula interface and listen port; the desktop apps list every network and show this node’s IP in each
  • Revocation that holds: revoking, deleting or re-enrolling a node blocklists its old certificate on every other node, and nodes keep running from their last config if the server is unreachable — see Nodes
  • Opt-in automatic client updates for Windows and Linux packages (notify-only on NixOS), turned on by an administrator on the device — see Automatic updates. That makes the package repository the recommended install for Linux nodes other than lighthouses
  • Lighthouse-based peer reachability monitoring and node offline detection
  • OIDC (e.g. Keycloak) or dev-token authentication, with step-up reauth required for sensitive actions (deletions, revocations)
  • Two-factor login with any authenticator app, on top of any sign-in provider: optional and encouraged, or required for everyone with one setting — see Security
  • Server moves — move an instance to a new domain, your own server or an IP address and every device follows on its own, after checking the move is genuine — see Move server
  • Audit logging, an invitation system, and multi-user management
  • Encryption at rest for certificates and keys
  • Backup & export — download the whole instance as one passphrase-encrypted file (standard age format) and import it into a fresh instance; devices keep working after a move without re-enrolling — see Backup & export
  • Hosted option — Nebula Commander Cloud if you’d rather not run the server yourself

What’s still planned

  • Automatic host-level route/NAT configuration for Windows subnet routers and exit nodes (Linux and Docker nodes running ncclient already get this automatically; see Subnet Routers and Exit Nodes)
  • Continued client hardening as real-world deployments surface edge cases

Installation options

Configuration

Environment variables use the NEBULA_COMMANDER_ prefix. See Server Configuration and Environment for key options such as DATABASE_URL, CERT_STORE_PATH, JWT_SECRET_KEY (or JWT_SECRET_FILE), OIDC_ISSUER_URL, OIDC_CLIENT_ID, and DEBUG.

License

Backend and frontend: MIT. Client (ncclient): GPLv3 or later. See Getting started: License for details.