Skip to main content

Launching Husarnet in a Docker container

Launching Husarnet inside of a Docker container is straightforward and can be accomplished in a couple of steps.

Preparing a Dockerfile#

First, we need to build an appropriate Docker image. We assume your base image might slightly differ from ours but that should not be a problem. For the purposes of this tutorial, we will use the latest (as of today) Ubuntu image and base the installation process on it.

Create a Dockerfile:

FROM ubuntu:20.04
# Install Husarnet Client and deppendenciesRUN apt update -yRUN apt install -y curl gnupg2 systemdRUN curl | bashRUN update-alternatives --set ip6tables /usr/sbin/ip6tables-nft
# Find your JOINCODE at https://app.husarnet.comENV JOINCODE=""
ENTRYPOINT (husarnet daemon > /dev/null 2>&1 &) && /bin/bash

As mentioned before, I'm using the Ubuntu:20.04 image. Feel free to adjust it to your needs.

Also, it is not necessary to add the && /bin/bash portion of ENTRYPOINT. It is convenient for this sample use case because it automatically spawns a shell upon running docker run ... without the need to provide extra arguments.

Building an image#

This is rather straightforward: inside of the directory containing Dockerfile, run

docker build -t husarnet_client .

Get your Husarnet JoinCode#

To connect a container to your Husarnet Dashboard account, you need to find your Join Code.

You will find your Join Code at
-> Click on the desired network
-> Add element button
-> Join code tab

…and change the JOINCODE variable in the listing below to your Join Code.

Running a container#

You can now run the container. We have two main options here:

  • run the container in privileged mode. This is absolutely not recommended as it exposes your host machine to the container and violates container isolation. We're' not going to go deeper into this method.

  • configure the container manually. This comes down to using a couple of flags.

    The command to start the container is as follows:

    sudo docker run --rm -it \--device /dev/net/tun \--cap-add NET_ADMIN \--sysctl net.ipv6.conf.all.disable_ipv6=0 \--volume husarnet-v:/var/lib/husarnet \--env JOINCODE='fc94:b01d:1803:8dd8:3333:2222:1234:1111/xxxxxxxxxxxxxxxxx' \husarnet_client

Connecting to Husarnet Dashboard#

Having followed the steps above, a shell inside of the container should be spawned. You can now use the client as if you were on a native system.

  • To connect a container to your Husarnet network execute (with my-dev hostname):
husarnet join ${JOINCODE} my-dev
  • To check a status of Husarnet VPN Client
husarnet status

Now you can play in the terminal, ping other peers, and so on. Example terminal output might look like that:

Click here to view example terminal output
root@42b31a880faf:/# husarnet statusVersion: 2020.06.29.1Husarnet IP address: fc94:beb4:7e5e:e2e3:ac66:cb8c:0b52:3790UDP connection to base: []:5582
root@42b31a880faf:/# husarnet join ${JOINCODE} mydev1[125430943] joining...[125432947] joining...root@42b31a880faf:/# root@42b31a880faf:/# root@42b31a880faf:/# husarnet statusVersion: 2020.06.29.1Husarnet IP address: fc94:beb4:7e5e:e2e3:ac66:cb8c:0b52:3790UDP connection to base: []:5582Peer fc94:b01d:1803:8dd8:b293:5c7d:7639:932a  source=[]:5582   addresses from base=[]:5582 []:5582 []:5582 []:5582 []:5582 []:5582 []:5582   target=[]:5582  secure connection established
root@42b31a880faf:/# root@42b31a880faf:/# ping6 fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0PING fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0(fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0) 56 data bytes64 bytes from fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0: icmp_seq=2 ttl=3 time=39.4 ms64 bytes from fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0: icmp_seq=3 ttl=3 time=49.1 ms64 bytes from fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0: icmp_seq=4 ttl=3 time=58.3 ms64 bytes from fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0: icmp_seq=5 ttl=3 time=45.6 ms64 bytes from fc94:edd8:9a3c:d84:cdee:921c:968d:8ad0: icmp_seq=6 ttl=3 time=1.70 ms


This is a super basic way to deal with Husarnet Client with Docker. The recommended way, however, is to use official Husarnet Docker image next to your existing containers.

More resources#

Read more about more practical (and even easier!) ways of using Husarnet & Docker on our blog: