Jump to content
Not connected, Your IP: 216.73.217.99
AirVPN
Hummingbird

AirVPN Suite's Hummingbird for Linux and macOS

AirVPN's free and open source OpenVPN 3 and WireGuard client based on AirVPN's OpenVPN 3 library fork

Version 2.2.0 (Linux) - Release date 15 October 2026

Version 2.1.0 (macOS) - Release date 15 June 2026

Main features:

  • Lightweight and standalone binary

  • No heavy framework required, no GUI

  • Tiny RAM footprint

  • Lightning fast

  • OpenVPN support is based on OpenVPN 3 library fork by AirVPN with tons of critical bug fixes from the main branch, new cipher support and never-seen-before features

    • ChaCha20-Poly1305 cipher support on both Control and Data Channel providing great performance boost on ARM, Raspberry PI and any Linux-based platform not supporting AES-NI. Note: ChaCha20 support for Android has already been implemented in our free and open source Eddie Android edition

  • WireGuard support is implemented through the high-performance built-in Linux kernel module. macOS support is provided by means of WireGuard's official tools.

  • Robust leak prevention through Network Lock based either on iptables, nftables or pf through automatic detection

  • Proper handling of DNS push by VPN servers, working with resolv.conf as well as with any operational mode of systemd-resolved

  • Word completion (auto completion) support for bash and zsh

Contents

How to Install AirVPN Hummingbird Client for Linux - Raspberry and macOS

Hummingbird is distributed both in binary and source code forms. Both the binary version and the complete source code are available in the official gitlab repository. For more information, feedback and latest news, please refer to AirVPN forum and related threads.

Requirements

Linux

  • x86-64 (64 bit), ARM 32 or ARM 64 bit CPU
  • A reasonably recent Linux distribution
  • OpenSSL 3.x
  • tar
  • sha512sum (optional)
  • ldd (optional)

Linux (legacy)

  • x86-64 (64 bit), ARM 32 or ARM 64 bit CPU
  • OpenSSL 1.1.1 series (any release from 1.1.1 to 1.1.1w)
  • tar
  • sha512sum (optional)
  • ldd (optional)

macOS

  • Macintosh computer with Intel or Apple Silicon M series architectures
  • macOS Mojave (10.14) or later on Intel, macOS Big Sur (11.0) or later on Apple Silicon
  • tar for the plain version, unzip for the notarized version
  • shasum (optional)
  • otool (optional)

Linux

Hummingbird for Linux x86-64, armv7l (32 bit) and arm64 (aarch64) is distributed with the AirVPN Suite. Please refer to the AirVPN Suite README.md for installation instructions.

Please note Hummingbird client needs root privileges to run. Your user must therefore be included in your system's "sudoers" (depending on specific Linux distribution)

Note about SELinux

In case your system has SELinux and Hummingbird is started from a systemd unit at boot time, please note that SELinux will prevent nft from being called by Hummingbird, because access to stdin is forbidden by the default policy. In this specific case, Hummingbird will be unable to enforce Network Lock rules via nft and you need to create a specific SELinux exception to do that.

macOS Installation

Hummingbird for macOS is distributed in four versions according to architecture and code signature. The distribution files are identified as follows:

Intel x86_64 architecture:

Apple Silicon M series architectures:

The difference lies in how the package is seen by macOS security, and it is therefore up to the user to pick the distribution file best suiting his or her needs. The signed and notarized version is compliant with the macOS software security scheme and runs "out of the box", whereas the plain version needs to be explicitly granted permission to run by the user in the macOS Security & Privacy settings. Please note both versions are the same binary and ensure the very same functionality in connecting to a VPN server; it is however up to the user to decide whether to use the signed and notarized version or not.

Installing the Signed and Notarized Version

