Installation on 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, tray, or additional Docker clients) can then resolve Nebula hostnames via the lighthouse.

Image: ghcr.io/nixrtr/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:

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.

Windows Installer

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

On Windows the MSI installer sets up the ncclient CLI, an unelevated tray control UI, and a background Windows Service that does the actual work as LocalSystem - no UAC prompts for enrolling, starting/stopping, or applying split-horizon DNS.

What the installer includes:

ncclient – CLI for enrollment and daemon (poll for config/certs, run or restart Nebula).
ncclient-tray – Unelevated system tray control UI: enroll, settings, and start/stop/restart the background service.
ncclient-service – The NebulaCommanderService Windows Service that polls for config/certs and runs Nebula as LocalSystem. Starts automatically at boot; the tray 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.

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 Install service in Usage). It’s exposed by the same flake.nix as the server module, as nixosModules.client.

{
 inputs.nebula-commander.url = "github:NixRTR/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.

Pip (PyPI)

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

Fallback method when Docker, binaries, or NixOS are not suitable (e.g. no Docker, or you need to run from source).

From PyPI:

pip install nebula-commander

Requires Python 3.10+. This installs the ncclient command.

From source (repo clone):

cd nebula-commander
pip install -r client/requirements.txt

Then run as python -m client --server URL enroll --code XXX, or install the client in development mode to get the ncclient command:

cd client
pip install -e .