Nebula Commander

Docker

Mon, 01 Jan 0001 00:00:00 +0000

The Docker client is the preferred method for the first lighthouse in a network so the container can run dnsmasq and you can use Magic DNS (split-horizon DNS) for the network. Other devices (CLI, a native GUI app, or additional Docker clients) can then resolve Nebula hostnames via the lighthouse.

Image: ghcr.io/nebula-commander/nebula-commander-ncclient:latest, or build from the repo client/docker (Dockerfile in that directory).

Required environment:

NEBULA_COMMANDER_SERVER – Base URL of your Nebula Commander backend (e.g. https://nc.example.com), no trailing slash.

Optional environment:

Docker

Mon, 01 Jan 0001 00:00:00 +0000

Run Nebula Commander with Docker using pre-built images or a local build. You can download all required files without cloning the repository. For HTTPS and HSTS at the edge (Nginx, Traefik, or Caddy in front of the frontend container), see Reverse Proxy.

Downloading files

You need: docker-compose.yml, docker-compose-keycloak.yml, .env.example, and the env.d.example/ directory (backend and Keycloak config). Either use the commands below or the provided script.

Using curl

Run these in an empty directory (or where you want the Docker setup):

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

All backend settings use the NEBULA_COMMANDER_ prefix. Set them in the environment or in a file (e.g. docker/env.d/backend). Optional values can be omitted; defaults apply.

Application

Variable	Description	Default
`NEBULA_COMMANDER_DEBUG`	Enable debug mode (enables dev-token endpoint; do not use in production)	`false`
`NEBULA_COMMANDER_API_DOCS_ENABLED`	From v0.9.0. Serve the interactive API docs at `/api/docs` (Swagger UI) and `/api/redoc`, with the schema at `/api/openapi.json`. Every API endpoint still requires authentication either way; set to `false` to hide the endpoint list and the server version from anyone who can reach the server. NixOS: `services.nebula-commander.apiDocs`.	`true`
`NEBULA_COMMANDER_UPDATE_CHECK_ENABLED`	Check GitHub for a newer release, shown as a notification in the About screen. Set to `false` to disable all outbound calls to github.com (air-gapped/privacy-conscious deployments).	`true`

Database

Variable	Description	Default
`NEBULA_COMMANDER_DATABASE_URL`	Database URL (SQLite: use four slashes for absolute path, e.g. `sqlite+aiosqlite:////var/lib/nebula-commander/db.sqlite`)	`sqlite+aiosqlite:////var/lib/nebula-commander/db.sqlite`
`NEBULA_COMMANDER_DATABASE_PATH`	Override for SQLite path	—
`NEBULA_COMMANDER_CERT_STORE_PATH`	Directory for CA and host certificates	`/var/lib/nebula-commander/certs`

Encryption at rest

Required. The backend refuses to boot if this is left at a placeholder/unset value — unlike most settings here, there’s no insecure-but-working default.

ncclient CLI

Mon, 01 Jan 0001 00:00:00 +0000

This page covers the plain ncclient command from the binaries or Pip, run by hand or under your own init system. If you installed the Linux packages, the Windows MSI, or the NixOS module, use the Linux App, Windows App, or NixOS page instead. Those set up a background service that keeps its state somewhere the plain CLI doesn’t look.

Where state lives

What	Default location
Device tokens (one per network)	The OS keyring, when there is a usable one (normally only in a logged-in desktop session). Otherwise files in `~/.nebula/tokens/`, readable only by their owner. That’s what root, servers, SSH sessions, and the frozen binaries get. Set `NEBULA_DEVICE_TOKEN_FILE` to a file path, and the tokens go in a `tokens/` folder next to it.
`settings.json` (each network’s server, node ID, accepted routes)	`~/.config/nebula-commander/` on Linux and macOS, `%APPDATA%\nebula-commander\` on Windows. Set `NEBULA_COMMANDER_CONFIG_DIR` to change it.
Nebula config and certificates	`networks/<id>/` under the output directory: `/etc/nebula` on Linux and macOS, `%USERPROFILE%\.nebula` on Windows. Set with `--output-dir`.

Before v0.8.0 there was one token (~/.nebula/device-token) and the Nebula files were directly in the output directory. ncclient moves them into this layout the first time v0.8.0 or newer runs.

Networks

Mon, 01 Jan 0001 00:00:00 +0000

The Networks page shows every Nebula network you can access as a grid of square cards, and lets you create networks. Each network has a name and a subnet (CIDR) used for IP allocation to nodes.

Light	Dark

Click a network’s card to open its detail view: node/user/group counts and the Group Access Diagram, a live visualization of which groups can reach which (see Groups for what restricted vs. open means).

Development Setup

Mon, 01 Jan 0001 00:00:00 +0000

Run the backend and frontend locally for development.

Backend

From the nebula-commander repository root:

python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r backend/requirements.txt
export NEBULA_COMMANDER_DATABASE_URL="sqlite+aiosqlite:///./backend/db.sqlite"
export NEBULA_COMMANDER_CERT_STORE_PATH="./backend/certs"
# Required — the backend refuses to boot without it. Generate one:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
export NEBULA_COMMANDER_ENCRYPTION_KEY="your-fernet-key-here"
export NEBULA_COMMANDER_DEBUG=true
python -m uvicorn backend.main:app --reload --port 8081

Use a real JWT secret in production; for local dev, NEBULA_COMMANDER_DEBUG=true enables the dev-token endpoint. Every backend setting uses the NEBULA_COMMANDER_ prefix — a bare DEBUG=true without it is silently ignored.

Signing up

Mon, 01 Jan 0001 00:00:00 +0000

Setting up takes a few minutes. Your instance is created automatically as soon as payment goes through.

1. Choose a name and plan

Go to cloud.nebulacdr.net/signup and fill in:

Email: this account becomes the administrator of your instance.
Organization or project name.
Subdomain: your instance’s address, for example acme for acme.nebulacdr.net. Use 3–32 lowercase letters, digits and hyphens. The form tells you straight away if a name is taken or reserved.
Plan: Hosted at the standard price, or Name your own price. For the second, enter your monthly amount (at least the minimum shown) or pick one of the suggested amounts.

Accept the Terms of Service, then click Continue to payment. Your subdomain is held for you while you complete checkout.

Binaries

Mon, 01 Jan 0001 00:00:00 +0000

If Docker is not an option, use binaries from the Web UI or GitHub Releases.

From Web UI

When your Nebula Commander instance is deployed with client binaries included (for example the frontend image built with DOWNLOAD_BINARIES=1), the Web UI can serve them.

Open your Nebula Commander URL in a browser and log in.
Go to the downloads or client section (or open https://YOUR_SERVER/downloads/ if your instance serves that path).
Download the binary for your platform:
- Linux x86_64: ncclient-linux-amd64
- Linux ARM64: ncclient-linux-arm64
- Windows x86_64: ncclient-windows-amd64.exe
- macOS Intel: ncclient-macos-amd64
- macOS Apple Silicon: ncclient-macos-arm64
Place the file in a directory on your PATH (or add that directory to PATH). On Linux and macOS, make it executable: chmod +x ncclient-linux-amd64 (or the file you downloaded).

If your instance does not serve binaries, use From releases or Pip (PyPI) instead.

Docker

Mon, 01 Jan 0001 00:00:00 +0000

The Docker client runs ncclient, Nebula, and (on lighthouses) dnsmasq in one container. See Docker installation for the image and a full docker-compose.yml. The commands below assume that compose file, with the service named ncclient, run from the directory that holds it.

Where state lives

Everything that must survive a container recreate lives in the /data volume, as long as the compose file sets these two paths (the example does):

NEBULA_OUTPUT_DIR: "/data/nebula"
NEBULA_DEVICE_TOKEN_FILE: "/data/nebula-commander/token"

Path in the container	What it is
`/data/nebula-commander/tokens/`	Device token (from v0.8.0, one file per network, named by its id)
`/data/nebula-commander/settings.json`	Server URL, node ID, accepted routes
`/data/nebula/networks/<id>/`	Nebula `config.yaml`, certificates, status

Before v0.8.0 the token was /data/nebula-commander/token and the Nebula files were directly in /data/nebula/. The container moves them into this layout on its first start with v0.8.0 or newer; the variables stay the same.

GitHub Actions

Mon, 01 Jan 0001 00:00:00 +0000

Nebula Commander uses two GitHub Actions workflows: one to build ncclient binaries (and create releases), and one to build and push Docker images.

Build ncclient Binaries

Workflow file: .github/workflows/build-ncclient-binaries.yml

Triggers

Version tags – Push a tag matching v* (e.g. v0.1.5) to build all binaries and create a GitHub Release. This is the only trigger that produces a release; there is no trigger on push to main.
Pull requests – Runs when changes touch client/binaries/**, client/windows/**, client/ncclient.py, installer/windows/**, or the workflow file itself.
Manual – Use “Run workflow” in the Actions tab (workflow_dispatch).

Platforms built

Platform	Artifact name
Linux x86_64	`ncclient-linux-amd64`
Linux ARM64	`ncclient-linux-arm64`
Windows x86_64	`ncclient-windows-amd64.exe`
macOS Intel	`ncclient-macos-amd64`
macOS ARM64 (Apple Silicon)	`ncclient-macos-arm64`

Windows ARM64 is not built (GitHub has no Windows ARM64 runners). Linux ARM64 is built in Docker with QEMU on the host runner.

Groups

Mon, 01 Jan 0001 00:00:00 +0000

The Groups page lets you define Nebula security groups and their inbound firewall rules per network. Groups are used by nodes (each node has one group). Firewall rules control which other groups can send traffic to this group and on what protocol and ports.

Light	Dark

Selecting a network

At the top of the Groups page, choose a network from the dropdown. Groups and rules are per network. Only networks you have access to appear in the list.

Managing your membership

Mon, 01 Jan 0001 00:00:00 +0000

Signing in to your account

Your account at cloud.nebulacdr.net is where you manage billing. It’s separate from your instance, which you use at your-name.nebulacdr.net.

Go to cloud.nebulacdr.net/login and enter the email you signed up with.
Open the sign-in link we email you. It expires after 15 minutes.

The account page lists your instances with their status and current price.

Updating your card and downloading invoices

On the account page, click Manage billing. This opens Stripe’s secure billing page, where you can:

NixOS

Mon, 01 Jan 0001 00:00:00 +0000

Run Nebula Commander as a NixOS service by adding the module and enabling the service. You can add the module from a local path (clone) or, when available, from a flake.

Adding the module (path-based, no flake)

Use this when you have the nebula-commander repository on disk (for example under /etc/nixos or a path you manage).

1. Get the repository

Clone or copy the nebula-commander repo so that the path contains both nix/ and backend/:

OIDC Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Nebula Commander can use OpenID Connect (OIDC) for login. Keycloak is supported with a pre-configured setup; other OIDC providers (Authentik, Auth0, etc.) work with the same environment variables.

Required variables

Set these in env.d/backend (Docker) or in the backend environment:

NEBULA_COMMANDER_PUBLIC_URL – URL where users reach the app (FQDN or host:port). The redirect URI is derived as PUBLIC_URL + /api/auth/callback if you do not set OIDC_REDIRECT_URI.
NEBULA_COMMANDER_OIDC_ISSUER_URL – Issuer URL used by the backend to talk to the provider. Inside Docker use the container name and container port (e.g. http://keycloak:8080/realms/nebula-commander). Do not use the host-mapped port here.
NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL – Issuer URL as seen by the browser (FQDN or host:port). Use the same URL users would use to open the provider’s login page.
NEBULA_COMMANDER_OIDC_CLIENT_ID – OIDC client ID (e.g. nebula-commander).
NEBULA_COMMANDER_OIDC_CLIENT_SECRET – Client secret from the provider. Prefer NEBULA_COMMANDER_OIDC_CLIENT_SECRET_FILE in production.

Optional: NEBULA_COMMANDER_OIDC_REDIRECT_URI – Override only if you need a callback URL different from PUBLIC_URL + /api/auth/callback.

DNS

Mon, 01 Jan 0001 00:00:00 +0000

The DNS page configures split-horizon DNS per network: a domain and optional hostname aliases that resolve to nodes inside the Nebula overlay. When enabled, lighthouses (or the Docker ncclient stack) can run dnsmasq to serve this domain; enrolled devices can use ncclient with --accept-dns to resolve the Nebula domain via the overlay.

Light	Dark

Access

Only network owners can view or change DNS for a network. Select a network from the dropdown at the top; the page shows the current DNS config and aliases for that network.

Linux Desktop App

Mon, 01 Jan 0001 00:00:00 +0000

On Linux, three packages give you a GTK4/libadwaita desktop app plus a background systemd service that does the actual work - no group membership or relogin needed, and no admin/root prompt for enrolling, starting/stopping, or accepting routes.

Light	Dark

What’s included:

nebula-commander-client – The ncclient CLI (frozen binary, no Python runtime needed).
nebula-commander-service – Installs ncclient.service (systemd), which polls for config/certs and runs Nebula as root. Exposes a system D-Bus API (org.beardedtek.NebulaCommander1) that the desktop app talks to, authorized per-call via polkit.
nebula-commander-desktop – The GTK4 app: enroll, view connection/service status, and accept or reject offered subnet routes and exit nodes.

Any user logged in at the machine can view status in the desktop app. Changes (enrolling, settings, routes, exit node, starting/stopping the service) need no password for members of the sudo or wheel group, which administrators normally already are, and an administrator’s password for everyone else.

Subnet Routers and Exit Nodes

Mon, 01 Jan 0001 00:00:00 +0000

Nebula Commander can turn a node into a subnet router (it advertises a LAN behind it to the rest of the mesh, the way tailscale up --advertise-routes does) or an exit node (it advertises 0.0.0.0/0/::/0 and routes all of another node’s traffic, the way tailscale up --advertise-exit-node does). Both build on Nebula’s own unsafe_routes feature.

This page covers how it’s configured from both sides — the gateway that advertises a route, and the other nodes that actually use it — what happens automatically for nodes running ncclient on Linux, and — the part that’s easy to miss — what you have to do yourself for everything else (Windows, macOS, Docker-deployed ncclient, or bare nebula).

Public Endpoints and Reachable Addresses

Mon, 01 Jan 0001 00:00:00 +0000

Nebula finds most nodes on its own: each node reports the addresses of its local interfaces to the lighthouses, and the lighthouses also see the address a node connects to them from. Three optional per-node settings cover what that misses. They reach other nodes by different paths, so they’re separate fields. A fourth setting, the listen port, is the UDP port the node itself binds.

	Public endpoint	Additional endpoints	Additional reachable addresses
Where to set it	Node details panel	Node details panel, once a public endpoint is set	Node details → Advanced
Values	One `host:port` (hostname, IPv4, or `[IPv6]`)	Up to 8 `host:port`, added one at a time	Up to 8 `IP:port`, added one at a time
Nebula setting	Every peer’s `static_host_map`	Every peer’s `static_host_map`, after the public endpoint	This node’s own `lighthouse.advertise_addrs`
How other nodes learn it	Written into their config	Written into their config	Reported to the lighthouses, which pass it on
Lighthouses and relays	Need one	Allowed	Not shown (Nebula ignores it on lighthouses)
Changing it restarts Nebula on	Every node on the network	Every node on the network	That node only

They can be used together: the endpoints let peers reach a node without asking a lighthouse first, and the additional reachable addresses fill in paths the lighthouses can’t see.

Manual Builds

Mon, 01 Jan 0001 00:00:00 +0000

You can build all ncclient binaries, the Windows service and app, the Windows MSI, the Linux .deb/.rpm/Flatpak packages, and the Docker images locally without using GitHub Actions.

ncclient CLI (standalone binary)

The CLI is built with PyInstaller from client/binaries/. Python 3.11 is used in CI.

Same platform (Linux x86_64, Windows x86_64, macOS)

From the repository root:

pip install -r client/binaries/requirements.txt
pip install -r client/requirements.txt
cd client/binaries
python build.py

Output: client/binaries/dist/ncclient (or ncclient.exe on Windows). Use python build.py --clean to remove build artifacts; python build.py --test to build and run basic tests.

Running Nebula manually

Mon, 01 Jan 0001 00:00:00 +0000

This is the manual method: you use Nebula Commander to create networks, nodes, and certificates, then run Nebula on devices yourself without ncclient. Config and certs are copied or downloaded from the UI (or API) and you start Nebula manually. Use this when you prefer to deploy config and certs yourself or when ncclient is not available (e.g. on mobile).

When to use this

You prefer to deploy config and certs yourself (copy to the device, run nebula -config ...).
You do not want to enroll devices or run the ncclient daemon.
You are fine updating config and certs manually when the network or node changes (re-download from the UI or API and replace files, then restart Nebula).

With ncclient, the device enrolls once and ncclient polls for config and certs and can run or restart Nebula automatically. With manual setup, you handle file deployment and restarts yourself.

NixOS

Mon, 01 Jan 0001 00:00:00 +0000

This page covers day-to-day use of the services.ncclient module. See NixOS installation for importing the module and its full option list. Paths below use the defaults (stateDir = "/var/lib/ncclient", outputDir = "/var/lib/ncclient/nebula"); adjust them if you changed those options.

What the module sets up

ncclient.service: runs ncclient run as root, with nebula from nebulaPackage, plus nftables and iproute2 (for subnet-router/exit-node forwarding and NAT), on its PATH. It restarts on failure.
ncclient-enroll.service: only when enrollCodeFile or networks is set. A oneshot that runs ncclient enroll before the main service, once per network: after enrolling it writes a marker file (/var/lib/ncclient/.enrolled-<name>) and never sends that network’s code again.
The D-Bus policy and polkit rules the Linux desktop app uses, if you also enable services.ncclient-desktop. Only members of adminGroups (default wheel/sudo) can make changes without a password.
An ncclient command on the system PATH, pre-pointed at the service’s state. See Running ncclient commands.

Where state lives

Path	What it is
`/var/lib/ncclient/tokens/`	One device token per network
`/var/lib/ncclient/settings.json`	Each network’s server, node ID and accepted routes
`/var/lib/ncclient/.enrolled-<name>`	Marker: the enroll unit has enrolled network `<name>`
`/var/lib/ncclient/nebula/networks/<id>/`	Each network’s Nebula `config.yaml`, certificates, status

Both directories are 0700 root:root. Before v0.8.0 the token was /var/lib/ncclient/token and the Nebula files were directly in nebula/; ncclient moves them into this layout on its first start.

Nodes

Mon, 01 Jan 0001 00:00:00 +0000

The Nodes page shows every node across networks (or filtered to one network) as a grid of square cards. You create nodes, assign IPs and groups, create or sign certificates, generate enrollment codes for ncclient, download config, and — new since v0.3.7 — pick which other node each one should route through as a subnet router or exit node.

Light	Dark

The node grid

Each card is color-coded by status — never checked in, active, or inactive — and carries a bottom-right badge cluster: Lighthouse, Relay, and a type/OS badge (iOS, Android, Windows, Linux, macOS, or a generic Node fallback until the platform is known). Hostname and IP sit at the top of the card, always drawn above the badges so a long badge row can never hide them, even on a narrow phone screen. Click a card to open its details panel:

Reverse Proxy

Mon, 01 Jan 0001 00:00:00 +0000

Nebula Commander is typically run behind a reverse proxy such as Nginx, Traefik, or Caddy. The frontend and backend containers listen on plain HTTP inside Docker; your reverse proxy:

Terminates TLS on port 443 with a certificate
Proxies requests to the frontend container (and through it to the backend)
Adds security headers like Strict-Transport-Security (HSTS)

This page shows recommended HSTS settings and example reverse proxy configurations.

HSTS and HTTPS

For best security, configure HTTPS and HSTS on your reverse proxy, not inside the containers. That lets you choose the right TLS policy for your environment (LAN-only, VPN-only, or Internet-facing).

Windows Installer

Mon, 01 Jan 0001 00:00:00 +0000

On Windows the MSI installer sets up the ncclient CLI, a native windowed app, and a background Windows Service that does the actual work as LocalSystem. Any user can view status in the app; enrolling, changing settings or routes, and starting/stopping the service require running the app as administrator.

What the installer includes:

ncclient – CLI for enrollment and daemon (poll for config/certs, run or restart Nebula).
Nebula Commander (WinUI 3) – The windowed desktop app: side tabs for Status, Enrollment, and Settings, minimizes to the tray on close. Talks to the background service.
ncclient-service – The NebulaCommanderService Windows Service that polls for config/certs and runs Nebula as LocalSystem. Starts automatically at boot; the app talks to it over a local named pipe.

All three are installed to %ProgramFiles%\Nebula Commander\. The installer can add that directory to PATH, creates Start Menu shortcuts, and registers/starts the service.

API

Mon, 01 Jan 0001 00:00:00 +0000

The Nebula Commander backend exposes a REST API under the base path /api. All routes are prefixed with /api. Most endpoints require a valid JWT in the Authorization: Bearer <token> header unless noted otherwise.

OpenAPI docs

The backend serves interactive documentation at:

Swagger UI – /api/docs
ReDoc – /api/redoc
OpenAPI schema – /api/openapi.json

For full request/response schemas and parameters, use the interactive docs. They’re on by default; set NEBULA_COMMANDER_API_DOCS_ENABLED to false (NixOS: apiDocs = false;) to turn all three off. Before v0.9.0 the docs pages loaded the schema from /openapi.json, which a reverse proxy usually sends to the frontend, so they didn’t render.

Client Download

Mon, 01 Jan 0001 00:00:00 +0000

The Client Download page (also reachable from the sidebar or at /client-download) lets users download ncclient binaries served directly from your Nebula Commander instance. No internet access to GitHub is required after deployment.

Light	Dark

Purpose

Install and run ncclient on a device to enroll with Nebula Commander and pull config and certificates. The enrollment code is obtained from the Nodes page (Enroll button for the node). The page is organized into tabs (Docker, Linux, Windows, macOS, Mobile) and provides the CLI for every platform, the Linux desktop app packages, and the Windows installer. Commands on the page are filled in with this instance’s own URL, so they can be pasted as-is.

Linux App

Mon, 01 Jan 0001 00:00:00 +0000

Light	Dark

On Linux, Nebula Commander (GTK4/libadwaita) is an unelevated desktop app for the background ncclient systemd service. The service does the actual work (polling for config and certs, running Nebula) as root, and exposes a system D-Bus API (org.beardedtek.NebulaCommander1) that the app talks to, authorized per call via polkit.

Anyone can view; administrators change. Any user logged in at the machine can see status and offered routes. Enrolling, changing settings, accepting routes or exit nodes, and starting/stopping the service work without a password for members of the sudo (Debian/Ubuntu) or wheel (Fedora/openSUSE/Arch) group. Anyone else needs an administrator’s password, so other users of a shared machine can’t re-point or stop the tunnel. Remote (SSH) sessions get nothing through the app’s API; use sudo on the command line instead.

NixOS

Mon, 01 Jan 0001 00:00:00 +0000

A services.ncclient module runs ncclient declaratively as a systemd service — an alternative to the Docker image, the Windows service, or a hand-written unit (see ncclient CLI: Run as a service). It’s exposed by the same flake.nix as the server module, as nixosModules.client.

{
 inputs.nebula-commander.url = "github:nebula-commander/nebula-commander";

 outputs = { self, nixpkgs, nebula-commander, ... }: {
 nixosConfigurations.yourHost = nixpkgs.lib.nixosSystem {
 system = "x86_64-linux";
 modules = [
 ./configuration.nix
 nebula-commander.nixosModules.client
 ];
 };
 };
}

Or import nix/client-module.nix directly by path if you’re not using a flake, the same way the server module can be.

Invitations

Mon, 01 Jan 0001 00:00:00 +0000

The Invitations page lets network owners (and system admins) invite users to a network with a chosen role and permissions. Invitations work when OIDC is configured; invited users sign in via the IdP and then gain access to the specified network.

Light	Dark

What invitations are

An invitation associates an email (or link) with a network, a role (e.g. member, admin), and optional permissions (can manage nodes, can invite users, can manage firewall). The invitee accepts by clicking a link or using a token; after acceptance they appear as a user with access to that network according to the role and permissions.

Pip (PyPI)

Mon, 01 Jan 0001 00:00:00 +0000

For advanced users only. Pip is the most delicate way to install ncclient. It’s easy to end up with a setup that sudo can’t find, that root can’t safely run, or that stores the token somewhere the service doesn’t look. Use the Linux packages, the Windows installer, Docker, or the binaries unless you need to run from source or none of those fit.

From PyPI:

pip install nebula-commander

Requires Python 3.10+. This installs the ncclient command.

Windows App

Mon, 01 Jan 0001 00:00:00 +0000

On Windows, Nebula Commander (WinUI 3) is a native windowed app for a background Windows Service (NebulaCommanderService). The service does the actual work (polling for config and certs, running Nebula, applying split-horizon DNS) as LocalSystem.

Anyone can view; only administrators can change. Run normally, the app is view-only: status, routes and config are visible to every user. Enrolling, changing settings, accepting routes or exit nodes, installing/updating Nebula, and starting/stopping the service all require an elevated administrator. Use the Relaunch as administrator bar at the top of the app (or press Alt+R; one UAC prompt), or start it with Run as administrator. The service enforces this itself on every change, so other users on a shared PC can’t re-point or stop your tunnel.

Several networks on one device

Mon, 01 Jan 0001 00:00:00 +0000

From v0.8.0, one device can be in several networks at once, for example your own network plus a customer’s. The networks can be on the same Nebula Commander server or on different ones. You enroll once per network, with a code from that network’s Nebula Commander, and the one ncclient on the device runs them all.

Each network gets its own Nebula process on its own interface, with its own token, config, certificates, routes and DNS. The desktop apps list them on a Networks page.

Users

Mon, 01 Jan 0001 00:00:00 +0000

The Users page (sidebar → Users) lists every user account in Nebula Commander as a grid of square cards. It’s visible only to system admins — everyone else never sees this link.

Light	Dark

The user grid

Each card shows a user’s email, their system role badge (system-admin in red, user in gray), whether they use two-factor login (2FA on or No 2FA), and how many networks they belong to. Click a card to open its details.

Security (two-factor login)

Mon, 01 Jan 0001 00:00:00 +0000

From v0.9.0, every account can add two-factor authentication (2FA): after signing in as usual, Nebula Commander asks for a 6-digit code from an authenticator app on your phone. Someone who learns your password, or gets into your identity provider account, still can’t get in without that code.

It works with any authenticator app that supports standard time-based codes (TOTP): Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, Aegis, Proton Pass and so on. It also works with any sign-in method (Keycloak or another OIDC provider, or the standalone dev-token login), because Nebula Commander checks the code itself.

Backup & export

Mon, 01 Jan 0001 00:00:00 +0000

The Backup & export page (sidebar → Backup & export) lets a system admin download everything in a Nebula Commander instance as one encrypted file, and import such a file into a new instance. Use it to:

keep an offline backup,
move from hosted Nebula Commander to your own server (or the other way round),
move a self-hosted instance to new hardware.

Only system admins see this page, and both export and import ask you to sign in again before they run.

Move server

Mon, 01 Jan 0001 00:00:00 +0000

From v0.9.0, a system admin can move a Nebula Commander instance to a new address, and enrolled devices switch to the new server by themselves, with no re-enrollment and no editing of each device. Typical moves:

https://nebulacdr.net to https://beardedtek.nebulacdr.net
Nebula Commander Cloud to your own domain, your own server, or an IP address (leaving Cloud)
an old server to new hardware with a new hostname

Both servers run side by side for a while: the old one tells devices where to go, and they move over during that time.

Appearance

Mon, 01 Jan 0001 00:00:00 +0000

The Appearance page (sidebar → Appearance, or /settings/appearance) lets each user customize the colors used across Nebula Commander — this is a personal preference, saved to your own account, not a site-wide setting an admin controls.

Light	Dark

Every color you pick automatically gets a readable, contrast-checked foreground: buttons, badges, status cards, and the page/container backgrounds all compute their own text color (near-black or near-white) from whatever background you choose, so an unusually light or dark pick never turns into illegible same-on-same text.

Automatic updates

Mon, 01 Jan 0001 00:00:00 +0000

From v0.7.0, the client can keep itself up to date. It’s off by default, and only an administrator on the device itself can turn it on. The Nebula Commander server shows each node’s client version and whether automatic updates are on, but can’t change the setting.

Install	What “on” does
Windows (MSI)	The service downloads and installs new releases during a daily window you choose.
Linux deb/rpm from the package repository	A systemd timer upgrades the Nebula Commander packages from that repository during the window.
NixOS module	Notify only. Checks daily and tells you when a release is out, with the commands to update. It never changes the system: your flake decides the version.
Docker, Flatpak, pip, a bare binary	Not available. Update these the way you installed them (pull a new image, Flathub, `pip install -U`).

Turn it on

Windows: open the app as administrator (Relaunch as administrator), go to Settings → Updates, switch on Automatic updates, pick the window and click Save. Or, from an elevated prompt:

State of Nebula Commander Development (v0.4.0)

Wed, 16 Sep 2026 00:00:00 +0000

It’s been a little over two weeks since the v0.3.0 update, where we listed exit nodes as the one big thing still missing and called out a still-inconsistent UI as ongoing work. Neither of those is true anymore. This one covers v0.3.0 through v0.4.0.

What’s new since v0.3.0

Subnet routers and exit nodes are here, built on Nebula’s own unsafe_routes. Turn any node into a subnet router (advertise a LAN behind it, Tailscale---advertise-routes-style) or an exit node (route all of another node’s traffic, Tailscale---advertise-exit-node-style). Routes are opt-in per consumer — advertising one never silently exposes it network-wide — and configurable from either side: a gateway’s “Used by” picker, or, new in this release, a simple Use Subnet Router/Use Exit Node dropdown on any other node that wants to consume one, without opening the gateway’s own settings at all. On Linux nodes running ncclient, the whole thing is automatic: local subnet discovery, IP forwarding, and nftables NAT rules, no host access needed. Everything else (Windows, macOS, Docker-deployed ncclient, bare nebula) gets the right config generated for it, with a full doc on the manual host-side steps. Getting the Nebula semantics right here took two fix-forward releases early on — via is mandatory on every unsafe_routes entry and the gateway’s own certificate needs a -subnets claim, or nebula refuses to start at all.

State of Nebula Commander Development (v0.3.0)

Sun, 30 Aug 2026 00:00:00 +0000

It’s been a little over six months since our last state-of-development post, when we described Nebula Commander as being in “early development” with a client that was “still evolving.” Since then the project has moved through v0.2.12 all the way to v0.3.0, and the picture has changed enough that it’s worth a proper update.

What’s new since February

The client is no longer the weak link. The Windows client was rearchitected around a real background service (NebulaCommanderService, running as LocalSystem) with a thin, always-unelevated tray app on top — no UAC prompts, ever, for enrolling, starting Nebula, or applying DNS. It ships three ways now: a standalone CLI, the Windows MSI (CLI + tray + service), and a Docker image with an s6-overlay supervisor for lighthouse deployments.

State of Nebula Commander Development (February 2025)

Tue, 24 Feb 2026 00:00:00 +0000

Nebula Commander is a self-hosted control plane for Nebula overlay networks. This post summarizes where the project stands as of February 2026 and how you can try it or contribute.

What’s in place

Backend (Python/FastAPI)
The API supports the core workflows: networks (create, delete), nodes (CRUD, IP allocation, certificates), groups and inbound firewall rules, and OIDC-based access with roles (system-admin, network-owner, user). You can run it with Docker, on NixOS via the systemd module, or locally with a venv and uvicorn.

Search

Mon, 01 Jan 0001 00:00:00 +0000