Intel x86_64 Architecture
  • Download hummingbird-macos-x86_64-notarized-2.1.0.zip
  • [optional] Download hummingbird-macos-x86_64-notarized-2.1.0.zip.sha512 This file is needed to check the integrity of the above zip archive. It is not mandatory but it is strongly advised to download this file and check the zip archive integrity
  • [optional] Open a terminal window
  • [optional] Check the integrity of the zip archive by issuing this command: shasum -a 512 -c hummingbird-macos-x86_64-notarized-2.1.0.zip.sha512
  • [optional] Make sure the command responds with hummingbird-macos-x86_64-notarized-2.1.0.zip: OK
  • Change your current directory to a convenient place, such as your home directory. This can be done by issuing the command cd ~
  • Extract the zip archive by issuing this command in your terminal window: unzip -x hummingbird-macos-x86_64-notarized-2.1.0.zip
  • A new directory will be created: hummingbird-macos-x86_64-2.1.0
  • Move into this new directory by entering command cd hummingbird-macos-x86_64-2.1.0
  • [optional] Check the integrity of the binary file hummingbird. Issue this command from your terminal window: shasum -a 512 -c hummingbird.sha512
  • [optional] Make sure the command responds with hummingbird: OK
  • [optional] Check dynamic library availability. Issue the command otool -L hummingbird and make sure all the required dynamic libraries are available. No line of the output must contain "not found". Please note otool is distributed with Xcode
  • The macOS client is now ready to be used and possibly copied to a different directory of your system, such as /usr/bin or /usr/local/bin
Apple Silicon M series Architectures
  • Download hummingbird-macos-arm64-notarized-2.1.0.zip
  • [optional] Download hummingbird-macos-arm64-notarized-2.1.0.zip.sha512 This file is needed to check the integrity of the above zip archive. It is not mandatory but it is strongly advised to download this file and check the zip archive integrity
  • [optional] Open a terminal window
  • [optional] Check the integrity of the zip archive by issuing this command: shasum -a 512 -c hummingbird-macos-arm64-notarized-2.1.0.zip.sha512
  • [optional] Make sure the command responds with hummingbird-macos-arm64-notarized-2.1.0.zip: OK
  • Change your current directory to a convenient place, such as your home directory. This can be done by issuing the command cd ~
  • Extract the zip archive by issuing this command in your terminal window: unzip -x hummingbird-macos-arm64-notarized-2.1.0.zip
  • A new directory will be created: hummingbird-macos-arm64-2.1.0
  • Move into this new directory by entering command cd hummingbird-macos-arm64-2.1.0
  • [optional] Check the integrity of the binary file hummingbird. Issue this command from your terminal window: shasum -a 512 -c hummingbird.sha512
  • [optional] Make sure the command responds with hummingbird: OK
  • [optional] Check dynamic library availability. Issue the command otool -L hummingbird and make sure all the required dynamic libraries are available. No line of the output must contain "not found". Please note otool is distributed with Xcode
  • The macOS client is now ready to be used and possibly copied to a different directory of your system, such as /usr/bin or /usr/local/bin

Please note Hummingbird needs root privileges to run. Also note the notarized version has been signed with AirVPN di Paolo Brini Apple developer certificate (ASC provider ID: A7P5AKGWFC)

Installing the Plain Version

Intel x86_64 Architecture
  • Download hummingbird-macos-x86_64-2.1.0.tar.gz
  • [optional] Download hummingbird-macos-x86_64-2.1.0.tar.gz.sha512 This file is needed to check the integrity of the above tar archive. It is not mandatory but it is strongly advised to download this file and check the tar archive integrity
  • [optional] Open a terminal window
  • [optional] Check the integrity of the tar archive by issuing this command: shasum -a 512 -c hummingbird-macos-x86_64-2.1.0.tar.gz.sha512
  • [optional] Make sure the command responds with hummingbird-macos-x86_64-2.1.0.tar.gz: OK
  • Change your current directory to a convenient place, such as your home directory. This can be done by issuing the command cd ~
  • Extract the tar archive by issuing this command in your terminal window: tar xvf hummingbird-macos-x86_64-2.1.0.tar.gz
  • A new directory will be created: hummingbird-macos-x86_64-2.1.0
  • Move into this new directory by entering command cd hummingbird-macos-x86_64-2.1.0
  • [optional] Check the integrity of the binary file hummingbird. Issue this command from your terminal window: shasum -a 512 -c hummingbird.sha512
  • [optional] Make sure the command responds with hummingbird: OK
  • [optional] Check dynamic library availability. Issue the command otool -L hummingbird and make sure all the required dynamic libraries are available. No line of the output must contain "not found". Please note otool is distributed with Xcode
  • The macOS client is now ready to be used and possibly copied to a different directory of your system, such as /usr/bin or /usr/local/bin
