This manual describes how to use Husarnet CLI (Command Line Interface). Husarnet CLI is powerful tool which allows you to:
- Manage Husarnet daemon running on the device i.e. examine current connectivity status, display and modify the whitelist, see software version and other typical tasks;
- Manage all your Husarnet devices and groups via intuitive and simple to use Dashboard API. You will only need to authenticate with your Husarnet account credentials.
Your devices with Husarnet daemon installed communicate with each other directly, without any central server forwarding traffic. That is a true low latency, peer-to-peer connection over the internet. Your devices see each other like they were in the same LAN.
Installing Husarnet (CLI & Daemon)
Husarnet CLI and Husarnet Daemon come as one package and are not meant to be installed separately.
I. Single command (recommended)
The simplest way to install Husarnet is to paste the following line into your terminal:
curl -s https://install.husarnet.com/install.sh | sudo bash
This method works on APT and Yum based Linux distributions such as Debian, Ubuntu, CentOS, RHEL, Fedora or Mint.
II. Setting up the Debian/Ubuntu repository manually
You can also set up Debian (works for all reasonably new versions of Ubuntu and Debian) repository manually:
sudo apt update && sudo apt install -y curl apt-transport-https
On Ubuntu 20.04, Debian 10 and older versions execute:
curl https://install.husarnet.com/repo.key | apt-key add -
echo 'deb https://install.husarnet.com/deb/ all husarnet' > /etc/apt/sources.list.d/husarnet.list
On Ubuntu 21.10, Debian 11 and newer versions execute
curl https://install.husarnet.com/repo.gpg > /usr/share/keyrings/husarnet.gpg
curl https://install.husarnet.com/husarnet_deb.repo > /etc/apt/sources.list.d/husarnet.list
And now continue with installation
sudo apt update && sudo apt install -y husarnet
III. Setting up the Yum repository manually
You can also set up the Yum repository manually:
rpm --import https://install.husarnet.com/repo.key
curl https://install.husarnet.com/husarnet_rpm.repo > /etc/yum.repos.d/husarnet.repo
yum install -y husarnet
IV. Totally manual binary installation (advanced)
Warning: this is not the recommended installation method. You won't get automatic software updates this way!
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
-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, make sure
husarnet daemon command is started on system startup. You need to run it as root, but don't worry - Husarnet automatically relinquishes unnecessary permissions.
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.
Husarnet CLI uses emojis in some outputs. These are not supported by standard cmd.exe and powershell.exe on Windows - if you see random characters here and there, change your terminal emulator to the one that supports full Unicode. Good one is official Microsoft's Windows Terminal
If you opened a terminal window before installing Husarnet, you might need to refresh your PATH (simply start new terminal session).
Some commands need Administrator-level privileges. If you see errors, try running elevated command prompt (Right-click and Run as administrator...)
Managing Husarnet Daemon via CLI
Open your terminal emulator and type:
You will see if your Husarnet Daemon is running, what is your Husarnet IP, what version you have installed and if there are any connectivity problems. The majority of the displayed information should be self-explanatory. If you are curious and/or see some issues, scroll down to Checking current status of the service section, which describes the output in great detail.
husarnet status is actually an alias for longer command -
husarnet daemon status. Husarnet's CLI has a lot of aliases - be sure to type
husarnet help, and then
husarnet help <command> to discover how you can use the CLI in a way that is more intuitive for you.
Joining a group
The purpose of Husarnet is to quickly and securely connect your devices together. This is achieved via joining a group. To join a group you will need the Join Code. Login to your account at https://app.husarnet.com, select a group, click Add element button and go to a join code tab. Join Code is unique for each group. Alternatively, you can login via command line, as described in Managing your devices and device groups via CLI below.
Once you have the Join Code, type:
husarnet join [JOIN_CODE] [HOSTNAME]
Where [HOSTNAME] is the hostname of given device. If omitted, Husarnet will use the local hostname.
Keep your join code secret! If you consider your join code might be compromised, click [Reset join code] button in a [join code] tab. Devices that already were connected using previous join code, still will be in your Husarnet groups, however previous join code will not be valid for adding new devices to your groups.
Checking current status of the service
In this part, we will describe information you can get from the output of
husarnet status command. Let's see the example output:
$ husarnet status
🟢 CLI: 2022.10.20.2
🟢 Daemon (running): 2022.10.20.2
🟢 Daemon (binary): 2022.10.20.2
🟢 CLI: app.husarnet.com
🟢 Daemon: app.husarnet.com
🟢 Base Server: 18.104.22.168:5582 (UDP)
🟢 Is ready to handle data? yes
🟢 Is ready to join? yes
🟢 Is joined? yes
⚪ Husarnet IP:
⚪ inactive 🟢 secure 🟡 tunelled
⚪ inactive 🟢 secure 🟡 tunelled
⚪ inactive 🟢 secure 🟡 tunelled
fc94:d797:bcdf:d20a:e2dc:c25e:2536:c1cd (localhost) gnaarmok
⚪ inactive ⚪ no data flow 🟡 tunelled
Red/Yellow/Green dot emojis are basic indicator of health of particular part of the system. Green dot means the value is as expected. Yellow typically means that something might be a problem (but Husarnet still works). Red is for errors, and white is neutral information.
Below we will dive deeper into each section.
husarnet status has a verbose flag. Type
husarnet status -v to get even more info. This is useful, for example while posting a support request on our Community Forums, or just if feeling curious.
Here we can see the version of the software.
Why three version strings? Husarnet comes in two binaries -
husarnet, which is CLI program you will use on day-to-day basis, and
husarnet-daemon, which is typically managed by
systemd (or platforms' equivalent) and is not intended to be used directly. First on the list is the version of CLI app, second is currently running daemon and the third is daemon binary as it is on the disk. All three versions should match. There might be situations, like for example when software update does not apply cleanly, that can cause divergence in version numbers. The CLI will inform you in this case.
This sections informs you what to type into web browser address bar to see Husarnet Dashboard web app. For majority of users, it will be app.husarnet.com. It can, however, be different for users of self-hosted Husarnet plans.
In this section you can see the address of the Base Server your device is connected to at the moment and which transport method it is using. If you see UDP and green dot here, everything is good.
If you see yellow dot and information as below you are connected to Base Server via TCP:
🟡 Base Server: 22.214.171.124:443 (TCP)
🟡 TCP is a fallback connection method. You'll get better results on UDP
Husarnet will work, but latency and performance will be negatively impacted.
If you see red dot, there is no connection to Base Server and establishing new connections over Husarnet will not be possible (except for the local network).
See Troubleshooting Guide to find out how to deal with these problems. If you want, you can also read what is the purpose of Base Server to gain better understanding of the role of Base Servers in the system.
Readiness flags will inform you if Husarnet Daemon is properly initialized. They are as follows:
🟢 Is ready to handle data? yes
This flag will be green if Husarnet Daemon is able to contact the Base Server.
🟢 Is ready to join? yes
This flag will be green if connection to Websetup, therefore joining, is possible. If you see "yes" here, but "no" down below on "Is joined" flag, you can join a group
🟢 Is joined? yes
This flag will be green if successful join already happened for this device, and will be red otherwise.
In this section you can see the IPv6 address of current device in Husarnet network.
Each instance of Husarnet Daemon maintains a whitelist. The concept is simple: if given IPv6 address is on the whitelist, then it can send packets to current device. Typically whitelist is managed by the Dashboard (i.e. if you add your device to a group in the Dashboard, all of the devices are notified of new member and will add it to their own whitelists); in some rare cases, however, it can be useful to manage it manually (you can read how to do it in Managing the whitelist section below).
Note: if you are using official Husarnet infrastructure, i.e. https://app.husarnet.com, our Websetup Server will always be on your whitelist, probably as the first device whitelist contains. It's address is
Each whitelist entry will contain IPv6 address and hostname of the device. Additionally, there will be flags indicating status of the connection:
Activity: you will see
⚪ inactiveif the peer is acknowledged, but the connection to given peer is not established yet. You will see
🟢 activeif there is a connection.
Data flow: you will see
⚪ no data flowif the peer is known, but the data is not exchanged at the moment (peer is idle). You will see
🟢 secureif data is transmitted through Husarnet link.
P2P status: you will see
🟢 peer to peerif there is direct link between current device and given peer (Base Server does not take part in data exchange) and
🟡 tunelledif the data has to be forwared through Base Server (because P2P link was not obtainable).
Managing the whitelist
To see what devices are on your whitelist, type:
husarnet daemon whitelist ls
PS C:\Users\husarnetman> husarnet daemon whitelist ls
fc94:5947:c16d:788d:26d7:74e0:dead:beef (localhost) husarnet-win11 master
⚪ inactive ⚪ no data flow 🟢 peer to peer
🟢 active 🟢 secure 🟡 tunelled
⚪ inactive ⚪ no data flow 🟡 tunelled
To add/remove IPv6 addresses, use following commands:
husarnet daemon whitelist add <IPv6_address>
husarnet daemon whitelist rm <IPv6_address>
You can also enable the whitelist (the default) or disable it completely. Disabling whitelist is highly discouraged, as it makes our device open for connections from any other Husarnet device. Anyone doing this is expected to have very good reason to do so, and is required to properly set up some firewall by themselves (on top of Husarnet).
husarnet daemon whitelist enable
husarnet daemon whitelist disable
Turning the daemon on and off
You can use the CLI to start, restart and stop Husarnet Daemon. Note that on Windows, these will only work if you are running them from elevated command prompt (as Administrator). On Linux, these are equivalent to starting/stopping the service via
systemctl (if you are not on root, the CLI will try to rerun the command with
husarnet daemon restart
husarnet daemon start
husarnet daemon stop
Switching to another instance of Husarnet Infrastructure
This command is applicable only to self-hosted plans of Husarnet.
In Husarnet self-hosted plans, your Dashboard instance is not on https://app.husarnet.com - it resides under your custom domain. Each instance of Husarnet Daemon must know this address. This is how you set it up:
husarnet daemon change-dashboard <MY_DASHBOARD_ADDRESS>
The address has to be provided without the scheme (i.e. app.husarnet.com, not https://app.husarnet.com)
To connect back to official production infrastructure, type simply:
husarnet daemon change-dashboard app.husarnet.com
Executing this command requires restarting the daemon. The CLI will prompt for restart.
Managing your devices and device groups via CLI
You can use Husarnet CLI as a replacement for using the Dashboard web app. If you feel more comfortable in your terminal emulator than in the web interface, this is section for you.
Everything (and more) that can be done in the Dashboard web app, can also be done via the CLI. CLI is first-class citizen in Husarnet.
In order to query against Dashboard API, you will need to authenticate first with your Dashboard account credentials. You can do it explicitly, by executing
husarnet dashboard login, but this can be skipped, because the program will ask you for credentials whenever you will try to query the API unauthenticated.
After successful login, an auth token is created and saved on your device. The token is valid for 30 minutes, so you don't need to login again on subsequent queries. Any query you execute gives you a new token, so the timer is reset with every API-utilizing command. The program will prompt for password again in case your token expires.
Examining your groups
Start by simply listing all your device groups:
husarnet dashboard group ls
⎯⎯⎯ Your groups ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
ID | Name | DeviceCount | JoinCode
112 | some group | 2 | WspSomeJCztzaiQCdyW7st
234 | empty group | 0 | beUC39nh6SomeJCx3xF4kL
356 | my_devices | 4 | ZD47XPYiop85SomeJCYsfM
You should see the same groups as in the Dashboard. To see details about specific group, type:
husarnet dashboard group show <ID>
ID parameter is optional. When omitted, CLI will display interactive prompt allowing you to choose the group you want to see. Type fragment to narrow the search:
This interactive prompt is available for any command where typically you would pass an ID, so
remove too. Try it out!
Creating, renaming and removing groups
To add a new group interactively, type:
husarnet dashboard group create
The program will prompt for group name, and after group is created will display it's ID. You can also do it non-interactively by passing name as a parameter:
husarnet dashboard group create <NAME>
To remove a group interactively, type:
husarnet dashboard group remove
To remove a group non-interactively, you must provide an ID or name:
husarnet dashboard group remove <ID or NAME>
To rename a group interactively, type:
husarnet dashboard group rename
You will be prompted to type new name.
To do it in one command, provide ID or name as first argument, and new name as second:
husarnet dashboard group rename <ID or NAME>
Hint: if the name of your group has spaces, wrap it around with quotation marks e.g.
husarnet dashboard group rename "my old group" "my new group"
Listing your devices
To see all devices assigned to your account, type:
husarnet dashboard device ls
⎯⎯⎯ Your devices ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
ID(ipv6) | Name | Version | UserAgent | Groups containing device
fc94:a2d1:1a9b:1cf3:85d8:e999:deaf:cafe | raspberry | 2022.07.13.2 | Husarnet,Unix,2022.07.13.2 | test-group1
fc94:b9e8:a45e:14f8:483d:b0f0:fade:deaf | laptop | 2021.12.29.1 | Linux daemon | test-group1, test2
fc94:0a66:d26c:803e:395f:f935:dead:beef | motorola | 2019.04.24.1 | Android VPN | test2
Displayed information includes:
- IPv6 address of the device
- name (hostname)
- Husarnet Daemon version installed
- User Agent (UA) string, which is basically platform/OS information
- Names of all groups the device is assigned to
Assigning/Unassigning a device to a group
Warning: Your device must be joined first!
To assign a device to a new group interactively, type:
husarnet dashboard assign
The program will let you to select the device from the list first, and in the second step which group should the device be assigned to.
To do it in one command, type:
husarnet dashboard assign <DEVICE_NAME> <GROUP_NAME>
To reverse the operation, i.e. unassign, analogous commands apply. Interactive version:
husarnet dashboard unassign
husarnet dashboard unassign <DEVICE_NAME> <GROUP_NAME>
Note: after this operation, the device is still joined to the account, even if you unassign it from all groups. There is never a need to join the device more than once.
I can't find the info I'm looking for in the docs!
Let us know! Describe your problem and post it on Husarnet Community Forums.