Build Katzenpost from source

This page is the canonical reference for the pinned versions of the Katzenpost stack, together with brief instructions for building and running each component from source. It is intended for anyone who wishes to run the software ahead of binary packages becoming available.

Pinned versions

The following git tags are the current recommended versions for running the stack. Components in the same row of the same repository should be built from the same tag.

Server-side components are listed for completeness; for full deployment guidance, see the Admin Guide.

Prerequisites

• Go 1.23 or newer.
• Rust stable (with cargo).
• Python 3.9 or newer (the thin client supports 3.8+, but the venv tooling here assumes 3.9+).
• Make, git, and a C toolchain (gcc or clang).

kpclientd (the client daemon)

The thin client libraries do not, by themselves, speak to the mix network. They communicate over a local socket with the kpclientd daemon, which performs all cryptographic and network operations.

git clone https://github.com/katzenpost/katzenpost
cd katzenpost
git checkout v0.0.73-rc3
cd cmd/kpclientd
go build

The resulting kpclientd binary is run with a TOML configuration file:

./kpclientd -c /path/to/client.toml

A configuration file is required. For testing, the Docker test mixnet generates one automatically; for joining a public network, you would obtain the configuration from that network’s operators.

Go thin client

The Go thin client is a library, imported as a Go module:

import "github.com/katzenpost/katzenpost/client/thin"

Pin to v0.0.73-rc3 in your application’s go.mod. There is no separate build step; the library is compiled with your application.

Rust thin client

git clone https://github.com/katzenpost/thin_client
cd thin_client
git checkout 0.0.12-rc3
cargo build --release

Or, in another Rust project’s Cargo.toml:

[dependencies]
katzenpost_thin_client = "0.0.12-rc3"

Python thin client

The Python thin client is best installed into a virtualenv, both to isolate its dependencies and to avoid any disturbance of the system Python.

git clone https://github.com/katzenpost/thin_client
cd thin_client
git checkout 0.0.12-rc3
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .

The example programs under thin_client/examples/ (echo_ping.py, fetch_pki_doc.py, mixnet_status.py, and others) demonstrate the API and are useful smoke tests once kpclientd is running.

katzenqt (Qt group chat client)

A decentralised group chat client built atop Qt. It depends solely on the Katzenpost mix network and the Pigeonhole storage services. No central server is involved. The underlying design is set out in the Echomix paper.

A tag has not yet been published; at present, katzenqt builds against a development branch of katzenpost. This section will be updated once a release is cut.

sudo apt install libxcb-cursor0 libegl1
git clone https://github.com/katzenpost/katzenqt
cd katzenqt
make deps
make run

If make deps run does not produce a running interface, the component-by-component sequence in katzenqt’s README.md is the recommended fallback.

Verifying the stack

Once kpclientd is running with a valid configuration, the Python example echo_ping.py is the simplest end-to-end smoke test. It sends a packet through the mix network and waits for the SURB reply.

source thin_client/.venv/bin/activate
python3 thin_client/examples/echo_ping.py

A successful run indicates that kpclientd is connected, the PKI document has been retrieved, and the network is producing consensus.