Apple Silicon M series Architectures
  • Download hummingbird-macos-arm64-2.1.0.tar.gz
  • [optional] Download hummingbird-macos-arm64-2.1.0.tar.gz.sha512 This file is needed to check the integrity of the above tar archive. It is not mandatory but it is strongly advised to download this file and check the tar archive integrity
  • [optional] Open a terminal window
  • [optional] Check the integrity of the tar archive by issuing this command: shasum -a 512 -c hummingbird-macos-arm64-2.1.0.tar.gz.sha512
  • [optional] Make sure the command responds with hummingbird-macos-arm64-2.1.0.tar.gz: OK
  • Change your current directory to a convenient place, such as your home directory. This can be done by issuing the command cd ~
  • Extract the tar archive by issuing this command in your terminal window: tar xvf hummingbird-macos-arm64-2.1.0.tar.gz
  • A new directory will be created: hummingbird-macos-arm64-2.1.0
  • Move into this new directory by entering command cd hummingbird-macos-arm64-2.1.0
  • [optional] Check the integrity of the binary file hummingbird. Issue this command from your terminal window: shasum -a 512 -c hummingbird.sha512
  • [optional] Make sure the command responds with hummingbird: OK
  • [optional] Check dynamic library availability. Issue the command otool -L hummingbird and make sure all the required dynamic libraries are available. No line of the output must contain "not found". Please note otool is distributed with Xcode
  • The macOS client is now ready to be used and possibly copied to a different directory of your system, such as /usr/bin or /usr/local/bin

Please note Hummingbird needs root privileges to run.

WireGuard Support

WireGuard connections on macOS are supported by means of the official WireGuard tools provided by its developers. To use WireGuard with Hummingbird on macOS you need to install these tools on your system, specifically the wg and wireguard-go binaries.

AirVPN suggests using the packages provided by the Homebrew package manager, available at https://brew.sh. The installation is straightforward: simply issue the command below in a shell terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You are however invited to visit the Homebrew website for the latest installation procedure for your macOS version.

Upon successful installation, you can proceed and install WireGuard tools by entering the following commands in the shell terminal:

brew install wireguard-go

and then

brew install wireguard-tools

Please note Hummingbird always checks that the WireGuard tools are properly installed on your system before attempting any WireGuard connection.

Note on Checksum Files

We strongly suggest that you check the integrity of both the distribution package files (tar.gz or zip) and the hummingbird binary to make sure you are installing a binary created and fully supported by AirVPN. Please read CHECKSUM.md for more information and to get the checksum codes created and guaranteed by AirVPN.

Running the Hummingbird Client

Run hummingbird and display its help to become familiar with its options. From your terminal window issue this command:

sudo ./hummingbird --help

After having entered your password, hummingbird responds with:

Hummingbird - WireGuard/OpenVPN3 Client 2.2.0 - 15 October 2026

OpenVPN core 3.12 AirVPN (20260514) linux x86_64 64-bit
Copyright (C) 2012- OpenVPN Inc. All rights reserved.
OpenSSL 3.5.4 30 Sep 2025
AirVPN WireGuard Client 2.0.0 Linux x86_64 64-bit

usage: hummingbird [options] <config-file>

