Installation

veriCue has two pieces you install separately:

1. The veriCue Runtime - a shared library (libvericue-server.so / vericue-server.dll / libvericue-server.dylib) plus headers, which runs inside your Qt application. You get it there either by linking it and calling VeriCueServer::startLocal() / start(port) in main(), or - on Linux x64 and Windows x64 (Windows from 0.5.0), against a dynamically linked Qt binary - by starting the application with vericue run, which needs no build change at all. Both are supported. macOS has no launch-time path: embed the Runtime there.
2. A client library - Python, C++, or C# package that connects to the Runtime and sends commands.

The Runtime listens on one of two transports: a user-private local IPC endpoint (a UNIX-domain socket - Linux and macOS, and the recommended path when the client runs on the same machine), or a TCP port (every platform, and the supported path on Windows; use it whenever something has to cross a host, container or device boundary).

Prerequisites

• Qt 5.15 or Qt 6.x (both are supported by the same headers; pick the tarball that matches your build environment).
• OpenSSL - only when you build against the Runtime: the development headers are needed to compile and link. You do not need to install OpenSSL to run veriCue from a package. The Linux Runtime uses your distribution's libcrypto, which is present on every supported distribution, and the Windows package ships the libcrypto DLL it links against, so a clean Windows machine needs nothing extra.
• CMake 3.16+ for embedding the Runtime.
• C++17 compiler.

1. Get the Runtime library

Download the matching pre-built archive from the veriCue distribution CDN. The archives are public - you do not need a licence key or an account to download them. They are hosted under https://dl.vericue.dev/<version>/:

Platform	Qt 5.15	Qt 6.7
Linux x64	vericue-<version>-qt5.15-linux-x64.tar.gz	vericue-<version>-qt6.7-linux-x64.tar.gz
Windows x64	.zip archive	.zip archive
macOS arm64 (Apple Silicon)	-	.tar.gz

macOS ships for Apple Silicon (arm64) on Qt 6.7. There is no macOS Intel (x64) build, and Qt 5.15 has no official arm64 macOS build.

Verify the SHA256 before extracting:

sha256sum -c vericue-<version>-qt5.15-linux-x64.tar.gz.sha256

Install into /usr/local:

tar xzf vericue-<version>-qt5.15-linux-x64.tar.gz -C /usr/local --strip-components=1

The Linux and macOS archives contain:

lib/libvericue-server.*   # the veriCue Runtime - runs inside your app under test
lib/libvericue-widgets.*  # QtWidgets support, loaded on demand
lib/libvericue-quick.*    # Qt Quick support, loaded on demand
lib/libvericue-client.*   # client library - drive it from C++ tests
lib/libvericue-inject.*   # (Linux x64) the LD_PRELOAD probe
lib/cmake/vericue/        # CMake config for find_package()
include/vericue/          # public headers
bin/vericue-inject        # (Linux x64) run an unmodified Qt app under veriCue

The Windows zip follows the platform convention instead: the DLLs live in bin/, the import libraries in lib/.

bin/vericue-server.dll    # the veriCue Runtime
bin/vericue-widgets.dll   # QtWidgets support, loaded on demand
bin/vericue-quick.dll     # Qt Quick support, loaded on demand
bin/vericue-client.dll    # client library
lib/vericue-*.lib         # import libraries
lib/cmake/vericue/        # CMake config for find_package()
include/vericue/          # public headers

The two toolkit plugins must stay in the same directory as the Runtime library - lib/ on Linux and macOS, bin/ on Windows - because the Runtime looks for them by base name (vericue-widgets, vericue-quick) next to itself, and the platform prefix and suffix are added for you. You do not link them and there is nothing to configure; deploying the directory intact is enough. Note the naming difference the platforms enforce: libvericue-widgets.so / .dylib on Unix-like systems, vericue-widgets.dll (no lib prefix) on Windows.

Leaving one out only costs you support for that toolkit - the Runtime still starts, and the version command names each toolkit it could not resolve:

{"server": "vericue", "version": "<the package version>", "protocol": 1, "qt": "6.7.2",
 "toolkits": ["widgets: loaded (detected via module Qt6Widgets.dll)",
              "quick: Qt module not present in this process (probed modules Qt6Quick.dll, Qt6Quickd.dll)"]}

A quick: Qt module not present in this process line is the expected answer for an application that does not use Qt Quick - the backends are only loaded when the matching Qt module is already in the process. It is only a deployment problem when the toolkit your application actually uses reports plugin not loadable.

The Linux x64 package also includes bin/vericue-inject, which runs an existing, dynamically linked Qt binary under veriCue with zero integration. It is part of the same deliverable: it loads lib/libvericue-inject.so relative to itself, which in turn uses the Runtime library and plugins beside it, so keep bin/ and lib/ together. See Zero-source-change runs for the supported configurations.

