Evaluating without embedding (vericue-inject)

vericue-inject lets you drive an unmodified Qt application with veriCue - no code changes, no rebuild, no linking. It is meant for evaluation: try veriCue against your real binary in minutes, then embed the server properly once you decide to adopt it.

Evaluation tool, Linux only

vericue-inject ships in the Linux packages and is intended for evaluation and exploration. For CI and production test rigs, embed the server instead - see Embedding the server.

60-second try

Install a Linux package (see Installation); it puts bin/vericue-inject and lib/libvericue-inject.so next to the server library.

In one terminal, launch your app under the injector:

vericue-inject --port 4242 -- ./your-qt-app

In another terminal, drive it with any client - for example the CLI:

python -m vericue --port 4242 list_objects
python -m vericue --port 4242 find_object --path "MainWindow/okButton"

That's it - the server is now running inside your application, exposing its live object tree over the veriCue protocol.

Everything after -- is your target command and its own arguments:

vericue-inject --port 4242 --token s3cret -- ./your-qt-app --your-flag foo

Ephemeral port

Pass --port 0 (or set VERICUE_PORT=0) to let the OS pick a free port. The injected server prints the actual port to stdout as VERICUE_PORT=<n>, so a script can capture it:

vericue-inject --port 0 -- ./your-qt-app | grep -m1 VERICUE_PORT
# VERICUE_PORT=45123

If you omit --port, the default is 4242.

How it works

vericue-inject sets LD_PRELOAD to load libvericue-inject.so into your application before it starts. That library registers a Q_COREAPP_STARTUP_FUNCTION, which Qt invokes the moment your app constructs its QApplication (or QGuiApplication / QCoreApplication). At that point the probe starts a VeriCueServer parented to the application object.

• No binary patching, no threads, no polling - it hooks Qt's own startup callback.
• Inert in non-Qt processes - if the process never constructs a QCoreApplication, the startup function simply never runs.
• Never aborts the host - if the server can't start (e.g. the port is taken), the probe prints a warning to stderr and the application keeps running normally.

The launcher first checks your target with ldd, so it fails fast with a clear message rather than a cryptic loader error.

Limitations

vericue-inject trades production-readiness for zero integration. Be aware:

• Linux x86_64 only. Not available on macOS or Windows.
• The target must link Qt dynamically. A statically linked Qt has no libQtNCore.so for the probe to piggyback on, so injection is not supported.
• Qt major must match the package. A Qt 6 app needs the qt6.7 package, a Qt 5 app the qt5.15 package. The launcher refuses a mismatch and tells you which variant to download.
• The target's Qt must be ABI-compatible with the package's. The injected server resolves Qt symbols from the Qt already loaded by your app, so use the package whose Qt major matches and whose minor is no newer than your app's Qt.
• Evaluation, not a production test rig. For repeatable CI runs, embed the server and compile it out of release builds.

For production, embed instead

Once you've evaluated veriCue, wire the server into your app explicitly and keep it out of release builds. See Embedding the server.

Security

The injected server is the same server you would embed, with the same exposure: it listens on a plaintext TCP port on all interfaces, and it is unauthenticated unless you pass --token. Anyone who can reach the port can inspect and drive your application.

Only inject on machines and networks you trust, always pass --token outside a single-developer box, and firewall or tunnel the port rather than exposing it. See the security model in the embedding guide for the full picture.