Husarnet Documentation
With Husarnet you can connect any device (laptops, servers, VMs, containers, microcontrollers etc.) with any interface (Wi-Fi, LTE/5G, Ethernet) into a peer-to-peer Virtual Private Network that works over the Internet with no configuration.
Read how Husarnet works and find all relevant documentation and tutorials here.
IT'S OPEN!
Husarnet Client is open source and available here: https://github.com/husarnet/husarnet
If you want to start right away, find an instruction for your target platform in the section below.
Using Husarnet
Before you go to the Installation procedure, get your Husarnet Join Code first. Join Code allows you to connect your devices to the same Husarnet network.
info
To get your Join Code:
- Setup a free account at Husarnet Dashboard: https://app.husarnet.com/accounts/register/
- Create a new network, click [ Add element ] button and go to
Join Code
tab - Join Code looks like that:
fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
- Linux
- Windows
- Container
- GitHub Actions
- ESP32
- MacOS ⏳
- Android ⏳
note
Husarnet Client for Linux
Supported architectures: i386, x64 (amd64), armhf, arm64, riscv64
Choose your Linux distribution:
- Debian, Ubuntu, CentOS, RHEL, Fedora or Mint
- Other distributions
For APT and Yum based Linux the simplest way to install Husarnet is to paste the following line into your terminal:
curl https://install.husarnet.com/install.sh | sudo bash
After installation process is finished, execute the following command:
sudo systemctl restart husarnet
Now export your Join Code as environment variable:
export JOINCODE=fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
To join your device to Husarnet network, execute:
sudo husarnet join $JOINCODE some-hostname
If your Linux distribution is not supported by the one-command install method, you can also download the binary package. For most seamless experience, it is recommended to unpack it in the root directory (/
):
curl https://install.husarnet.com/tgz/husarnet-latest-amd64.tar > husarnet-latest-amd64.tar
sudo tar --directory=/ --no-same-owner --dereference -xf husarnet-latest-amd64.tar
(replace -amd64
with -armhf
, -arm64
or -i386
if you don't have 64-bit Intel/AMD processor)
If you are using systemd, enable and start the service:
systemctl enable husarnet
systemctl start husarnet
otherwise start the Husarnet Daemon manually:
husarnet daemon &
Now export your Join Code as environment variable:
export JOINCODE=fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
To join your device to Husarnet network, execute:
sudo husarnet join $JOINCODE some-hostname
note
Husarnet Client container (sidecar)
Supported architectures: x64 (amd64), armhf, arm64
Choose a preffered method for running containers:
- docker run
- docker-compose
- ansible
To start a Husarnet Sidecar container execute:
docker run -it \
--name husarnet-vpn \
--env HOSTNAME='testing-container' \
--env JOINCODE='fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX' \
--volume husarnet-vol:/var/lib/husarnet \
--device /dev/net/tun \
--cap-add NET_ADMIN \
--sysctl net.ipv6.conf.all.disable_ipv6=0 \
husarnet/husarnet:latest
replace
fc94:...:932a/XXX...XXXXX
with your own Join Code
Now to give other containers on the same host access to your Husarnet network (using wordpress
container as an example):
docker run -it \
--network container:husarnet-vpn \
--volume wordpress-vol:/var/www/html \
wordpress
Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80
(because wordpress is hosted on port 80
by default)
To start a Husarnet Sidecar container that provides over-the-internet access for your application containers (in the example below - for wordpress
), create a docker-compose.yml
file:
version: '2.2'
services:
my-website:
image: wordpress
restart: unless-stopped
network_mode: service:husarnet
volumes:
- /var/www/html
husarnet:
image: husarnet/husarnet:latest
restart: unless-stopped
volumes:
- /var/lib/husarnet
sysctls:
- net.ipv6.conf.all.disable_ipv6=0
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun
environment:
HOSTNAME: testing-container
JOINCODE: fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
replace
fc94:...:932a/XXX...XXXXX
with your own Join Code
And execute:
docker-compose up
Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80
(because wordpress is hosted on port 80
by default)
To start a Husarnet Sidecar container that provides over-the-internet access for your application containers (in the example below - for wordpress
), create a playbook.yml
file:
- name: Wordpress available over Husarnet
hosts: localhost
tasks:
- name: Running Husarnet
community.docker.docker_container:
name: husarnet
image: husarnet/husarnet:latest
restart_policy: unless-stopped
volumes:
- /var/lib/husarnet
sysctls:
net.ipv6.conf.all.disable_ipv6: 0
capabilities:
- net_admin
devices:
- "/dev/net/tun:/dev/net/tun:rwm"
env:
HOSTNAME: testing-container
JOINCODE: fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
- name: Running Wordpress
community.docker.docker_container:
name: my-website
image: wordpress
volumes:
- wordpress:/var/www/html
network_mode: "container:husarnet"
replace
fc94:...:932a/XXX...XXXXX
with your own Join Code
And execute:
ansible-playbook playbook.yml
Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80
(because wordpress is hosted on port 80
by default)
note
Husarnet Action for GitHub Actions
Supported runners hosted by GitHub: ubuntu-18.04, ubuntu-20.04, ubuntu-latest
To use Husarnet in your GitHub workflow, create a .github/workflows/my-husarnet-workflow.yml
file with the following content in your GitHub repository:
name: Ping other peer from a VPN network
on: push
jobs:
build:
runs-on: ubuntu-20.04
steps:
- name: Connecting to Husarnet VPN network
uses: husarnet/husarnet-action@v1
with:
join-code: ${{ secrets.HUSARNET_JOINCODE }}
- name: Ping other peer
run: ping6 -c 10 my-laptop
- name: Stop husarnet
run: sudo systemctl stop husarnet
Create a new GitHub secret: HUSARNET_JOINCODE
and place your Join Code there.
Now after each commit, my-laptop
device (we assume that it is in the same Husarnet network) will be pinged 10 times.
note
Husarnet Client SDK for ESP32
Prerequisites: Install Visual Studio Code and platformio extension first!
Let's run a simple webserver hosted on ESP32 that is based on AsyncTCP
and ESPAsyncWebServer
libraries. They are not required by Husarnet to work, but are faster than default ones provided in Arduino Core for ESP32.
Create a folder for your ESP32 project, eg. esp32-proj
. Inside that folder create two files:
platformio.ini
src/simple-webserver.ino
with the following content:
- src/simple-webserver.ino
- platformio.ini
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <Husarnet.h>
// WiFi credentials
const char *ssid = "my-wifi-ssid";
const char *password = "my-wifi-pass";
// Husarnet credentials
const char *hostName = "esp32-webserver";
const char *husarnetJoinCode = "fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX";
// HTTP Server on port 8080
AsyncWebServer server(8080);
void setup(void)
{
Serial.begin(115200);
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.println("waiting for Wi-Fi...");
}
Husarnet.join(husarnetJoinCode, hostName);
Husarnet.start();
server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
request->send(200, "text/plain", "Hello world!!!");
});
server.begin();
}
void loop(void){}
[env]
platform = espressif32
framework = arduino
platform_packages =
framework-arduinoespressif32 @ https://github.com/husarnet/arduino-esp32/releases/download/1.0.4-1/arduino-husarnet-esp32.zip
lib_deps =
https://github.com/husarnet/AsyncTCP.git
Husarnet ESP32
ESP Async WebServer
[env:esp32dev]
board = esp32dev
monitor_speed = 115200
upload_speed = 921600
board_build.partitions = min_spiffs.csv
replace
fc94:...:932a/XXX...XXXXX
with your own Join Code and place your own Wi-Fi credentials in the*.ino
file
Open the project folder using Visual Studio Code. Platformio extension should now automatically download and install locally all required tools and libraries needed to build and flash a firmware.
Click PlatformIO: Upload
button in Visual Studio Code. After a few seconds your first HTTP webserver on ESP32 should be available from a level of any device from your Husarnet network under the following URL: http://esp32-webserver:8080
.
Reseting IPv6 addr
Husarnet IPv6 address of each ESP32 is stored in a flash. If you want to generate a new IPv6 address for you ESP32 run:
pio run --target erase
inside the project folder.
note
Husarnet Client for Windows [BETA]
Caution: Our Windows client is Work-in-Progress. Some things might not yet work exactly like in Linux client, and stability is not guaranteed. Feel welcome to report bugs and remarks on our Community Forums. Only 64-bit Windows is supported.
Download latest Husarnet Windows installer from our nightly repository and run the executable.
You are likely to get SmartScreen popup from Windows; unfortunately, Windows considers unsigned .exe
files as a threat to system security. Click on [More info] and you'll be able to run the installer as you would install any software on Windows.
After installer finishes working, service will start and you should be able to use Husarnet through the command line. Run cmd.exe or PowerShell and type:
husarnet status
If you see errors, try running elevated command prompt (Right-click and Run as administrator...)
If output looks OK, use Join Code to join a network:
husarnet join <JOINCODE> my-windows-dev
note
Husarnet Client for MacOS
is coming soon ... ⏳
note
Husarnet Client for Android
is coming soon ... ⏳
Tutorials & examples
We provide example applications for Husarnet on our blog, like:
- Making Raspberry Pi Internet connected on 1st boot
- WebRTC server hosted on RaspberryPi with connected USB camera
- Using Husarnet with Kata containers
- Configure reverse proxy for public access to services hosted by Husarnet connected
- Using Husarnet VPN for low-latency remote desktop (VNC) connections
- Using Husarnet VPN with Cyclone DDS and ROS 2
There is also a Husarnet Hackster profile where you can find sample applications for ESP32 powered IoT.
Troubleshooting
Common issues and ways to solve or report them are covered in this guide.