Cockatrice: a Qt virtual tabletop where the server holds the game state

The client is only half of Cockatrice, and the server is the point

Cockatrice is an open-source, multiplatform application for playing tabletop card games over a network. What makes it interesting is stated plainly in the project description: the server design prevents users from manipulating the game for unfair advantage.

That is a design decision with consequences. In many online card game clients, the state of the game lives in the client, and the server relays messages between players. A determined client can then edit what it believes the board looks like, and the other player sees something the rules do not allow. Cockatrice inverts this. The authoritative game state sits on the server, the clients render what the server tells them, and the actions a player takes are requests the server validates before applying them. The dice rolls and card draws happen where nobody can reach them.

The client also provides a single-player mode, which lets users brew while offline, that is, build and tune decks without a connection. The README frames this as an addition to the networked mode rather than a parallel product, and it is worth keeping that proportion in mind, because the offline mode does not carry the server's rules enforcement.

The project is written in C++ and uses the Qt libraries, with the primary language of the repository listed as C++. The client, the server and the tooling are all in this one repository, split into a directory per library.

For the audience, the shape is fairly specific: a community organiser who wants a virtual tabletop for a trading card game, or a player who wants to play one with a group spread across the internet. It is not a general-purpose board game platform, and the card data it uses is not bundled with it.

servatrice, the server, and the port it listens on

The server component is called servatrice, and the repository holds it in the servatrice/ directory. The client code is spread across the libcockatrice_* directories, which are separate libraries: libcockatrice_card, libcockatrice_deck_list, libcockatrice_filters, libcockatrice_interfaces, libcockatrice_models, libcockatrice_network, libcockatrice_protocol, libcockatrice_rng, libcockatrice_settings and libcockatrice_utility. There is also an oracle/ directory, and the top level holds CMakeLists.txt, cmake/, a Dockerfile, a docker-compose.yml and a separate docker-compose.yml.windows.

The docker-compose file in the repository is the clearest statement of what a server deployment looks like. It defines two services, a MySQL database and servatrice, with the database image set to mysql, the sql_mode flag cleared in the command, and a servatrice database and user created from environment variables. The server image is published at ghcr.io/cockatrice/servatrice:latest, it depends on the database, and it maps the port:

    ports:
      - "4748:4748"
    entrypoint: "/bin/bash -c 'sleep 10; servatrice --config /tmp/servatrice.ini --log-to-console'"
    restart: always
    volumes:
      - $PWD/servatrice/docker/servatrice-docker.ini:/tmp/servatrice.ini

Port 4748 is the port a Cockatrice server listens on, and it is the number to remember when configuring a client or a firewall. The entrypoint sleeps for ten seconds before starting, which is the crude but effective way to wait for MySQL to accept the schema that the compose file seeds by mounting servatrice/servatrice.sql into the database's init directory.

The configuration itself is a servatrice.ini file, and the compose file expects one at servatrice/docker/servatrice-docker.ini. The Dockerfile builds the server from an ubuntu:26.04 base with cmake and Ninja, passing three options to the configure step:

RUN cmake \
      -S . \
      -B build \
      -G Ninja \
      -DWITH_CLIENT=0 \
      -DWITH_ORACLE=0 \
      -DWITH_SERVER=1 \
    && cmake --build build \
    && cmake --install build

Those three switches are the build options worth knowing. WITH_SERVER=1 builds the server, WITH_CLIENT=0 leaves out the desktop client, and WITH_ORACLE=0 leaves out the oracle tool, so a container build is server-only. The runtime stage is a clean ubuntu:26.04 with the runtime libraries copied in rather than the source tree, and it exposes 4748 as well.

The card database is not in this repository

The single most common surprise for someone evaluating Cockatrice is that the card data is not part of the application. The README lists the related repositories, and the first two are the ones that matter.

Magic-Token holds the MtG token data used by Cockatrice. Magic-Spoiler holds the code that generates MtG spoiler data from MTGJSON, for use in Cockatrice. So there are two distinct kinds of data in play. Token data is the picture and text attached to a token such as a creature or a planeswalker, and spoiler data is the rules text and statistics of a card. The spoiler data is generated from MTGJSON, which is a separate community dataset, and the generation code is versioned apart from the application.

The consequence for a server operator is that a fresh servatrice has no cards in it. Something has to load the card list, and if you are running a different game system than Magic, the data is a problem you solve yourself, using the same oracle and database conventions. That is the practical work that separates installing Cockatrice from having a usable tabletop.

Two more related projects round out the ecosystem. Webatrice is a web client for Cockatrice servers, written in TypeScript and React, which is what lets people join a game from a browser. The io.github.Cockatrice.cockatrice repository holds the configuration for the Linux flatpak hosted on Flathub, which is the easiest install path on Linux and sidesteps the dependency question for the desktop client entirely.

