Netmaker: WireGuard automation for self-hosted mesh and site-to-site networks

The problem Netmaker solves: WireGuard keys at fleet scale

WireGuard itself is a small kernel interface. Adding a peer means generating a keypair, editing a config on both ends, and reloading the interface. That is fine for three machines and painful for thirty, and it becomes a real operational problem when some of those machines are behind NAT, on a cloud VM with a changing address, or in a Kubernetes cluster. Netmaker's answer is a server that holds the desired state of the network and pushes the resulting configuration to agents.

The README frames the scope as "WireGuard automation from homelab to enterprise" and lists four things it creates: WireGuard networks, remote access gateways, mesh VPNs and site-to-site links. The audience follows from that list. It is for people who have decided they want WireGuard, not people who want a VPN product with a friendly app and no server to run. The repository topics (mesh, overlay-network, site-to-site, zero-trust, self-hosted) describe the same territory.

One thing worth stating plainly: the network is still WireGuard. Netmaker is the control plane, and the data plane is the kernel module. That is the whole reason to care. You get kernel WireGuard throughput and you get a management layer, but you also inherit the requirement that the agent can actually program a WireGuard interface on the host.

How the server, the mq broker and netclient fit together

The repository layout tells most of the story. main.go is the server entry point, and the top level is split into auth, controllers, logic, models, db, mq, grpc, schema, servercfg and netclient. The Dockerfile builds that server binary with CGO enabled and copies a config directory into the image, exposing 8081 and 6060.

The mq directory is the interesting one. Netmaker depends on github.com/eclipse/paho.mqtt.golang, so the server and the agents are not in a request-response relationship only. Configuration changes can be published to agents rather than polled. The presence of grpc and a swagger.yaml suggests a second, typed API surface alongside the REST controllers.

On the client side, netclient is a directory in this same repository, which means the agent is versioned with the server. The Dockerfile creates /etc/netclient/config inside the image, so the agent expects a config directory at that path. The go.mod also pulls in golang.zx2c4.com/wireguard/wgctrl, the library used to talk to the WireGuard interface, and gorm with both SQLite and Postgres drivers, so the server's own state can live in either database.

That split matters for failure modes. If the server is unreachable, existing WireGuard tunnels keep forwarding packets, because the data plane does not depend on the control plane. What stops is change: new peers, revoked keys, ACL edits. If the MQ connection drops, the documentation does not describe what happens to pending configuration pushes.

Installing Netmaker on a cloud VM with the quick install script

The README gives a self-hosted quick start aimed at a single cloud VM. It asks for Ubuntu 24.04 with a static public IP, inbound allowed on port 443 and 51821 for both TCP and UDP, and outbound allowed on all TCP and all UDP. It also recommends preparing DNS first: a wildcard subdomain such as *.netmaker.example.com pointing at the VM's public IP.

With that in place, the README's command downloads the quick install script and runs it as root:

sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh

The script lives at scripts/nm-quick.sh in the repository, so you can read it before running it. The README does not enumerate every prompt the script asks, so treat the first run as something to watch rather than something to fire and forget.

If you would rather build and run the server yourself, the Dockerfile is the contract: the build stage uses gravitl/go-builder:1.26.0 with CGO_ENABLED=1, and the runtime stage is alpine:3.24.1 with sqlite installed. The Makefile exposes the same targets the CI uses, with CE and EE build tags:

make deps
make build-ce
make image-ce TAG=dev

The Makefile notes that EE builds are slow on first run because of CGO, SQLite and the pro/ tree, and that cached rebuilds are much faster. That is a fair warning about the CE build too: CGO means you need a C toolchain, and the Makefile has a check-cgo target for exactly that reason.

After the server is up, the README points to the Walkthrough and Getting Started guides for configuring networks, and to the blog for use cases including Kubernetes. There is no separate client install command in the README itself; the netclient directory is where the agent lives, and the docs are where enrollment is described.

Where Netmaker is the wrong tool

