The token is a base64 config file, and it is the whole trust model

Everything starts with a token that is just base64

The configuration model is the thing to understand first, because it decides the security posture. A config file is generated with a redirect:

# Generate a new config file and use it later as EDGEVPNCONFIG
$ edgevpn -g > config.yaml

A token is the same content in base64, produced with edgevpn -g -b, and the two forms are shown to be identical by an equivalent shell line that pipes the config through tee and base64 -w0. So neither form carries different privileges, they are the same bytes. Every command needs either EDGEVPNTOKEN, or --token, or an EDGEVPNCONFIG pointing at the file. The warning is stated in bold in the original: exposing this file or passing it by is equivalent to giving full control of the network. There is no central server, no host list and no per-user identity, because the token is the network.

Trusted zones are labelled experimental for a stated reason

Among the VPN capabilities, the README lists the ability to create trusted zones to restrict which peers may join, and immediately qualifies it: experimental, and it does not currently stop a token holder from entering the zone, with a link to the security model page. Taken literally, the feature does not do what its name promises for the case most people would assume. Anyone holding a valid token is inside regardless of which zone they think they are in. That is consistent with the token model above, since the token is the whole network definition, and it means zones are at present a way to organize a network rather than a way to partition it. The rest of the VPN list is less contentious: automatic IP assignment to nodes, and an embedded tiny DNS server that resolves internal and external addresses.

A Go build needs a Node toolchain because the UI is embedded

The build instructions contain the kind of constraint that costs an afternoon if you hit it cold. The web UI is a React application compiled into the binary, so a Node toolchain, Node 20.19 or newer, is required for a full build. The make targets are make build, which builds the UI if needed and then the Go binary, and make react-ui-force for a clean rebuild. The critical sentence is that go build alone works only when api/react-ui/dist already exists, because the UI is embedded with //go:embed and a missing directory is a compile error. For Go-only work the workaround is given explicitly: create the directory and touch an index.html inside it. So the repository contains a frontend, and go.mod sits next to package files and a Makefile in a layout that does not announce that dependency. go.mod names Go 1.26.0, which is the language floor for this codebase.

Four uses, and only one of them is a VPN

The README describes four distinct modes. Creating a VPN gives a secure connection between peers with automatic IP assignment and the embedded DNS server. Acting as a reverse proxy shares a TCP service the way ngrok does, exposing it to the peer network without establishing a VPN connection at all. Sending files moves data between nodes over the peer network, again without a VPN connection. And being used as a library puts a distributed peer-to-peer ledger inside Go code, with EdgeVPN named as the component behind LocalAI's P2P features. That last one is the most interesting for a developer: the reverse proxy and file transfer modes are applications of the same primitive, and the library mode is how you build your own. Starting the VPN itself is running edgevpn with no arguments, with each node given a --address that is a virtual unique IP rather than a real interface address.

Install is a script, a static binary, or a container

Installation has a documented one-liner in addition to the precompiled static releases on the releases page:

curl -sfL https://raw.githubusercontent.com/mudler/edgevpn/master/install.sh | sh

Every route is covered by the same documentation, the same documentation, naming the install script, the release archives, Homebrew, a container image and building from source as the options, with the install tutorial collecting them. You can either install the binary into your system or run it from wherever you unpacked it, and the static compilation is what makes that second option work on a host whose libc differs from yours. The container image and the docker-compose.yml at the repository root cover the containerized route, and the Dockerfile sits beside them. For anyone who wants to see the network before installing anything, the screenshots show a dashboard with separate indexes for DNS, services, files, machines, connected users and the blockchain, which is a fair picture of what the peer network tracks.

Two named users, and one of them is Kubernetes

The README points at real deployments rather than describing hypothetical ones. Kairos, a CNCF project, uses EdgeVPN as a layer for creating decentralized clusters with Kubernetes, and the repository has a Kubernetes section that sends you to the Kairos project to see it in action. LocalAI uses it for P2P features, with a link to that project's documentation for the distribution feature. A separate desktop GUI for Linux exists as a companion project, edgevpn-gui, and it is labelled alpha in the README. That combination is the most useful signal about the project's shape: the core is a Go library and a statically compiled binary, the network primitives come from libp2p, and the interesting adoptions are infrastructure projects embedding it rather than people running a VPN client. The keyword list reinforces that reading, covering hole punching, NAT traversal, mesh networks, IPFS and blockchain.

Where EdgeVPN is the wrong tool

Four cases. The first is anything needing per-user access control. Because the token is the network, giving a colleague access means handing over the token, and the warning about what that means is in bold in the README. There is no user model to attach a role to. The second is compliance work that needs an audit trail of who connected. A peer-to-peer network with a shared secret and no central server has no place to log connection events, which is the direct consequence of the design rather than a missing feature. The third is anyone who assumes zones segment the network. The README says plainly that a token holder can still enter, so a deployment that relies on zones for separation is relying on a feature that does not yet do that. The fourth is a team that wants a conventional VPN with a server. If you can run a WireGuard server or a hosted VPN, you get user accounts, key rotation and logs, and EdgeVPN's advantage is specifically the absence of the server. What you trade for it is the whole control plane.

Editorial conclusion

EdgeVPN suits a team that wants a private network between a handful of machines without running a VPN server, and that is comfortable with a shared secret as the entire access control. It does not suit anyone who needs per-user identity, an audit trail or real zone separation. Before adopting, generate a config with edgevpn -g, keep the token out of shell history and logs, install Node 20.19 or newer if you intend to build the embedded UI yourself, and read the security model page before relying on trusted zones.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mudler/edgevpn on GitHub
3. Project website
4. README
5. Releases