The oracle/ directory in the main repository is the tool that connects the two halves, generating card data for the client to read. The repository also carries a .tx/ directory, which is the Transifex configuration for translation, and the topics list includes transifex, so localisation is handled through that service across the project.

Getting the client: releases, beta builds, and the flatpak

Downloads are published as GitHub releases, with a stable channel and a beta channel, and the README is clear that there is no strict release schedule for either. The recent release list shows how that works in practice: 3.1.0 titled Reality Check on 2026-10-03, 3.1.1 with the same title on 2026-10-10, and 2026-10-12-Development-3.1.2-beta two days later. So a stable release every week or so at the moment, plus a beta build that follows it.

The README warns about the beta channel in plain terms: while incorporating the latest fixes and features, beta builds may not be stable or contain new bugs, and users are asked to report findings and open issues when testing them. That is an unusually direct invitation to test, and it is the normal way a server operator finds out whether a change breaks their card data before their players do.

For Linux users, the flathub configuration repository is the straightforward route, since Flathub packages the client with its own dependency set. For other platforms, the release artefacts on the releases page are the route, and the build and run documentation lives in the repository's own doc/ directory and the wiki.

The README asks people who want to help with development to read the contributing guidelines in .github/CONTRIBUTING.md, and it maintains two issue tags for that purpose: good first issue for work that does not require much experience, and help wanted for issues the project supports but has no time for. The second tag is a fair description of a volunteer project with a steady release cadence, and it is also the best way to find out what the maintainers want help with.

Where Cockatrice is weak, and where it is the wrong tool

There are three real limits, and none of them are hidden in the documentation.

The first is the card data dependency. The application is generic in the sense that it is not tied to one game, but the data is the game. A server for a game system without an existing data set in the ecosystem means building a card list in the format the oracle produces, testing the interaction between the card definitions and the client's rendering, and maintaining it as the set changes. The cost of that work is not in the C++ and not in the Qt.

The second is the server as a responsibility. State enforcement is the feature, and state enforcement means a process to run, a database to back it, a configuration to keep, and a set of moderation obligations. The README has an IMPORTANT note aimed exactly at this: for support regarding specific servers, contact that server's admins and use their dedicated communication channels rather than the software team. In other words, the project expects a layer of per-server administration and declines to staff it. A community organiser adopting Cockatrice is signing up to be a server operator, not just a user of a desktop program.

The third is the client stack. A C++ and Qt desktop application, distributed as a flatpak on Linux and as release binaries elsewhere, is a heavy install for a game that could be played in a browser, and Webatrice exists precisely because a browser client is a different proposition. The trade-off is real: the native client has the card rendering and the deck editor that a web client has to approximate.

There is also a licensing boundary worth naming. The project is GPL-2.0, and the card data repositories sit in the same organisation. If you are considering using Cockatrice in a commercial product, or building a service on top of it, that licence is the first question to ask rather than the last.

How Cockatrice compares to the alternatives

The alternatives to a virtual tabletop fall into three groups, and Cockatrice's own design choices make sense only once you see them against those.

The first group is general-purpose game simulators: platforms where you upload a rules module and a deck and play a game with a defined rule set. These tend to be built around a rule engine, and their value is that they carry a rules implementation you did not write. Cockatrice takes the opposite position. It does not model card rules in a general engine, it holds the game state and adjudicates actions on the server, and the card behaviour comes from the data and the client logic rather than from a portable rules module. The gain is fidelity to a particular game's real interaction, including the messy parts; the loss is that a new game means new work rather than new data.

The second group is the general-purpose virtual tabletop with a shared board: a tool where players move tokens and cards on a board, with rules left entirely to the players and a dice roller in the corner. Cockatrice is a different category here too, because it is specifically a card game client, with a deck editor, a card database, and game-specific actions rather than free-form object placement.

The third group is simply a physical or video-conference table. The difference in approach is that Cockatrice inserts an authoritative referee into the session. That is what stops a rules dispute from becoming a trust dispute, and it is the reason the server exists at all rather than being a relay.

The deciding factor is what you need the software to guarantee. If the value is in a shared table where people can point at things, a general board tool or a video call does it with less to run. If the value is in a game where cheating by editing game state is the obvious failure mode, the server-side design is the whole reason to pick Cockatrice over a lighter alternative.

Editorial conclusion

Adopt Cockatrice if you run a card game community and want a virtual tabletop whose game state is enforced by a server you control, and you are prepared to host servatrice, feed it card databases and moderate the players on it. Do not adopt it if you want a single-player deck builder with no server to maintain, since the offline mode is a side feature rather than the centre of the product. Verify first that the card data you need exists in the Magic-Token and Magic-Spoiler repositories for your set, that your servatrice instance runs on port 4748 with a MySQL backend, and that the client and server versions match, since the release line is currently 3.1.x with a 3.1.2 beta published on 2026-10-12.

Frequently asked questions

Official sources

1. Cockatrice/Cockatrice on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases