Skip to content
/ edgevpn Public

β›΅ The immutable, decentralized, statically built p2p VPN without any central server and automatic discovery! Create decentralized introspectable tunnels over p2p with shared tokens


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


Create Decentralized private networks

license go report card

Fully Decentralized. Immutable. Portable. Easy to use Statically compiled VPN and a reverse proxy over p2p.
VPN - Reverse Proxy - Send files securely over p2p - Blockchain

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 prevent network access if token is leaked
  • 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!

See the documentation.

πŸ“· Screenshots

Dashboard (Dark mode) Dashboard (Light mode)
Screenshot 2021-10-31 at 00-12-16 EdgeVPN - Machines index Screenshot 2021-10-31 at 23-03-26 EdgeVPN - Machines index
DNS Machine index
Screenshot 2021-10-31 at 23-03-44 EdgeVPN - Services index Screenshot 2021-10-31 at 23-03-59 EdgeVPN - Files index
Services Blockchain index
Screenshot 2021-10-31 at 23-04-12 EdgeVPN - Users connected Screenshot 2021-10-31 at 23-04-20 EdgeVPN - Blockchain index

πŸ†• GUI

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

Dashboard Connections index
edgevpn-gui-2 edgevpn-3


Check out c3os for seeing EdgeVPN in action with Kubernetes!

πŸƒ Installation

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

πŸ’» 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.

πŸ“‘ 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
# on Node B
$ EDGEVPNTOKEN=.. edgevpn --address
# on Node C ...
$ EDGEVPNTOKEN=.. edgevpn --address

... 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.

❓ Is it for me?

EdgeVPN makes VPN decentralization a first strong requirement.

Its main use is for edge and low-end devices and especially for development.

The decentralized approach has few cons:

  • The underlying network is chatty. It uses a Gossip protocol for synchronizing the routing table and p2p. Every blockchain message is broadcasted to all peers, while the traffic is to the host only.
  • Might be not suited for low latency workload.

Keep that in mind before using it for your prod networks!

But it has a strong pro: it just works everywhere libp2p works!

❓ 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!

I'm not a security expert, and this software didn't went through a full security audit, so don't use and rely on it for sensible traffic and not even for production environment! I did this mostly for fun while I was experimenting with libp2p.

Example use case: network-decentralized k3s test cluster

Let's see a practical example, you are developing something for kubernetes and you want to try a multi-node setup, but you have machines available that are only behind NAT (pity!) and you would really like to leverage HW.

If you are not really interested in network performance (again, that's for development purposes only!) then you could use edgevpn + k3s in this way:

  1. Generate edgevpn config: edgevpn -g > vpn.yaml

  2. Start the vpn:

    on node A: sudo IFACE=edgevpn0 ADDRESS= EDGEVPNCONFIG=vpn.yml edgevpn

    on node B: sudo IFACE=edgevpn0 ADDRESS= EDGEVPNCONFIG=vpm.yml edgevpn

  3. Start k3s:

    on node A: k3s server --flannel-iface=edgevpn0

    on node B: K3S_URL= K3S_TOKEN=xx k3s agent --flannel-iface=edgevpn0 --node-ip

We have used flannel here, but other CNI should work as well.

πŸ““ As a library

EdgeVPN can be used as a library. It is very portable and offers a functional interface.

To join a node in a network from a token, without starting the vpn:

import (
    node ""

e := node.New(
    node.MaxMessageSize(2 << 20),
    node.FromBase64( mDNSEnabled, DHTEnabled, token ),
    // ....


or to start a VPN:

import (
    vpn ""
    node ""

opts, err := vpn.Register(vpnOpts...)
if err != nil {
	return err

e := edgevpn.New(append(o, opts...)...)


πŸ§‘β€πŸ’» 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.

πŸ““ Credits

πŸ““ Troubleshooting

If during bootstrap you see messages like:

edgevpn[3679]:             * [/ip4/] failed to negotiate stream multiplexer: context deadline exceeded     


edgevpn[9971]: 2021/12/16 20:56:34 failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See for details.

or generally experiencing poor network performance, it is recommended to increase the maximum buffer size by running:

sysctl -w net.core.rmem_max=2500000


  • 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


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.