--help, -h : Show this help page
--version, -v : Show version info
--eval, -e : Evaluate profile only (standalone)
--username, -u : Username
--password, -p : Password
--response, -r : Static response
--dc, -D : Dynamic challenge/response cookie
--cipher, -C : Encrypt packets with specific cipher algorithm <alg>
--list-data-ciphers : List supported data ciphers
--proto, -P : Protocol override <udp|tcp>
--server, -s : Server override
--port, -R : Port override
--tcp-queue-limit, -l : Size of TCP packet queue <1..65535> default 8192
--mtu : WireGuard MTU
--network-lock, -N : Network filter and lock mode <on|iptables|nftables|pf|off> default on
--allow-private-network : Allow private IPv4 and IPv6 network classes to pass to and from the network filter. <on|off> default on
--allow-ping : Allow Ping to pass to and from the network filter. <on|off|input|output> default output
--allow-ipv6ndp : Allow IPv6 NDP to pass to and from the network filter. <on|off> default on
--gui-version, -E : Set custom gui version <text>
--ignore-dns-push, -i : Ignore DNS push request and use system DNS settings
--allowuaf, -6 : Allow unused address families <yes|no|default>
--timeout, -t : Timeout <seconds>
--compress, -c : Compression mode <yes|no|asym>
--pk-password, -z : Private key password
--tvm-override, -M : Tls-version-min override <disabled|default|tls_1_x>
--tcprof-override, -X : Tls-cert-profile override <legacy|preferred|etc.>
--proxy-host, -y : HTTP proxy hostname/IP
--proxy-port, -q : HTTP proxy port
--proxy-username, -U : HTTP proxy username
--proxy-password, -W : HTTP proxy password
--proxy-basic, -b : Allow HTTP basic auth
--alt-proxy, -A : Enable alternative proxy module
--cache-password, -H : Cache password
--no-cert, -x : Disable client certificate
--def-keydir, -k : Default key direction <bi|0|1>
--ssl-debug : SSL debug level
--auto-sess, -a : Request autologin session
--auth-retry, -Y : Retry connection on auth failure
--persist-tun, -j : Keep TUN interface open across reconnects
--peer-info, -I : Peer info key/value list in the form K1=V1,K2=V2,...
--gremlin, -G : Gremlin info <send_delay_ms|recv_delay_ms|send_drop_prob|recv_drop_prob>
--epki-ca : Simulate external PKI cert supporting intermediate/root certs
--epki-cert : Simulate external PKI cert
--epki-key : Simulate external PKI private key
--recover-network : Recover network settings after a crash or unexpected exit
--remove-wireguard-device : Remove any existing WireGuard tunnel device after a crash or unexpected exit

