Echomix Documentation on EchoMix

Mon, 18 May 2026 09:33:21 -0700

KatzenQT chat client guide [Pre-release]

This guide introduces the KatzenQT chat client. With KatzenQT you can securely share one-to-one and group messages with other KatzenQT users. KatzenQT relies on Katzenpost, an advanced mixnet system designed for people who have something to say, but who also value their anonymity. Anonymity is not the same thing as encryption, which protects the content of communication over the Internet. Anonymity is about protecting people.

Build Katzenpost from source

Mon, 11 May 2026 21:31:32 -0700

Build Katzenpost from source

Table of Contents

Pinned versions

Prerequisites

kpclientd (the client daemon)

Go thin client

Rust thin client

Python thin client

katzenqt (Qt group chat client)

Verifying the stack

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.

Mon, 01 Jan 0001 00:00:00 +0000

Build and run katzenqt from source

katzenqt is the Qt group chat client. It is a decentralised application that runs over the Katzenpost mix network and the Pigeonhole storage services. The design is set out in the Echomix paper.

Warning. katzenqt is in active development and has not yet been tagged for general release. It is not appropriate to rely on the software for anonymity, security, or privacy at this stage. Pre-built packages will be linked from the docs landing once a release is cut.

Mon, 01 Jan 0001 00:00:00 +0000

Python Thin Client API

This is the API reference for the katzenpost_thinclient Python package, the Python binding of the Katzenpost thin client. The thin client is an interface to the kpclientd daemon, which performs all cryptographic and network operations; the binding itself does no cryptography.

This page is generated by website/tools/python-api-gen/ from the docstrings of the pinned katzenpost_thinclient release, using the native Python documentation tool pydoc-markdown. Do not edit it directly: changes belong in the binding docstrings (in the thin_client repository) and will be overwritten by the next generation pass.

Mon, 01 Jan 0001 00:00:00 +0000

Run a Katzenpost Mix server in a Docker container

Prerequisites

Access to the namenlos git repo

Preparing the host filesystem

mkdir katzenpost-mix
cd katzenpost-mix
mkdir {conf,data}
chmod 700 data

All further actions are performed from the katzenpost-mix directory.

Building the Docker image

Create Dockerfile:

FROM golang:bookworm AS builder

LABEL authors="<ops@cryptonymity.net>"

RUN \
 cd /go && \
 git clone https://github.com/katzenpost/katzenpost && \
 cd katzenpost && \
 go mod tidy && \
 cd cmd/server && go build

FROM debian:bookworm AS deploy

COPY --from=builder /go/katzenpost/cmd/server/server /usr/bin/server

EXPOSE 8181

ARG uid=1000
ARG gid=1000

RUN \
 mkdir -p /home/user && \
 echo "user:x:${uid}:${gid}:User,,,:/home/user:/bin/bash" >> /etc/passwd && \
 echo "user:x:${uid}:" >> /etc/group

USER user
ENV HOME=/home/user

ENTRYPOINT ["/usr/bin/server","-f","/conf/katzenpost.toml"]

Build Docker image:

Mon, 01 Jan 0001 00:00:00 +0000

Thin Client API Reference

This is the complete API reference for the Katzenpost thin client. The thin client is an interface to the kpclientd daemon, which handles all cryptographic and network operations. The thin client communicates with the daemon over a local socket using CBOR-encoded messages.

This document is generated. The canonical source is website/tools/thin-client-api-gen/; edit binding docstrings (in the source trees) or groups.yaml / overlay/*.md (in the generator) — do not edit this file directly, as local changes will be overwritten by the next generation pass.

Mon, 01 Jan 0001 00:00:00 +0000

Thin Client How-to Guide

This guide shows how to accomplish specific tasks with the Katzenpost thin client. Each section is self-contained: find the task you need and follow the steps.

If you are new to Pigeonhole, read Understanding Pigeonhole first for the concepts, then return here for the recipes, and consult the Thin Client API Reference for the precise signatures.

Throughout this guide and the API the words channel and stream are used interchangeably: they denote one and the same thing.

Mon, 01 Jan 0001 00:00:00 +0000

Threat Model

The purpose and structure of this document

This threat model document is unique in the privacy technology landscape for its detailed treatment of realistic adversary capabilities. It is not a description of a superficial, theoretical system, but rather of complex, real-life software that is being interrogated and constantly re-designed to provide the best possible security. We examine it from the point of view of both theoretical design, networking choices and practical pitfalls.

Mon, 01 Jan 0001 00:00:00 +0000

Understanding Pigeonhole

Pigeonhole is the storage layer of the Katzenpost mix network. It lets applications communicate anonymously using encrypted, append-only streams. From a passive network observer’s perspective there is no consistent stream access and instead everything looks like randomly scattered queries across storage servers.

 client ┌───── via mix network ─────┐ courier replicas
 ┌────┐
 kpclientd ──▶ Sphinx round-trip (×3 mix layers) ──▶ service │ 1 │
 node ├────┤
 (courier) │ 2 │
 │ ├────┤
 └─────▶│ ...│
 └────┘
 fixed-throughput K = 2
 connections; replicas
 cannot read box IDs per box
 (consistent
 hashing)

This is the document to read first. Having understood the concepts here, proceed to the how-to guide for task-oriented recipes, and consult the API reference for the precise signatures.