edgevpn

EdgeVPN uses libp2p to build private decentralized networks that can be accessed via shared secrets.

It can:

• Create a VPN : Secure VPN between p2p peers

  • Automatically assign IPs to nodes
  • Embedded tiny DNS server to resolve internal/external IPs
  • Create trusted zones to restrict which peers may join (experimental: it does not currently stop a token holder from entering the zone — see the security model)
  • For example, the Kairos CNCF project uses it as a layer for creating decentralized clusters with Kubernetes

• Act as a reverse Proxy : Share a tcp service like you would do with ngrok. EdgeVPN let expose TCP services to the p2p network nodes without establishing a VPN connection: creates reverse proxy and tunnels traffic into the p2p network.

• Send files via p2p : Send files over p2p between nodes without establishing a VPN connection.

• Be used as a library: Plug a distributed p2p ledger easily in your golang code! For example EdgeVPN powers LocalAI's P2P features (you can learn more about it here).

See the documentation.

:camera: Screenshots

Dashboard (Dark mode)	Dashboard (Light mode)

DNS	Machine index

Services	Blockchain index

:new: GUI

A Desktop GUI application (alpha) for Linux is available here

Dashboard	Connections index

Kubernetes

Check out Kairos for seeing EdgeVPN in action with Kubernetes!

:running: Installation

Download the precompiled static release in the releases page. You can either install it in your system or just run it.

Or install the latest release with the one-liner:

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

Every installation route — install script, release archives, Homebrew, the container image and building from source — is covered in Install EdgeVPN.

:hammer: Building from source

The web UI is a React application compiled into the binary, so a Node toolchain (Node 20.19+) is required for a full build:

make build            # builds the UI if needed, then the Go binary
make react-ui-force   # force a clean UI rebuild

go build alone works only when api/react-ui/dist already exists — the UI is embedded with //go:embed, and a missing directory is a compile error. For Go-only work you can stub it:

mkdir -p api/react-ui/dist && touch api/react-ui/dist/index.html

See api/react-ui/README.md for frontend development.

:computer: Usage

EdgeVPN works by generating tokens (or a configuration file) that can be shared between different machines, hosts or peers to access to a decentralized secured network between them.

Every token is unique and identifies the network, no central server setup, or specifying hosts ip is required.

To generate a config run:

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

OR to generate a portable token:

$ EDGEVPNTOKEN=$(edgevpn -g -b)

Note, tokens are config merely encoded in base64, so this is equivalent:

$ EDGEVPNTOKEN=$(edgevpn -g | tee config.yaml | base64 -w0)

All edgevpn commands implies that you either specify a EDGEVPNTOKEN (or --token as parameter) or a EDGEVPNCONFIG as this is the way for edgevpn to establish a network between the nodes.

The configuration file is the network definition and allows you to connect over to your peers securely.

Warning Exposing this file or passing-it by is equivalent to give full control to the network.

:satellite: As a VPN

To start the VPN, simply run edgevpn without any argument.

An example of running edgevpn on multiple hosts:

# on Node A
$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.11/24
# on Node B
$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.12/24
# on Node C ...
$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.13/24
...

... and that's it! the --address is a virtual unique IP for each node, and it is actually the ip where the node will be reachable to from the vpn. You can assign IPs freely to the nodes of the network, while you can override the default edgevpn0 interface with IFACE (or --interface)

Note: It might take up time to build the connection between nodes. Wait at least 5 mins, it depends on the network behind the hosts.

:question: Is it for me?

The decentralized approach is chatty and might not suit low-latency workloads, and this software has not been security audited. Read when not to use EdgeVPN before you rely on it.

:question: Why?

First of all it's my first experiment with libp2p. Second, I always wanted a more "open" ngrok alternative, but I always prefer to have "less infra" as possible to maintain. That's why building something like this on top of libp2p makes sense.

:warning: Warning!

This software has not been through a full security audit — don't rely on it for sensitive traffic or production environments. The full caveats are in when not to use EdgeVPN.

:books: Examples

• A network-decentralized k3s test cluster — a multi-node Kubernetes development cluster across machines behind NAT.
• Use EdgeVPN as a library — embed a node in your own Go program.

🧑‍💻 Projects using EdgeVPN

• Kairos - creates Kubernetes clusters with K3s automatically using EdgeVPN networks

🐜 Contribution

You can improve this project by contributing in following ways:

• report bugs
• fix issues
• request features
• asking questions (just open an issue)

and any other way if not mentioned here.

:notebook: Credits

• The awesome libp2p library
• https://github.com/songgao/water for tun/tap devices in golang
• Room example (shamelessly parts are copied by)
• Logo originally made by Uniconlabs from www.flaticon.com, modified by me

:notebook: Troubleshooting

Bootstrap failures, receive-buffer warnings and poor network performance are covered in Troubleshooting.

:notebook: TODO

• VPN
• Send and receive files via p2p
• Expose remote/local services via p2p tunnelling
• Store arbitrary data on the blockchain
• Allow to persist blockchain on disk

:notebook: LICENSE

Apache License v2.

edgevpn  Copyright (C) 2021 Ettore Di Giacinto
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions.