Skip to content

Headless mode

Headless mode runs the simulation of one project on the CONNECT machine, in an invisible browser that CONNECT starts and supervises itself, on Windows and on Linux. It draws nothing, but the model runs in real time and exchanges signals with your interfaces like an open tab would. Use it for automated tests of a PLC program, for a simulation that must keep running without an operator, or for a machine without a screen.

Like every realvirtual tab, headless mode runs locally on your own machine, server or network, not in a cloud service. The model and its data do not leave the CONNECT machine.

From the command line on Windows (PowerShell):

Terminal window
realvirtual-Connect.exe --headless --project <project-id> --wait-ready 90
realvirtual-Connect.exe --headless-stop

On Linux the executable has no .exe:

Terminal window
realvirtual-Connect --headless --project <project-id> --wait-ready 90
realvirtual-Connect --headless-stop

The older flags --viewer-service and --viewer-service-stop keep working as aliases.

The command starts the gateway if needed, starts headless mode and prints the status until it is ready. The exit code is 0 when the simulation runs and the project owns its document, and not 0 with the reason otherwise (for example document in use, project not loadable, project code not trusted). The reasons that only occur on Linux are listed under Errors.

You can also start and stop headless mode from the Headless mode tray menu or with POST /web/service ({ "action": "start", "project": "<id>" }). GET /web/service returns the status: state, ready flag, reason, restarts, simulation time and executed steps per second.

On Linux, CONNECT starts the browser as the account that runs CONNECT, in its own process group, and stops the whole group on --headless-stop or when CONNECT ends. Headless mode runs on linux-x64.

  1. Install a supported browser:
    • Google Chrome as a .deb package. CONNECT finds the binary /opt/google/chrome/chrome.
    • Chromium from Debian (apt install chromium). CONNECT finds the binary /usr/lib/chromium/chromium.
  2. Make sure setsid from util-linux is installed (/usr/bin/setsid). CONNECT uses it to give the browser its own process group.
  3. Run CONNECT as a systemd service, for example with the unit realvirtual-connect.service from the CONNECT package. The service account needs write access to its data directory, because the browser profile and its home folder live there.
  4. Start headless mode once with the command line above, or let it start together with the service: set ViewerService.Enabled to true and ViewerService.Project to the project id in connect-config.json, then restart the service.
{
"ViewerService": {
"Enabled": true,
"Project": "<project-id>",
"Performance": "high"
}
}

Without a graphics card the browser renders in software. That is fine here, because headless mode draws nothing.

The CONNECT repository contains an example for a container with CONNECT and Debian Chromium: deploy/docker/connect-headless/ with a Dockerfile, a compose.yml, connect-config.example.json and a README. It is an example, not a published image: you build it from your own CONNECT Linux build.

  • RV_CONNECT_API_KEY is required. Inside the container CONNECT listens on all interfaces so that the published port works, and a listener that is not loopback-only refuses to start without a key. The compose file publishes the port on the host loopback only.
  • shm_size: Chromium keeps shared memory in /dev/shm. The example sets 1 GB. With Rendering Off, Docker’s default of 64 MB was enough in our measurements; the larger value leaves room for Rendering On.
  • DisableSandbox is set in the example config. Chromium’s own sandbox does not work for a non-root user under Docker’s default security profile, so CONNECT starts the browser without it (ViewerService.DisableSandbox: true).

Without the sandbox the browser runs without a second layer of protection; CONNECT therefore lets it reach only its own loopback origin (127.0.0.1:<port>), and everything else, including hosted libraries and external assets, is blocked. If an administrator has set a managed DNS-over-HTTPS policy (DnsOverHttpsMode) for Chrome or Chromium, CONNECT refuses to start the browser in this mode (managed DoH policy).

realvirtual does not ship a browser. You install Chrome or Chromium yourself and bring its licenses and terms. The Docker example installs Chromium from the Debian packages; the license texts are in /usr/share/doc/chromium/copyright in the image.

  • Linux support is linux-x64 only. ctrlX is not supported.
  • On Linux, headless mode is officially supported up to the performance level High. Realtime on Linux is not released yet.
  • Realtime needs the gateway setting "Performance": "Realtime" in connect-config.json. The REST parameter performance alone results in High.
  • GPU rendering is not possible in headless mode under WSLg. The browser renders in software there.
Exit codeReasonWhat to do
10browser is a snap, browser path is a script, setsid missing, invalid browser path, browser not foundInstall Chrome (.deb) or Debian Chromium, install util-linux, or set ViewerService.BrowserPath to the real binary
17sandbox unavailableEnable user namespaces for the account, or set ViewerService.DisableSandbox (it adds the loopback restriction described above)
18managed DoH policyRemove DnsOverHttpsMode from the managed browser policy or set it to off, or keep the sandbox on
19browser home unavailableGive the CONNECT account write access to the viewer-service/home folder in its data directory
20network fence incompleteRestore the CONNECT browser arguments, or keep DisableSandbox off

Other exit codes apply on every platform: 11 project not loadable, 12 wait-ready expired, 13 registration required, 14 platform not supported, 15 project code not trusted, 16 document in use.

  • Runs the simulation in real time with Rendering Off: nothing is drawn, the clock and the signals keep running.
  • Owns the project document for CONNECT. While headless mode runs, a normal tab on the same gateway shows the signals but cannot change the configuration.
  • Restarts its browser when it dies, with growing waiting times, and reports each restart in the status.
  • Resets the simulation on request with POST /web/service/sim ({ "action": "reset" }).

Signals of your interfaces are read as usual with GET /signals. Values written by the PLC reach the model, and model outputs reach the PLC.

Headless mode holds the write seat of CONNECT. Because CONNECT starts and supervises headless mode itself, its seat counts as CONNECT’s own: while headless mode runs, local clients and clients with a valid API key can set and force signals over REST (POST /signals/{name}/force) and MCP (signal_set_float, signal_set_bool, signal_force) without taking the seat over. Other browser tabs stay locked out and show the signals read-only.

  1. Configure interfaces and signals first (see the caution below).
  2. Start: realvirtual-Connect.exe --headless --project <id> --wait-ready 90 (exit code 0 means ready).
  3. Set or force inputs and read outputs: POST /signals/{name}/force, GET /signals.
  4. Reset the simulation between test cases: POST /web/service/sim with { "action": "reset" }.
  5. Stop: realvirtual-Connect.exe --headless-stop.

When CONNECT serves a project folder (--project-root), the project owns its configuration files and CONNECT uses no document lease. Headless mode then owns the document by holding the write seat. If another session already holds the seat, the status shows document not owned and headless mode does not take it away.