slackhq/nebula: a peer-to-peer overlay network you run yourself

The problem Nebula solves: private addressing across networks you do not control

Hosts in different clouds, datacenters and home offices usually have no shared addressing scheme. The README states that Nebula lets users move data between nodes in any number of cloud service providers, datacenters and endpoints "without needing to maintain a particular addressing scheme." Each node gets an IP from a subnet you choose at certificate signing time, and that IP is asserted by the certificate rather than by the network it sits on.

The intended audience is an operator who is willing to run a small amount of infrastructure. The README describes the lighthouse as "the only node in a Nebula network whose IP should not change," and notes it requires very few compute resources. That is a real operational commitment, small but not zero. Teams that want someone else to hold the PKI and the lighthouses are pointed by the README at Managed Nebula from Defined Networking.

Certificates, groups and lighthouses: how the overlay is wired

Nebula is described as a mutually authenticated peer-to-peer software-defined network based on the Noise Protocol Framework. Certificates carry three things: a node's IP address, its name, and its membership in user-defined groups. The default configuration uses Elliptic-curve Diffie-Hellman key exchange and AES-256-GCM.

The data plane is peer to peer. Lighthouses exist for discovery, and the README notes they can optionally use UDP hole punching so peers behind most firewalls or NATs can establish connections. Traffic between two hosts does not have to transit the lighthouse once the path is established, which is the main architectural difference from a hub-and-spoke VPN.

Group membership is what makes the firewall expressive. The README signs one node with `-groups "laptop,home,ssh"` and another with `-groups "servers"`, and those labels are later usable in traffic rules. That is the cloud-security-group style of filtering the project set out to provide, applied to hosts that may sit anywhere.

The repository layout reflects this split. Top-level files such as `firewall.go`, `hostmap.go`, `lighthouse.go`, `handshake_manager.go` and `connection_manager.go` sit alongside directories `cert/`, `handshake/`, `header/`, `config/` and `cmd/`. The `cmd/` directory is where the Makefile points its `NEBULA_CMD_PATH`, so that is where the `nebula` binary is built from.

Installing Nebula and bringing up a two-node network

The README lists distribution packages rather than a single canonical install path. On macOS with Homebrew the command is:

brew install nebula

On Debian, Fedora, Arch and Alpine the README gives `apt install nebula`, `dnf install nebula`, `pacman -S nebula` and `apk add nebula` respectively. There is also a container image, which the README shows as:

docker pull nebulaoss/nebula

You need `nebula-cert` as well as the `nebula` binary. The README says to get both from the releases page or from the distribution packages.

First create the certificate authority. This writes `ca.key` and `ca.cert` into the current directory, and the README calls `ca.key` the most sensitive file you will create because it signs every host certificate:

./nebula-cert ca -name "Myorganization, Inc"

The README warns that a CA has a one-year lifetime by default. Then sign host certificates. This example uses 192.168.100.x/24, one lighthouse and two hosts, with groups attached to the nodes that need them:

./nebula-cert sign -name "lighthouse1" -ip "192.168.100.1/24"
./nebula-cert sign -name "laptop" -ip "192.168.100.2/24" -groups "laptop,home,ssh"
./nebula-cert sign -name "server1" -ip "192.168.100.9/24" -groups "servers"

Host certificates expire one second before the CA unless you pass `-duration`, according to the README. Next, take the example configuration from `examples/config.yml` in the repository. On the lighthouse set `am_lighthouse: true`; on the other hosts put the lighthouse in `static_host_map` and in the lighthouse `hosts` section.

Copy to each host the binary, `config.yml`, `ca.crt`, the host's `.crt` and the host's `.key`. The README is explicit that `ca.key` must not be copied to individual nodes. Then start it:

./nebula -config /path/to/config.yml

What you should see is the interface come up and the peers reachable at their 192.168.100.x addresses once the lighthouse has helped them find each other. Make sure udp/4242, the default Nebula port per the README, can reach the lighthouse from the internet.

Where Nebula is the wrong tool

The README is candid that the PKI is yours to lose. `ca.key` signs every node certificate, and if it leaks, the trust root of the whole network is compromised; if you lose it, you cannot issue new certificates. Certificate expiry compounds this. A CA defaults to a one-year lifetime, and the README links a separate guide for rotating a certificate authority rather than treating rotation as a routine operation.

Discovery is the second constraint. The README marks the lighthouse as optional, then immediately adds "but you really should." Without one, nodes have no way to find each other unless you supply static reachability yourself. A lighthouse is also the only node whose IP must stay fixed, so it becomes a piece of infrastructure you monitor and pay for.

There is a scale trade-off the README does not resolve. It claims Nebula can connect tens of thousands of computers, but the same document gives no sizing guidance for lighthouses, no numbers on how many peers a single lighthouse can serve, and no description of what happens to discovery latency as the hostmap grows. If your plan depends on that upper bound, you are reading a claim, not a documented capacity model. The README also does not document rollback or downgrade between releases, so treat version changes as one-way until you have checked the changelog yourself.

Nebula against WireGuard: overlapping primitives, different defaults

The dependency list in `go.mod` includes `golang.zx2c4.com/wireguard` and `golang.zx2c4.com/wireguard/windows`, so Nebula is not a reimplementation of WireGuard's crypto; it is a different system that borrows parts of that codebase for platform integration. The comparison that matters is operational.

WireGuard is a tunnel with a configuration model built around pre-shared public keys and allowed IPs. You decide which peer can reach which address, and you distribute that configuration. Nebula adds a certificate authority, named nodes, group labels and a firewall that can match on those labels. The README frames this as bringing encryption, security groups, certificates and tunneling together.

The cost of that extra layer is the PKI. WireGuard has no CA to rotate, no certificate expiry to track and no signing step when you add a machine; you exchange keys and edit a config. Nebula trades that simplicity for identity that survives IP changes and for rules written against groups. If your fleet is a handful of static servers with stable addresses, WireGuard's model is less machinery for the same tunnel. If your fleet is dozens or hundreds of hosts behind NAT that come and go, the certificate and group layer is the part doing the work.

Licence, maintenance and the cost of upgrading

Nebula is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is about as permissive as it gets; the practical constraint is not the licence text but the CA key you generate, which is your operational secret and not something the licence governs. This is not legal advice.

The repository is not archived, and the last push was on 2026-09-17. Recent releases are v1.11.1 on 2026-08-21, v1.11.0 on 2026-07-23 and v1.10.3 on 2026-02-06. The gap between v1.10.3 and v1.11.0 is roughly five months, and the two 1.11 releases landed a month apart, so the cadence is not uniform. Plan upgrades around the changelog rather than an assumed schedule.

Upgrade cost has two parts. The binary swap is cheap; the Makefile cross-builds a long list of targets including linux-amd64, linux-arm64, darwin-arm64 and windows-amd64, and distribution packages exist for the major Linux families. The expensive part is certificates. Because host certificates expire one second before the CA by default and the CA itself lasts a year, a long-lived deployment needs a rotation plan regardless of how often you upgrade the binary. The README does not document rollback, so the safe sequence is to test a version change on one node before touching the lighthouse.

Editorial conclusion

Adopt Nebula if you can hold a CA key, run at least one lighthouse, and want firewall rules expressed against certificate groups rather than IP ranges. Do not adopt it if you cannot keep the CA offline or you need a hosted control plane, since the README points to Defined Networking's Managed Nebula for that. Before rolling out, verify that udp/4242 reaches your lighthouse and check the CA lifetime, which the README says defaults to one year.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. slackhq/nebula on GitHub