Open Source Project by AirVPN (https://airvpn.org)

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help,
support, suggestions and testing.

Hummingbird needs a valid OpenVPN or WireGuard profile to connect to a server. You can create a VPN profile by using the config generator available on the AirVPN website in your account's Client Area

Start a VPN connection

Hummingbird can start both OpenVPN and WireGuard connections by providing a proper configuration file or profile. The profile type is automatically recognized by Hummingbird, which will start the corresponding VPN connection accordingly.

Start an OpenVPN connection

sudo ./hummingbird your_openvpn_file.ovpn

Start a WireGuard connection

sudo ./hummingbird your_wireguard_file.conf

Stop a connection

Type CTRL+C in the terminal window where Hummingbird is running. The client will initiate the disconnection process and will restore your original network settings according to your options.

Start a connection with a specific cipher

sudo ./hummingbird --cipher CHACHA20-POLY1305 your_openvpn_file.ovpn

Please note: to properly work, the server you are connecting to must support the cipher specified with the --cipher option.

Disable the network filter and lock

sudo ./hummingbird --network-lock off your_openvpn_file.ovpn

Ignore the DNS servers pushed by the VPN server

sudo ./hummingbird --ignore-dns-push your_openvpn_file.ovpn

Please note: the above options can be combined together according to their use and function.

Controlling Hummingbird

Hummingbird uses the following system signals to control specific actions. You can send a signal to Hummingbird by using the kill command from a terminal.

  • SIGTERM, SIGINT, SIGPIPE, SIGHUP : Disconnect the active VPN connection

  • SIGUSR1: This is actually a toggle signal to be used to both pause and resume VPN connection. In case Hummingbird is connected to a VPN server, the connection is paused, whereas in case it is paused, VPN connection will be resumed. When the VPN connection is paused, the tunnel device status is controlled according to --persist-tun option. Also consider that pausing and resuming a connection is allowed only in case TUN persistence is enabled.

  • SIGUSR2: Reconnect (restart) the current VPN connection. Reconnecting a connection is allowed only in case TUN persistence is enabled.

Note on macOS and UDP

Because of some architectural specifications and implementation in macOS, in particular in case of high speed traffic - a condition becoming more and more common in modern internet technology and infrastructure - Hummingbird may warn the user about shortage of buffer space, specifically when connected with the UDP protocol.

This condition is signaled by Hummingbird with the below messages in the log:

UDP send exception: send: No buffer space available
ERROR: NETWORK_SEND_ERROR

This error is caused by the maximum size set in macOS for network sockets, a value usually small and unsuited for modern high speed networks, specifically in case the VPN is connected with the UDP protocol. The solution to this problem consists of increasing the maximum allowed size for socket buffers and, in case the problem persists, to increase the number of mbuf clusters.

In this regard, it should be considered that each mbuf cluster in macOS has a fixed size of 2 KB and the maximum socket buffer size cannot be greater than 1/16 of the total memory allocated by the system for mbuf clusters.

For example, in case the number of mbuf clusters is set to 32768 (this is likely to be the default value in most macOS systems), the total memory allocated for this purpose is 32768 * 2 KB, therefore 64 MB. The maximum socket buffer size is hence set to 1/16 of 64 MB, therefore 4 MB.

To find out the current values set on your system, you can use the following commands. Please note, you need to be root to manipulate these settings according to the commands provided below.

sysctl -a kern.ipc.nmbclusters

and

sysctl -a kern.ipc.maxsockbuf

to respectively get the current values set for the number of mbuf clusters and the maximum socket buffer size.

In case the current number of mbuf clusters set on your system allows it, you can change the maximum socket buffer size by issuing the following command:

sysctl -w kern.ipc.maxsockbuf=<size_in_bytes>

For example, to set the maximum socket buffer size to 16 MB, this can be done with the below command:

sysctl -w kern.ipc.maxsockbuf=16777216

The above value is accepted by the system only in case the number of mbuf clusters is equal to or greater than 131072 (131072 * 2 KB = 268435456 = 256 MB)

Important note: by using sysctl command as described above, the value is set for the current session only and it is not permanent. This means when the machine is restarted or powered on, the above values will be reset to their respective default values and according to the macOS version in use. To make these changes permanent and properly set up at system start-up, please refer to the procedures provided for the specific macOS version in use.

In case the current kern.ipc.nmbclusters value is not enough to properly increase kern.ipc.maxsockbuf, you can permanently change the value of ncl boot argument by issuing this command:

nvram boot-args="ncl=<number_of_mbuf_clusters>"

Please remember each mbuf cluster equates to 2 KB of RAM, therefore in case you want to set the size of memory used for mbuf clusters to 256 MB, therefore allowing a maximum value for kern.ipc.maxsockbuf of 16 MB, you can multiply this value (in bytes) by 16, then divide it by 2048 (2 KB in bytes), therefore yielding the number of mbuf clusters.

16777216 * 16 = 268435456 (256 MB)

268435456 / 2048 = 131072

to make this value permanent you then need to issue the command:

nvram boot-args="ncl=131072"

then restart your system:

shutdown -r now

Upon reboot you are now allowed to set kern.ipc.maxsockbuf to 16 MB.

Network Filter and Lock

Hummingbird's network filter and lock natively uses iptables, iptables-legacy, nftables and pf to provide a "best effort leak prevention". Hummingbird will automatically detect and use the infrastructure available on your system.

The --network-lock option defaults to on: in this case Hummingbird automatically detects and uses the firewall installed on your system, using this priority: iptables-legacy, iptables, nftables and finally pf. To force a specific firewall, specify its name in the same option, for example --network-lock nftables. Please note the firewall must be properly installed on your system.

Also note in case both iptables and iptables-legacy are installed on your system, Hummingbird will use iptables-legacy.

Note on nftables: nftables rules created and issued by Hummingbird follow the specification and behavior of nftables version 0.9. In case you detect nftables errors or it seems to not be working properly, please check nftables installed on your system and make sure it is compatible with 0.9 specifications.

Please note: Linux services firewalld and ufw may interfere with Hummingbird's network filter and lock and you are strongly advised not to issue any firewall-related command while the VPN connection is active.

Note on firewalld and Linux

In case the firewalld service is running and it is set to own nftables tables, this will strongly interfere with Hummingbird, in particular, with system netfilter restore at disconnection.

In its default settings, firewalld is the owner of its nftables tables and, by default, will interfere with any application when trying to interact with nftables tables created and owned by firewalld. This condition will make nftables issue an error at the moment of tables modification, including tables restore, as in the case of Hummingbird. In this specific case, Hummingbird will also fail to restore the system network settings, therefore causing a "dirty" network status.

In case firewalld is set to be the owner of nftables tables, Hummingbird will issue a warning in the log, therefore inviting the system administrator to change this setting.

To change firewalld settings to let Hummingbird work properly and to proficiently interact with the system, you need to edit firewalld's configuration file /etc/firewalld/firewalld.conf, set the option NftablesTableOwner to no and then restart firewalld. Please note, by default, NftablesTableOwner is set to yes, so, in case you do not see this line in the configuration file, you explicitly need to add it and set NftablesTableOwner=no.

DNS Management in Linux

Hummingbird currently supports both resolv.conf and systemd-resolved service. It is also aware of NetworkManager, in case it is running. While the client is running, you are strongly advised not to issue any systemd-resolved related command (such as resolvectl) or change the resolv.conf file to make sure the system properly uses DNS pushed by the VPN server. Please note: DNS system settings are not changed in case the client has been started with --ignore-dns-push. In this specific case, the connection will use your system's DNS.

Furthermore, please note that if your network interfaces are managed by NetworkManager, DNS settings might be changed under peculiar circumstances during a VPN connection, even when DNS push had been previously accepted.

DNS Management in macOS

DNS setting and management is done through OpenVPN 3 native support (OpenVPN connections) or the AirVPN WireGuard Client (WireGuard connections).

Recover Your Network Settings

In case Hummingbird crashes or is killed by the user (e.g. kill -9 `pidof hummingbird` ) as well as in case of system reboot while the connection is active, the system may keep and use some or all of the network settings determined by the client, therefore your network connection might not work as expected, every connection might be refused and the system might seem to be "network locked". To restore and recover your system network, you can use the client with the --recover-network option.

sudo ./hummingbird --recover-network

Please note in case of crash or unexpected exit, when you subsequently run Hummingbird it will warn you about the unexpected exit and require you to run it again with the --recover-network option. It will also refuse to start any connection until the network has been properly restored and recovered.

Building Hummingbird from Sources

To build hummingbird from sources, you need the following dependencies:

Clone AirVPN-Suite repository into your computer:

git clone https://gitlab.com/AirVPN/AirVPN-Suite

Move into the project's directory:

cd AirVPN-Suite

Build Linux Dynamic Binary

Edit the build-hummingbird.sh script and set the INC_DIR, OPENVPN3 and ASIO variables according to your system configuration.

Run the build shell script:

sh build-hummingbird.sh

The script will compile the project and create hummingbird binary in the current directory.

Build Linux and macOS Static Binary

Edit the build-hummingbird-static.sh script and set the INC_DIR, OPENVPN3 and ASIO variables according to your system configuration. Also set STATIC_LIB_DIR and SSL_LIB_DIR according to your system architecture.

Run the build shell script:

sh build-hummingbird-static.sh

The script will create a hummingbird static binary file according to your system and will also create the associated distribution compressed tarball file in the current directory. To install the binary on your system, please refer to the installation instructions provided above.

Hummingbird is an open source project by AirVPN

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help, support, suggestions and testing.

OpenVPN is Copyright (C) 2012-2025 OpenVPN Inc. All rights reserved.

Hummingbird is released and licensed under the GNU General Public License Version 3 (GPLv3)

×
×
  • Create New...