PokerTH: an open source Texas Hold'em engine you can host yourself

Twenty years of poker, and a licence that says no ads and no tracking

PokerTH is a poker game written in C++ with Qt. The readme puts it as the open source Texas Hold'em engine, play against the computer or against other people over the internet.

Two things in the About section set the tone. The project has been around since 2006, which for a game means it has survived several generations of toolkits. And it is licensed under the AGPLv3, and carries no ads, no real-money gambling and no tracking.

That last sentence is a real design constraint rather than a boast, and it explains several choices further down. There is a chat translation feature that is opt-in and documented separately, so a third party service is involved only if you turn it on. The official server is a separate binary from the dedicated one, so the player database, accounts and rankings live in a component you do not have to run.

The audience is a community that wants to host its own games. The About section says you can play against up to nine computer opponents or against real people on the internet, either on the official server at pokerth.net or on any dedicated server you run yourself.

The scope is wider than the poker. The features list covers tournament-style games with start money and blind levels raised by hand count or by minutes, several game access modes, a lobby with chat and private messages that persist per account, 29 languages with the full UI translated, and 20 table themes with 11 card decks and several card backsides, importable and exportable as ZIP files.

Two clients, two servers, one protocol file

The repository builds more than one binary, and the readme is precise about which is which, which matters because one of them is on its way out.

The current client is pokerth_qml-client, using Qt Quick and QML from the src/gui/qt6-qml directory, described as the current client, all platforms, scaling from phone to desktop. The classic client is pokerth_client, using Qt Widgets from src/gui/qt, and it is described as discontinued, with 2.1.9 as its final version, bugfix builds only, currently 2.1.9.2.

So a new deployment on the classic client would be building on something the project itself has ended. That is stated plainly rather than buried, and it is the single most important fact for anyone evaluating the project today.

On the server side there are two binaries. pokerth_dedicated_server is for everybody who wants to host games. pokerth_official_server adds the user database used by pokerth.net.

The architectural centre is a single file. pokerth.proto is the network protocol, described as the single source of truth for client and server. The repository layout table makes the layering explicit: src/engine holds the poker engine with hands, betting rounds and bot logic in both a local and a network variant, src/net holds client and server networking using Boost.Asio, TLS and WebSocket for the browser client, src/db and src/dbofficial hold the server database interface and the asynchronous MySQL backend, and src/core and src/config hold logging, crypto, avatar handling and configuration files.

The protocol file being the source of truth is the right way to structure this, and it is also what makes the browser client and the two desktop clients able to speak to the same server.

Building on Linux, and the dependency list it implies

The build requirements are spelled out, and they are a modern toolchain rather than a legacy one.

You need Qt at version 6.7.0 or later, with 6.9.2 LTS recommended. Boost at 1.83 or later, specifically the thread, filesystem, date_time, program_options, iostreams, asio, regex, random and uuid components. Protocol Buffers 2.3.0 or later, with protoc at build time and libprotobuf at runtime. OpenSSL. And CMake 3.15 or later with a C++23 compiler, with Ninja recommended.

The Linux build is three commands:

cmake -DCMAKE_BUILD_TYPE=Release -S . -B ./build -G Ninja
cmake --build ./build --config Release --target all
sudo cmake --install ./build

You can build individual targets instead of all, and the readme names them: pokerth_qml-client, pokerth_client, pokerth_dedicated_server, pokerth_official_server and pokerth_chatcleaner. That last one is the chat filter service used by the official server, and it is also visible as a src/chatcleaner directory in the layout table, alongside a separate chatcleaner.proto in the tree.

There is a clean build path as well. For a clean build including the test certificate and the data directory inside build/, you run bash clean_build.sh first, and the INSTALL file has the details.

The dependency list explains a lot about the shape of the code. Qt and QML for the modern client, Boost for the platform abstraction the engine sits on, Protobuf for the wire format, and OpenSSL for the TLS that a public server needs. The C++23 requirement is worth noting, because it means the build needs a current compiler rather than the older toolchains still common on long lived distributions.

The dedicated server, and the three helper tools around it

Running a server is two commands once it is built:

cmake --build ./build --target pokerth_dedicated_server
./build/bin/pokerth_dedicated_server

The server reads its settings from the PokerTH config file and writes its log next to it, and the readme is direct that the complete walkthrough, covering ports, firewall, TLS certificate and server list entry, is in docs/server_setup_howto.txt. So the operational details are documented in the repository rather than implied.

Three helper tools sit around the server, and each solves a different operational problem.

pokerth_bot is a headless client for load and protocol tests. That is the tool you reach for when you want to know whether the server holds up, or whether the protocol still behaves after a change.

pokerth_globalnotice sends a notice to everyone on a server. On a server with a user database, that is how you announce a restart, a rule change or an outage without relying on chat messages that players might not read.

tools/analyze_server_log.py renders a server log as SVG, and the tools directory in the layout table is described as server log analysis, screenshot and theme preview automation. There is a create_serverlist.sh script and a serverlist_example.xml at the root, which is the server list entry the setup guide refers to.

