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.
If you want to know more about the internals How Husarnet works is a great start.
Support
Our preferred way of support is through Husarnet Community.
If you want you can reach us at support@husarnet.com too.
Husarnet Dashboard
Husarnet Dashboard is a platform for managing all your Client instances. You can create groups/check statuses/rename nodes and a lot more there.
In the Husarnet Dashboard Quick Start guide, you'll find all the important bits and pieces of information to become a poweruser.
Husarnet Client
Husarnet Client is open source and available for all supported platforms at: https://github.com/husarnet/husarnet
For typical "quickstart" setup, choose your platform below and see installation instructions. Alternative approaches and extended guides for all the platforms can be found in the sidebar on the left, in the "Platforms" section.
- Linux
- Windows
- Container
- GitHub Actions
- ESP32
- MacOS
- Android ⏳
Husarnet Client for Linux
Supported architectures: i386, x64 (amd64), armhf, arm64, riscv64
Choose your Linux distribution:
- Debian, Ubuntu, CentOS, RHEL, Fedora, Mint or Arch
- Other distributions
For APT, pacman 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
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
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='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)
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.
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.
Husarnet Client for Windows
Caution: Only 64-bit Windows is supported.
Download latest Husarnet Windows installer 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
Husarnet Client for MacOS [ALPHA]
Caution: Our MacOS 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.
Caution: Currently, we only support Apple Silicon devices (M1 arm architecture)
The binaries are available through Homebrew. You need to add our 'nightly', tap, as MacOS client is not yet in stable.
brew tap husarnet/tap-nightly
brew install husarnet
After installation finishes, you have to start the daemon and install it into launchctl, this is done via single command (requires sudo):
sudo husarnet daemon service-install
After couple of seconds you can check the status:
husarnet status
If the output looks OK, use Join Code to join a network:
husarnet join <JOINCODE> my-windows-dev
Husarnet Client for Android
is coming soon ... ⏳