{"id":13509302,"url":"https://github.com/mudler/edgevpn","last_synced_at":"2026-05-30T01:03:26.022Z","repository":{"id":37707697,"uuid":"367481529","full_name":"mudler/edgevpn","owner":"mudler","description":":sailboat: The immutable, decentralized, statically built p2p VPN without any central server and automatic discovery! Create decentralized introspectable tunnels over p2p with shared tokens","archived":false,"fork":false,"pushed_at":"2024-10-23T18:38:22.000Z","size":8033,"stargazers_count":653,"open_issues_count":33,"forks_count":90,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T14:19:05.315Z","etag":null,"topics":["blockchain","cloudvpn","golang","golang-library","holepunch","ipfs","ipfs-blockchain","kubernetes","libp2p","mesh","mesh-networks","nat","networking","p2p","p2pvpn","tunnel","vpn"],"latest_commit_sha":null,"homepage":"https://mudler.github.io/edgevpn","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mudler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-14T21:18:10.000Z","updated_at":"2024-10-24T23:31:00.000Z","dependencies_parsed_at":"2023-10-02T18:59:09.134Z","dependency_job_id":"56b0f1d2-15ac-483f-8900-679a8457f882","html_url":"https://github.com/mudler/edgevpn","commit_stats":{"total_commits":1028,"total_committers":17,"mean_commits":"60.470588235294116","dds":0.377431906614786,"last_synced_commit":"e2ba69ca8bffa31e1f9fbf6037c0acfd2f74f95f"},"previous_names":[],"tags_count":111,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudler%2Fedgevpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudler%2Fedgevpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudler%2Fedgevpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudler%2Fedgevpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mudler","download_url":"https://codeload.github.com/mudler/edgevpn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161243,"owners_count":21057552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cloudvpn","golang","golang-library","holepunch","ipfs","ipfs-blockchain","kubernetes","libp2p","mesh","mesh-networks","nat","networking","p2p","p2pvpn","tunnel","vpn"],"created_at":"2024-08-01T02:01:05.916Z","updated_at":"2026-05-30T01:03:26.017Z","avatar_url":"https://github.com/mudler.png","language":"Go","funding_links":[],"categories":["Go","Before using VPN, please modify **[DNS](https://www.dnsperf.com/#!dns-resolvers)** to ensure that the vpn server is correct resolve. [How to Change Your DNS](https://www.wikihow.com/wikiHowTo?search=dns) **[Change sim Mobile data APN](https://apkpure.com/apn-settings/net.thenatureweb.apnsettings)**","网络信息服务","blockchain","Repos","vpn"],"sub_categories":["网络代理"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n\t\u003cimg src=\"https://user-images.githubusercontent.com/2420543/144679248-1f6e4c10-a558-424c-b6f5-b3695269c906.png\" width=128\n         alt=\"logo\"\u003e\u003cbr\u003e\n    EdgeVPN\n\n\u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003eCreate Decentralized private networks \u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/licence-GPL3-brightgreen\"\n         alt=\"license\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/mudler/edgevpn/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/mudler/edgevpn\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/made%20with-Go-blue\"\u003e\n  \u003cimg src=\"https://goreportcard.com/badge/github.com/mudler/edgevpn\" alt=\"go report card\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t \u003cbr\u003e\n    Fully Decentralized. Immutable. Portable. Easy to use Statically compiled VPN and a reverse proxy over p2p.\u003cbr\u003e\n    \u003cb\u003eVPN\u003c/b\u003e -  \u003cb\u003eReverse Proxy\u003c/b\u003e - \u003cb\u003eSend files securely over p2p\u003c/b\u003e -  \u003cb\u003eBlockchain\u003c/b\u003e\n\u003c/p\u003e\n\n\nEdgeVPN uses libp2p to build private decentralized networks that can be accessed via shared secrets.\n\nIt can:\n\n- **Create a VPN** :  Secure VPN between p2p peers\n  - Automatically assign IPs to nodes\n  - Embedded tiny DNS server to resolve internal/external IPs\n  - Create trusted zones to prevent network access if token is leaked\n  - For example, the [Kairos](https://github.com/kairos-io/kairos) CNCF project uses it as a layer for creating decentralized clusters with Kubernetes\n\n- **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.\n\n- **Send files via p2p** : Send files over p2p between nodes without establishing a VPN connection.\n\n- **Be used as a library**: Plug a distributed p2p ledger easily in your golang code! For example EdgeVPN powers [LocalAI](https://github.com/mudler/LocalAI)'s P2P features (you can learn more about it [here](https://localai.io/features/distribute/)).\n\nSee the [documentation](https://mudler.github.io/edgevpn).\n\n# :camera: Screenshots\n\nDashboard (Dark mode)            |  Dashboard (Light mode)\n:-------------------------:|:-------------------------:\n![Screenshot 2021-10-31 at 00-12-16 EdgeVPN - Machines index](https://user-images.githubusercontent.com/2420543/163020448-8e9238c1-3b6d-435d-9b25-7729d8779ebd.png) | ![Screenshot 2021-10-31 at 23-03-26 EdgeVPN - Machines index](https://user-images.githubusercontent.com/2420543/163020460-e18c07d7-8426-4992-aab3-0b2fd90279ae.png)\n\nDNS            |  Machine index\n:-------------------------:|:-------------------------:\n![Screenshot 2021-10-31 at 23-03-44 EdgeVPN - Services index](https://user-images.githubusercontent.com/2420543/163020465-3d481da4-4912-445e-afc0-2614966dcadf.png) | ![Screenshot 2021-10-31 at 23-03-59 EdgeVPN - Files index](https://user-images.githubusercontent.com/2420543/163020462-7821a622-8c13-4971-8abe-9c5b6b491ae8.png)\n\nServices            |  Blockchain index\n:-------------------------:|:-------------------------:\n![Screenshot 2021-10-31 at 23-04-12 EdgeVPN - Users connected](https://user-images.githubusercontent.com/2420543/163021285-3c5a980d-2562-4c10-b266-7e99f19d8a87.png) | ![Screenshot 2021-10-31 at 23-04-20 EdgeVPN - Blockchain index](https://user-images.githubusercontent.com/2420543/163020457-77ef6e50-40a6-4e3b-83c4-a81db729bd7d.png)\n\n\n# :new: GUI\n\nA Desktop GUI application (alpha) for Linux is available [here](https://github.com/mudler/edgevpn-gui)\n\nDashboard            |  Connections index\n:-------------------------:|:-------------------------:\n![edgevpn-gui-2](https://user-images.githubusercontent.com/2420543/147854909-a223a7c1-5caa-4e90-b0ac-0ae04dc0949d.png) | ![edgevpn-3](https://user-images.githubusercontent.com/2420543/147854904-09d96991-8752-421a-a301-8f0bdd9d5542.png)\n![edgevpn-gui](https://user-images.githubusercontent.com/2420543/147854907-1e4a4715-3181-4dc2-8bc0-d052b3bf46d3.png) | \n\n# Kubernetes \n\nCheck out [Kairos](https://github.com/kairos-io/kairos) for seeing EdgeVPN in action with Kubernetes!\n\n# :running: Installation\n\nDownload the precompiled static release in the [releases page](https://github.com/mudler/edgevpn/releases). You can either install it in your system or just run it.\n\n# :computer: Usage\n\nEdgeVPN 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.\n\nEvery token is unique and identifies the network,  no central server setup, or specifying hosts ip is required.\n\nTo generate a config run:\n\n```bash\n# Generate a new config file and use it later as EDGEVPNCONFIG\n$ edgevpn -g \u003e config.yaml\n```\n\nOR to generate a portable token:\n\n```bash\n$ EDGEVPNTOKEN=$(edgevpn -g -b)\n```\n\nNote, tokens are config merely encoded in base64, so this is equivalent:\n\n```bash\n$ EDGEVPNTOKEN=$(edgevpn -g | tee config.yaml | base64 -w0)\n```\n\nAll 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. \n\nThe configuration file is the network definition and allows you to connect over to your peers securely.\n\n**Warning** Exposing this file or passing-it by is equivalent to give full control to the network.\n\n## :satellite: As a VPN\n\nTo start the VPN, simply run `edgevpn` without any argument.\n\nAn example of running edgevpn on multiple hosts:\n\n```bash\n# on Node A\n$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.11/24\n# on Node B\n$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.12/24\n# on Node C ...\n$ EDGEVPNTOKEN=.. edgevpn --address 10.1.0.13/24\n...\n```\n\n... 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`)\n\n*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.\n\n\n# :question: Is it for me?\n\nEdgeVPN makes VPN decentralization a first strong requirement. \n\nIts main use is for edge and low-end devices and especially for development.\n\nThe decentralized approach has few cons:\n\n- 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.\n- Might be not suited for low latency workload.\n\nKeep that in mind before using it for your prod networks!\n\nBut it has a strong pro: it just works everywhere libp2p works!\n\n# :question: Why? \n\nFirst 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.\n\n# :warning: Warning!\n\nI'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. \n\n## Example use case: network-decentralized [k3s](https://github.com/k3s-io/k3s) test cluster\n\nLet'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.\n\nIf you are not really interested in network performance (again, that's for development purposes only!) then you could use `edgevpn` + [k3s](https://github.com/k3s-io/k3s) in this way:\n\n1) Generate edgevpn config: `edgevpn -g \u003e vpn.yaml`\n2) Start the vpn:\n\n   on node A: `sudo IFACE=edgevpn0 ADDRESS=10.1.0.3/24 EDGEVPNCONFIG=vpn.yml edgevpn`\n   \n   on node B: `sudo IFACE=edgevpn0 ADDRESS=10.1.0.4/24 EDGEVPNCONFIG=vpm.yml edgevpn`\n3) Start k3s:\n \n   on node A: `k3s server --flannel-iface=edgevpn0`\n   \n   on node B: `K3S_URL=https://10.1.0.3:6443 K3S_TOKEN=xx k3s agent --flannel-iface=edgevpn0 --node-ip 10.1.0.4`\n\nWe have used flannel here, but other CNI should work as well.\n\n\n# :notebook: As a library\n\nEdgeVPN can be used as a library. It is very portable and offers a functional interface.\n\nTo join a node in a network from a token, without starting the vpn:\n\n```golang\n\nimport (\n    node \"github.com/mudler/edgevpn/pkg/node\"\n)\n\ne := node.New(\n    node.Logger(l),\n    node.LogLevel(log.LevelInfo),\n    node.MaxMessageSize(2 \u003c\u003c 20),\n    node.FromBase64( mDNSEnabled, DHTEnabled, token ),\n    // ....\n  )\n\ne.Start(ctx)\n\n```\n\nor to start a VPN:\n\n```golang\n\nimport (\n    vpn \"github.com/mudler/edgevpn/pkg/vpn\"\n    node \"github.com/mudler/edgevpn/pkg/node\"\n)\n\nopts, err := vpn.Register(vpnOpts...)\nif err != nil {\n\treturn err\n}\n\ne := edgevpn.New(append(o, opts...)...)\n\ne.Start(ctx)\n```\n\n# 🧑‍💻 Projects using EdgeVPN\n\n- [Kairos](https://github.com/kairos-io/kairos) - creates Kubernetes clusters with K3s automatically using EdgeVPN networks\n\n\n# 🐜 Contribution\n\nYou can improve this project by contributing in following ways:\n\n- report bugs\n- fix issues\n- request features\n- asking questions (just open an issue)\n\nand any other way if not mentioned here.\n\n# :notebook: Credits\n\n- The awesome [libp2p](https://github.com/libp2p) library\n- [https://github.com/songgao/water](https://github.com/songgao/water) for tun/tap devices in golang\n- [Room example](https://github.com/libp2p/go-libp2p/tree/master/examples/chat-with-rendezvous) (shamelessly parts are copied by)\n- Logo originally made by [Uniconlabs](https://www.flaticon.com/authors/uniconlabs) from [www.flaticon.com](https://www.flaticon.com/), modified by me\n\n# :notebook: Troubleshooting\n\nIf during bootstrap you see messages like:\n\n```\nedgevpn[3679]:             * [/ip4/104.131.131.82/tcp/4001] failed to negotiate stream multiplexer: context deadline exceeded     \n```\n\nor\n\n```\nedgevpn[9971]: 2021/12/16 20:56:34 failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See https://github.com/lucas-clemente/quic-go/wiki/UDP-Receive-Buffer-Size for details.\n```\n\nor generally experiencing poor network performance, it is recommended to increase the maximum buffer size by running:\n\n```\nsysctl -w net.core.rmem_max=2500000\n```\n\n# :notebook: TODO\n\n- [x] VPN\n- [x] Send and receive files via p2p\n- [x] Expose remote/local services via p2p tunnelling\n- [x] Store arbitrary data on the blockchain\n- [x] Allow to persist blockchain on disk\n\n# :notebook: LICENSE\n\nApache License v2.\n\n```\nedgevpn  Copyright (C) 2021 Ettore Di Giacinto\nThis program comes with ABSOLUTELY NO WARRANTY.\nThis is free software, and you are welcome to redistribute it\nunder certain conditions.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmudler%2Fedgevpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmudler%2Fedgevpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmudler%2Fedgevpn/lists"}