Hyprspace

A Lightweight VPN Built on top of Libp2p for Truly Distributed Networks.

A Bit of Backstory

Libp2p is a networking library created by Protocol Labs that allows nodes to discover each other using a Distributed Hash Table. Paired with NAT hole punching this allows Hyprspace to create a direct encrypted tunnel between two nodes even if they're both behind firewalls.

Moreover! Each node doesn't even need to know the other's ip address prior to starting up the connection. This makes Hyprspace perfect for devices that frequently migrate between locations but still require a constant virtual ip address.

So How Does Hyprspace Compare to Something Like Wireguard?

Wireguard is an amazing VPN written by Jason A. Donenfeld. If you haven't already, definitely go check it out! Wireguard actually inspired me to write Hyprspace. That said, although Wireguard is in a class of it's own as a great VPN, it requires at least one of your nodes to have a public IP address. In this mode, as long as one of your nodes is publicly accessible, it can be used as a cental relay to reach the other nodes in the network. However, this means that all of the traffic for your entire system is going through that one system which can slow down your network and make it fragile in the case that node goes down and you loose the whole network. So instead say that you want each node to be able to directly connect to each other as they do in Hyprspace. Unfortunately through Wireguard this would require every node to be publicly addressable which means manual port forwarding and no travelling nodes.

By contrast Hyprspace allows all of your nodes to connect directly to each other creating a strong reliable network even if they're all behind their own firewalls. No manual port forwarding required!

Use Cases:

A Digital Nomad

I use this system when travelling, if I'm staying in a rental or hotel and want to try something out on a Raspberry Pi I can plug the Pi into the location's router or ethernet port and then just ssh into the system using the same-old internal Hyprspace ip address without having to worry about their NAT or local firewall. Furthermore, if I'm connected to the Virtual Hyprspace Network I can ssh into my machines at home without requiring me to set up any sort of port forwarding.

A Privacy Advocate

Honestly, I even use this system when I'm at home and could connect directly to my local infrastructure. Using Hyprspace however, I don't have to trust the security of my local network and Hyprspace will intelligently connect to my machines using their local ip addresses for maximum speed.

If anyone else has some use cases please add them! Pull requests welcome!

:exclamation: Hyprspace is still a very new project. Although we've tested the code locally for security, it hasn't been audited by a third party yet. We probably wouldn't trust it yet in high security environments.

Getting Started

Prerequisites

If you're running Hyprspace on a Mac you'll need to install iproute2mac. If you're using the brew package manager that's as simple as,

brew install iproute2mac

Installation

  1. Go to Hyprspace Releases (over there -->)
  2. Copy the link for your corresponding OS and Architecture.
  3. Run sudo mkdir -p /usr/local/bin/
  4. Run sudo curl -L "PATH-TO-RELEASE" -o /usr/local/bin/hyprspace
  5. Run sudo chmod a+x /usr/local/bin/hyprspace
  6. (Optional) Run sudo ln -s /usr/local/bin/hyprspace /usr/bin/hyprspace

Usage

Commands

Command Alias Description
help ? Get help with a specific subcommand.
init i Initialize an interface's configuration.
up up Create and Bring Up a Hyprspace Interface
down d Bring Down and Delete A Hyprspace Interface
update upd Have Hyprspace update its own binary to the latest release.

Tutorial

Initializing an Interface

The first thing we'll want to do once we've got Hyprspace installed is
initialize the configuration for an interface. In this case we'll call the
interface on our local machine hs0 (for hypr-space 0) and hs1 on our remote server
but yours could be anything you'd like.

(Note: if you're using a Mac you'll have to use the interface name utun[0-9]. Check which interfaces are already in use by running ip a once you've got iproute2mac installed.)

Local Machine
sudo hyprspace init hs0
Remote Machine
sudo hyprspace init hs1

Add Each Machine As A Peer Of The Other

Now that we've got a set of configurations we'll want to
tell the machines about each other. By default Hyprspace will
put the interface configurations in /etc/hyprspace/interface-name.yaml.
So for our example we'll run

Local Machine
sudo nano /etc/hyprspace/hs0.yaml

and

Remote Machine
sudo nano /etc/hyprspace/hs1.yaml

Update Peer Configs

Now in each config we'll add the other machine's ID as a peer.
You can find each machine's ID at the top of their configuration file.
Update,

peers: {}

to

peers:
  10.1.1.2:
    id: YOUR-OTHER-PEER-ID

Notice here we'll have to pick one of our machines to be 10.1.1.1
and the other to be 10.1.1.2. Make sure to update the interface's IP
address for the machine who needs to change to be 10.1.1.2.

Update our Discover Key

Looking in the interface's configuration you'll also notice a field called
discover_key (right above the interface's private key). It doesn't matter
which discovery key you pick but it much be the same for all of the nodes in your little cluster
so that they can find each other.

(*Note you can use different discover_keys with different interfaces on the same
host to create different isolated networks.)

discover_key: fiftieth-dandelion-wronged-craftwork

Starting Up the Interfaces!

Now that we've got our configs all sorted we can start up the two interfaces!

Local Machine
sudo hyprspace up hs0

and

Remote Machine
sudo hyprspace up hs1

After a few seconds you should see a the network finish setting up
and find your other machine. We can now test the connection by
pinging back and forth across the network.

Local Machine
ping 10.1.1.2

Stopping the Interface and Cleaning Up

Now to stop the interface and clean up the system you can run,

Local Machine
sudo hyprspace down hs0

and,

Remote Machine
sudo hyprspace down hs1

GitHub

https://github.com/hyprspace/hyprspace