Documentation

• ✅ 2.2 | ✅ 2.1 | ✅ 2.0 | ⛔ 1.9 | ...

Since 2.2.4

Provide custom deployment options with QZ Tray that are packaged with the desktop installer. If you'd like to sideload a provisioning without modifying the desktop installer, see sideloading section.

1. Prepare environment for compiling
2. Prepare provision.json file

   [
      {
         "description": "Configure log file size",
         "type": "property",
         "data": "log.size=2097152"
      }
   ]

3. Invoke ant with the provision file:

   ant -Dprovision.file=provision.json nsis

4. You now have a customized installer.

CA | Cert | Conf | Policy | Property | Preference | Script | Software | Remover

Custom trusted root certificate is installed during the "phase": "certgen" and write an authcert.override=self-signed.crt entry to qz-tray.properties to allow deployment with 3rd-party CA or self-signed certificates. For trusting certificates issued by QZ Industries, see cert provisioning instead.

Since 2.2.5

[
   {
      "description": "Trusts a self-signed certificate",
      "type": "ca",
      "data": "self-signed.crt"
   }
]

Certificates are installed during the "phase": "startup" and write an entry to allowed.dat (e.g. %APPDATA%\qz) to avoid clicking "Remember this decision". For trusting self-signed certificates, see ca provisioning instead.

[
   {
      "description": "Trusts a certificate",
      "type": "cert",
      "data": "digital-certificate.txt"
   }
]

Conf settings are installed during "phase": "certgen" (post-install) and writes a properties entry to runtime/conf/<path> located in the installation directory. This is useful for configuring the proxy or changing local Java security policy, e.g. net.properties, logging.properties, etc.

Since 2.2.5

[
   {
      "description": "Configure proxy",
      "type": "conf",
      "data": "java.net.useSystemProxies=true",
      "path": "net.properties"
   }
]

Policies are installed during "phase": "certgen" | "install" | "uninstall" will deploy (or remove) a custom application policy to 3rd-party apps such as Google Chrome and Firefox. For each install section, it's recommended to add a matching uninstall section to cleanly remove the policy when the application is removed.

Policies are installed by leveraging the designated platform mechanism at install-time:

• Windows: Policies installed at HKLM\SOFTWARE\Policies using the Windows registry
• macOS: Policies installed at /Library/Preferences/ using the macOS preferences system
• Linux: Policies installed at /etc/ or /var/app using JSON files

[!NOTE] On Linux there may be slight disparities between where policies are installed flatpak, snap and appimage. User-mode policies are not yet supported by the provisioning process. Please inquire with support if you have any questions or concerns.

Since 2.2.6

[
   {
      "description": "Chrome: Disable LNA for qz.io and subdomains",
      "type": "policy",
      "app": "chromium",
      "name": "LocalNetworkAccessAllowedForUrls",
      "format": "array",
      "data": "[*.]qz.io"
   },
   {
      "description": "Chrome: Disable LNA for qz.io and subdomains",
      "type": "policy",
      "app": "firefox",
      "name": "LocalNetworkAccess",
      "format": "map",
      "data": "{\"SkipDomains\": [\"*.qz.io\"] }"
   },
]

Properties are installed during "phase": "certgen" (post-install) and writes a properties entry to qz-tray.properties located in the installation directory. (e.g. %PROGRAMFILES%\QZ Tray)

[
   {
      "description": "Disable logs",
      "type": "property",
      "data": "log.disable=true"
   }
]

• ‡ websocket.secure.ports and websocket.insecure.ports are an exception and must also be provided during "phase": "install" for Windows installers to set firewall rules.

Properties are installed during "phase": "startup" and write a properties entry to prefs.properties located in the user data directory (e.g. %APPDATA%\qz)

[
   {
      "description": "Show all notifications",
      "type": "preference",
      "data": "tray.notifications=true"
   }
]

Script are run during "phase": "install" or "phase": "startup" and allow granular customizations. The script will be automatically copied into the installer.

• data Must point to a valid script file and may be relative or absolute in respect to the location of provision.json.
• os is recommended and never inferred.
• The script may reference custom environment variables provided by the installer.

[
   {
      "description": "Python script",
      "os": "linux|mac",
      "type": "script",
      "data": "my_script.py"
   }
]

#!/usr/bin/env python3

import os

title=os.getenv('APP_TITLE')
version=os.getenv('APP_VERSION')

def notify(title, message):
  os.system(f"notify-send '{title}' '{message}'")

notify(title, "Hello from {} {}".format(title, version))

Software is run during "phase": "install" and will execute with the provided deployment arguments.

• os optional but will be assumed based on file extension
• arch is optional but strongly recommended
• args will automatically be split up on whitespace for convenience
  • ... if whitespace is needed, use "arg1": "first arg", "arg2": "second arg"

[
   {
      "description": "Install Notepad++",
      "type": "software",
      "os": "windows",
      "arch": "x86_64",
      "data": "npp.8.5.8.Installer.x64.exe",
      "args": "/S"
   }
]

Remover is a task to uninstall other QZ Tray installations, which is especially helpful for Company Branded builds to remove known-conflicting installs.

• data may be qz, or the application identifiers from the Company Branded portal.
  • Example: "data": "qz" Shorthand for QZ branded installers.
  • Example: "data": "Cherry Connect,cc-util,cc" Long format, required for Company Branded builds.

[
   {
      "description": "Remove QZ Tray",
      "type": "remover",
      "data": "QZ Tray,qz-tray,qz",
   }
]

Arch will designate which architecture to perform the step.

• If not provided, arch will default to "arch": "*" and run on all systems.
• Multiple values may be provided: "arch": "aarch64|riscv64"

OS will designate which platform to perform the step.

• If not provided, os will default to "os": "*" and run on all systems
  • Except software installers, which will try to choose a sane value.
• Multiple values may be provided: "os": "mac|linux"

Provisioning is intended to be bundled directly into the QZ Tray application, however if you're already leveraging custom install steps (such as manually invoking certgen) you may side-load the provision.json file by placing it into the expected location.

⚠️ NOTE: Please use "phase": "certgen" for all post-install tasks. You may also use phases uninstall and startup, for their respective phases, however phase install should not be used for sideloading purposes as this phase normally occurs prior to the app directory being created.

1. Create a directory called provision that's inside the app directory.

   • Windows: C:\Program Files\QZ Tray\provision
   • macOS: /Applications/QZ Tray.app/Contents/Resources/provision
   • Linux: /opt/qz-tray/provision

2. Create a file called provision.json:

   [
       {
           "description": "Chromium LNA Policy",
           "type": "policy",
           "phase": "certgen",
           "os": "*",
           "app": "chromium",
           "name": "LocalNetworkAccessAllowedForUrls",
           "format": "array",
           "data": "[*.]example.com"
       },
       {
           "description": "Firefox LNA Policy",
           "type": "policy",
           "phase": "certgen",
           "os": "*",
           "app": "firefox",
           "name": "LocalNetworkAccess",
           "format": "map",
           "data": "{\"SkipDomains\":[\"*.example.com\"]}"
       }
   ]

3. Re-run the task that would invokes the phase.

4. Check the terminal or log files for invocation:

   [INFO] 2026-04-17T15:35:15,053 @ qz.installer.provision.ProvisionInstaller:100
    [PROVISION] Invoking step 'Step { description='Chromium LNA Policy', ... }'