vericue run is the command most people should use for this: it comes with the Python client and starts an application through the package above.

Put the package's bin/ on $PATH, or point VERICUE_HOME at the package root, and it finds the rest itself:

export VERICUE_HOME=/usr/local
vericue run ./your-qt-app

2. Wire it into your Qt application

Add to your CMakeLists.txt:

find_package(vericue REQUIRED)
target_link_libraries(my_app PRIVATE vericue::vericue-server)

In your main.cpp. On Linux and macOS, start the local IPC endpoint - it is user-private, has no network presence, and is the recommended path when your tests run on the same machine:

#include <vericue/server.h>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    vericue::VeriCueServer server;
    server.setLicenseFile("/path/to/licence.json");
    server.startLocal();                                 // local IPC endpoint
    qInfo().noquote() << "VERICUE_ENDPOINT=" << server.localEndpoint();

    MainWindow w;
    w.show();
    return app.exec();
}

On Windows, and whenever the client runs on another host, in another container or on a device, start the TCP transport instead. Local IPC is not supported on Windows - see Limitations:

    server.start(4242);          // TCP; 0 lets the OS pick, read serverPort() back

Both calls speak the identical protocol and enforce the identical authentication and licensing rules; see Transports: local IPC vs TCP for the full comparison. You may call both on one server if you need to serve local and remote clients at the same time - they share the one licensed concurrent-session budget.

Don't have a licence yet? You don't need one to start.

Leave setLicenseFile() out and the server starts in trial mode by itself: 30 days from the first run on that machine, full protocol with no command restrictions, max 1 concurrent automation session. There is no key to request and nobody to e-mail first - see Start your 30-day trial.

After the trial the server stays running but rejects every command except handshake, ping and version until a paid licence is loaded. Trial scope and the paid plans are described in Trial & paid tiers.

Security

The veriCue Runtime exposes a control channel that can fully drive your application's UI. Treat it as a privileged interface:

• Prefer local IPC where it is supported. startLocal() creates a UNIX-domain socket with owner-only permissions and no network presence at all, so there is no port to firewall and nothing for another host to reach.

• Always set an auth token in shared or CI environments so only your tests can connect:

  server.setAuthToken("a-strong-shared-secret");

  Pass the same token from the client: connect(host, port, token="...") or connect_local(endpoint, token="...").

• Keep a TCP port on a trusted network. start(port) listens on every interface and the protocol is plaintext, so firewall it or tunnel it, and never expose the veriCue port to the public internet.

• Ship it only in test/CI builds of your application - never enable the veriCue Runtime in production releases. The embedding guide shows the compile-out pattern.

3. Install a client

Python

pip install vericue

C# / .NET

dotnet add package VeriCue

C++

The C++ client is included in the same archive as the Runtime library, in lib/libvericue-client.so (bin/vericue-client.dll on Windows) + include/vericue/client.h.

find_package(vericue REQUIRED)
target_link_libraries(my_tests PRIVATE vericue::vericue-client)

Verify the setup

Start your Qt application, then in a separate terminal point the CLI at whichever transport you started. --endpoint selects local IPC, --port selects TCP:

# local IPC - the path your app printed as VERICUE_ENDPOINT=<path>
python -m vericue --endpoint /run/user/1000/vericue/vericue-4213.sock ping

# TCP
python -m vericue --port 4242 ping

Should print {"pong": true} - you're connected. Continue with the Python quick start.

Troubleshooting

"License file not found" on server start

Use an absolute path, not relative. The Qt working directory may differ from where you launched the binary.

"Authentication required" on every command

You called setAuthToken() on the server. Pass the same token to the client: connect(host, port, token="...") over TCP, connect_local(endpoint, token="...") over local IPC.

startLocal() returns false

Read the reason from the errorOccurred(QString) signal. The two usual causes are an endpoint path longer than the platform's UNIX-socket limit (107 bytes on Linux - keep endpoints under $XDG_RUNTIME_DIR, not in a deep build directory) and a leftover endpoint that another live server still owns. On Windows, startLocal() is not supported at all - use start(port).

"License expired" after first day

You're in trial mode and your 30 days are up. The trial period is fixed at 30 days from the first run. To keep going, load a paid license key, or ask sales@vericue.dev for a signed trial key covering a longer, organization-wide evaluation (issued manually, typically within one business day).

Example applications

The public vericue-examples repository contains seven ready-to-build Qt apps (widgets, QML, touch, model/view, OpenGL) instrumented with veriCue - clone it and build against your installed SDK to see every feature area in a working program:

git clone https://github.com/VeriCueOrg/vericue-examples.git
cmake -S vericue-examples -B vericue-examples/build \
      -DCMAKE_PREFIX_PATH="/path/to/Qt/6.7/gcc_64;/path/to/vericue"
cmake --build vericue-examples/build --parallel