Installation

Complete installation guide for Havoc Framework on Ubuntu, Debian, Kali Linux, and macOS

Havoc Framework works well on Debian 10/11, Ubuntu 20.04/22.04, Kali Linux, and macOS. It’s recommended to use the latest versions possible to avoid issues. You’ll need a modern version of Qt and Python 3.10.x to avoid build issues.

If you run into issues during installation, check the Known Issues section below and the GitHub Issues list.

Prerequisites

Before installing Havoc, you’ll need to install several dependencies. The requirements vary slightly by operating system.

Ubuntu 20.04 / 22.04

1. Install base dependencies

   Install the core packages required for building Havoc:

   sudo apt install -y git build-essential apt-utils cmake libfontconfig1 \
     libglu1-mesa-dev libgtest-dev libspdlog-dev libboost-all-dev \
     libncurses5-dev libgdbm-dev libssl-dev libreadline-dev libffi-dev \
     libsqlite3-dev libbz2-dev mesa-common-dev qtbase5-dev qtchooser \
     qt5-qmake qtbase5-dev-tools libqt5websockets5 libqt5websockets5-dev \
     qtdeclarative5-dev golang-go qtbase5-dev libqt5websockets5-dev \
     libspdlog-dev python3-dev libboost-all-dev mingw-w64 nasm
   
2. Enable Python 3.10

   Ubuntu 20.04/22.04 requires Python 3.10 for the Havoc client. Add the deadsnakes PPA:

   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install python3.10 python3.10-dev
   

   If you encounter fatal error: Python.h: No such file or directory during build, ensure you have both python3.10 and python3.10-dev packages installed.

Debian 10/11

1. Install base dependencies

   Install the core packages required for building Havoc:

   sudo apt install -y git build-essential apt-utils cmake libfontconfig1 \
     libglu1-mesa-dev libgtest-dev libspdlog-dev libboost-all-dev \
     libncurses5-dev libgdbm-dev libssl-dev libreadline-dev libffi-dev \
     libsqlite3-dev libbz2-dev mesa-common-dev qtbase5-dev qtchooser \
     qt5-qmake qtbase5-dev-tools libqt5websockets5 libqt5websockets5-dev \
     qtdeclarative5-dev golang-go qtbase5-dev libqt5websockets5-dev \
     libspdlog-dev python3-dev libboost-all-dev mingw-w64 nasm
   
2. Setup Python 3.10 from bookworm repository

   Debian 10/11 requires adding the bookworm repository for Python 3.10:

   echo 'deb http://ftp.de.debian.org/debian bookworm main' | sudo tee -a /etc/apt/sources.list
   sudo apt update
   sudo apt install python3-dev python3.10-dev libpython3.10 libpython3.10-dev python3.10
   

Kali Linux

Kali Linux includes most dependencies by default. Install the required packages:

sudo apt install -y git build-essential apt-utils cmake libfontconfig1 \
  libglu1-mesa-dev libgtest-dev libspdlog-dev libboost-all-dev \
  libncurses5-dev libgdbm-dev libssl-dev libreadline-dev libffi-dev \
  libsqlite3-dev libbz2-dev mesa-common-dev qtbase5-dev qtchooser \
  qt5-qmake qtbase5-dev-tools libqt5websockets5 libqt5websockets5-dev \
  qtdeclarative5-dev golang-go qtbase5-dev libqt5websockets5-dev \
  libspdlog-dev python3-dev libboost-all-dev mingw-w64 nasm

Kali has issues loading the proper Monaco font from the embedded Qt resources file. You may experience formatting issues in the Havoc client if not using a monospace/fixed-width font.

Arch-based Distributions

sudo pacman -S git gcc base-devel cmake fontconfig glu gtest spdlog \
  boost boost-libs ncurses gdbm openssl readline libffi sqlite bzip2 \
  mesa qt5-base qt5-websockets python3 nasm mingw-w64-gcc

macOS

1. Install Homebrew

   If you don’t have Homebrew installed, install it from brew.sh:

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

   Install the required packages using Homebrew:

   brew install --cask cmake
   brew install python@3.10 qt@5 spdlog golang
   brew link --overwrite qt@5
   

Building Havoc

Clone the Repository

First, clone the Havoc Framework repository:

git clone https://github.com/HavocFramework/Havoc.git
cd Havoc

Build the Teamserver

1. Install additional Go dependencies

   go mod download golang.org/x/sys
   go mod download github.com/ugorji/go
   
2. Build the teamserver binary

   From the Havoc root directory, run:

   make ts-build
   

   This command will:

   • Run the teamserver installation script
   • Compile the teamserver with Go
   • Set capabilities to allow running as a regular user (Linux only)

   The teamserver is compiled with the Git commit hash embedded for version tracking.

Build the Client

1. Build the client binary

   From the Havoc root directory, run:

   make client-build
   

   This will:

   • Initialize and update Git submodules
   • Create the build directory
   • Clone the official Havoc Modules repository
   • Build the client using CMake with 4 parallel jobs
2. macOS-specific post-build step

   On macOS, after the CMake build completes, run:

   brew unlink qt && brew link qt
   

Build Both Components

You can build both the teamserver and client in one command:

make all

Verifying the Installation

After building, verify your installation:

Teamserver

# Check if the teamserver binary exists
ls -lh havoc

# Run the teamserver with help flag
./havoc server --help

Data Storage

All files created during interaction with the Teamserver are stored within the /Havoc/data/* folder, including:

• Agent loot and downloads
• SQLite database (havoc.db)
• Teamserver certificates
• Cross-compilation toolchains

WSL Support

To run the Havoc client on Windows Subsystem for Linux (WSL), you need to install the appropriate GUI driver:

1. Navigate to the Microsoft WSL GUI Apps documentation
2. Download and install the required driver for your system
3. Follow the standard Linux installation steps above

Known Issues

fatal error: Python.h: No such file or directory

This error occurs when Python development files are not installed. Ensure you have Python 3.10 and its development package:

sudo apt install build-essential
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-dev

incomplete type 'QTime' used in nested name specifier

You probably need a newer version of Qt. If you are using Ubuntu, try adding a backports PPA and installing the latest Qt6 development packages.

See GitHub Issue #95 for more details.

Known compiler issue: Couldn't compile implant: exit status 1

This is typically related to the MinGW compiler setup. Check that all cross-compilation dependencies are properly installed.

See GitHub Issue #105 for troubleshooting steps.

Kali Linux font/formatting issues

Kali has issues loading the proper Monaco font from the embedded Qt resources file. The Havoc client requires a monospace/fixed-width font for proper formatting.

You can manually configure a monospace font in your system settings to work around this issue.

Cleanup

If you need to clean your build and start fresh:

Clean Everything

make clean

Next Steps

Now that you have Havoc installed, proceed to the Quick Start Guide to learn how to:

• Start the teamserver
• Connect the client
• Create listeners
• Generate and deploy agents