The quick install assumes a VM with a static public IP and a firewall you control. That is a reasonable assumption for a homelab or a cloud tenancy and a bad one for a laptop-only setup or a network where you cannot open inbound ports. If you cannot expose 443 and 51821, the self-hosted path in the README does not apply to you, and the README's alternative is the managed service at netmaker.io.

The second limitation is the agent. Netclient has to program a WireGuard interface on the host, and the README's own platform list is Linux, Docker, Mac and Windows. The linked community projects (OpenWRT packager, K3S, Podman setup) exist because those environments need extra work that the main repository does not cover. If your fleet includes an OS outside that list, check the community projects before assuming support.

The third is the licence boundary. The README states that content under the pro/ directory is licensed under pro/PRO_LICENSE, while content outside those restrictions is Apache 2.0. The repository's top-level entries include pro/ and main_ee.go, and the Makefile builds an ee tag. So "open source" here describes the CE path, not necessarily every artifact in the tree. The GitHub licence field reports NOASSERTION, which is consistent with a mixed-licence repository rather than a single SPDX identifier.

Netmaker compared with Tailscale and Headscale

The comparison people search for is Netmaker versus Tailscale, and the difference is architectural rather than a feature list. Tailscale is a hosted coordination service with a client that is designed to work without you running anything. Netmaker's README opens with a self-hosted quick start, and the managed option is presented as an alternative for people who do not want to run the server. If your constraint is "no infrastructure to operate", the hosted option wins by definition.

Headscale is the closer comparison, because it is also a self-hosted control server. The distinction is what sits underneath. Headscale implements the Tailscale coordination protocol for Tailscale clients. Netmaker drives plain WireGuard through wgctrl and ships its own agent in the netclient directory. If you want to keep stock WireGuard semantics and your own agent, Netmaker's approach is the one that matches; if you want the Tailscale client ecosystem without the hosted service, Headscale is the one that matches.

ZeroTier and Nebula come up in the same searches and differ one level lower: they are their own overlay protocols rather than control planes for WireGuard. Choosing between them is a choice of data plane, and Netmaker is only in the running if you have already decided on WireGuard.

Maintenance, releases and upgrade cost

The last push to the develop branch was on 2026-09-10, and the most recent release is v1.7.0 from 2026-08-31. Before that, v1.6.0 landed on 2026-06-12 and v1.5.1 on 2026-03-31. So the release cadence over 2026 is roughly quarterly, with the default branch moving between releases. The repository is not archived.

That cadence is the cost model. A quarterly release train means you should expect to upgrade a server and a fleet of agents, and the agent is versioned in the same repository as the server, which reduces the chance of a protocol mismatch but does not remove the need to roll agents forward. The Makefile's note that EE builds are slow on first run and that cached rebuilds are faster is a hint about what rebuilding from source costs you if you do not use the published images.

The server also carries state. go.mod includes gorm with both SQLite and Postgres drivers, and the Dockerfile creates a SQLite-backed runtime by default. Whatever database you choose, that is the thing to back up before an upgrade, and the README does not document a rollback procedure for a failed upgrade. Plan the upgrade as a database migration, not as a container restart.

On licensing, the README is explicit that pro/ content falls under pro/PRO_LICENSE and everything outside those restrictions is Apache 2.0, with LICENSE.md holding the details. Read LICENSE.md against the directory you are actually building before you ship it inside a product.

Editorial conclusion

Adopt Netmaker if you need a self-hosted control plane over kernel WireGuard and you are willing to run a server with a static public IP, DNS and open ports 443 and 51821. Do not adopt it if you want a zero-ops service, or if your network is small enough that a handful of wg-quick configs will do. Verify first that the netclient agent builds or installs cleanly on every OS in your fleet, and read LICENSE.md to confirm what the pro/ directory covers in v1.7.0.

Frequently asked questions

Official sources

1. gravitl/netmaker on GitHub
2. Issues
3. Project website
4. README
5. Releases