The combination of a headless bot, a global notice channel and a log analyser is a good indicator of how the project treats running a server as an ongoing operation rather than a one-off install, and the tests directory reinforces that with a protocol test suite in Java driving a running server.

Packages for five platforms, and the iOS caveat

The download table is the most practically useful part of the readme, because it tells you which platforms have a ready-made artefact and which do not.

For Linux there are five options: a Flatpak named net.pokerth.PokerTH, a Snap named pokerth, an AppImage, a .deb, and a portable ZIP. For Windows there is an installer, and it contains both clients. For macOS there is a DMG, also containing both clients. For Android there is an APK from the PokerTH F-Droid repo at the site address, and the fdroid directory in the tree is the repository configuration. For iOS the readme points at build_ios_qml.sh and says explicitly that there is no App Store build yet.

That last point matters more than it looks. iOS is on the list of supported platforms in the features section, but the packaging route is a build script rather than a distributed app, so anyone shipping an iOS build is building it themselves.

The features list also claims cross-platform support across Linux, Windows, macOS, Android and iOS, and the download table qualifies that with the practical detail. The current QML client is the one that scales from phone to desktop, which is consistent with Android being served as an APK built from the QML target rather than the Widgets one.

For the other platforms the release builds are reproducible rather than assembled by hand. The readme states that the release builds are reproducible through Docker images and GitHub Actions workflows rather than by hand, and maps each platform to a directory: docker/windows for a MinGW cross build, docker/android plus build_android_qml.sh, build_macos_combined.sh and build_ios_qml.sh for macOS and iOS, and docker/linux for AppImage, deb, ZIP, Snap and Flatpak. Every one of these also exists as a manually triggered workflow in .github/workflows.

There is also a language and tooling layer worth noting: a ts directory in the tree, a pokerth.lua file, and Lua appears as a configuration or scripting surface alongside the C++ engine.

Where PokerTH is the wrong choice

There are cases where this project is the wrong answer, and the readme itself flags the main one.

The first is the classic client. It is discontinued, with 2.1.9 as its final version and bugfix builds only. If you are starting a new desktop deployment, you are on the QML client, and if you are evaluating the project as a codebase to contribute to, the Widgets client is a maintenance liability rather than a foundation.

The second is a modern commercial poker client expectation. This is a Qt Quick application with 29 languages, 20 themes and a lobby with chat and emoji reactions, which is a substantial feature list, but it is a Qt application. A team that wants a web or mobile client, or a polished cross platform experience, is looking at a different kind of project. The browser client hinted at in the src/net entry, with WebSocket support, points at where the project is heading, but it is not the product you would download today.

The third is the AGPL. If you plan to modify PokerTH and run a public service, the copyleft obligations of the AGPL apply to the modified work, and that is a conversation with your own legal advice rather than a technical one. The licence is a genuine feature for a community-hosted game, and it is a genuine constraint for a commercial deployment.

The fourth is a self-hosted game server that needs operational maturity. The readme gives you the setup guide, the helper tools and the protocol test suite, which is a good foundation, but a public server is a service with availability expectations, and the tooling here is aimed at the person who runs it, not at a team with an on call rotation.

And the fifth is tournament play at scale. The tournament features are real, with blind levels raised by hand count or by minutes, manual blind orders, action timeouts and configurable GUI speed, but the load testing tool is a headless bot rather than a benchmark suite, so capacity planning is on you.

Against a hosted poker site, and against a minimal open source engine

Two comparisons make the choice concrete.

The first is against a hosted card room. The difference in approach is where the trust sits. A hosted site owns the shuffler, the account database and the money, and a self-hosted PokerTH server owns all three on your machine, which is why the licence, the no-tracking stance and the AGPL are stated up front rather than buried. For a community that does not want its players' data on someone else's server, or a group that wants to be certain the game is not monetised, that is the entire argument.

The second is against a much smaller open source engine. A minimal project might be a few thousand lines with a headless client and a text interface, which is easier to audit, easier to embed in a larger system, and trivial to run on a small machine. PokerTH is a full application: two clients, two server binaries, a chat filter service, a user database, twenty themes, eleven card decks and twenty-nine languages.

The trade is scope against auditability. If you want to host games for a community with players, chat, accounts and a lobby, PokerTH has already solved the parts you would otherwise spend months on, and the protocol file being the single source of truth means a client and a server cannot drift apart silently. If you want a component to embed in your own service, that whole application is more than you need, and a smaller library would be a better fit.

The intermediate case, where you want the engine and the protocol but not the official server, is where the dedicated server binary earns its place: it gives you the real implementation without the user database and ranking system.

Editorial conclusion

Adopt PokerTH if you want to run a Texas Hold'em game server your community controls, on your own hardware, with an AGPL licence and no advertising or telemetry, since a dedicated server binary and a documented setup guide are in the box. Skip it if you want a modern poker client with a large player base, because the readme records the classic Qt Widgets client as discontinued and the QML client as the current one. Verify first that the QML client covers the platforms you need, that the protocol file version matches between your client and server, and that you are comfortable with the AGPL obligations before you host it publicly.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. pokerth/pokerth on GitHub
3. Project website
4. README
5. Releases