Install on Linux

v1.0 is out. This page gets it running; if it does not, tell us what breaks.

Linux covers ordinary desktops and dedicated cabinets. One build, not a special one. This page gets it running; Getting started takes it from there.

Install it

1. Download vPinOps-linux-x64.zip from Releases.

2. Unpack it in your home folder.

   unzip ~/Downloads/vPinOps-linux-x64.zip -d ~

   The zip contains a vpinops folder, so you end up with ~/vpinops/app/. Unpack it anywhere else and everything still works; the paths below just change to match. No unzip on the machine? bsdtar -xf ~/Downloads/vPinOps-linux-x64.zip -C ~ does the same job.

   Extracting it by double-clicking gives you one folder more

   Desktop archive managers usually wrap what they extract in a folder named after the zip, so you get ~/vPinOps-linux-x64/vpinops/app/ instead. Nothing is broken. Move that inner vpinops folder into your home folder, or leave it and read the paths below with your own in place of ~/vpinops.

   It carries its own runtime. There is no .NET to install first, and nothing is added to your system. It ran on a machine that had never had .NET on it.

3. Start it:

   setsid ~/vpinops/app/vPinOps >/dev/null 2>&1 &

   That starts vPinOps on its own, so you can close the terminal straight away. A plain ~/vpinops/app/vPinOps works too, but it keeps the terminal busy until you quit vPinOps.

   You get a tray icon. That icon is how you talk to vPinOps from now on, and it is the only way to quit it.

   It creates ~/.vpinops/ on this first run: your config, your run log, and a generated OpsLink password. It also creates ~/vPinOpsData/, where your tables and Visual Pinball go. Nothing is installed system-wide and nothing needs root.

   You only need the terminal this once. That first run also puts vPinOps in your applications menu — ~/.local/share/applications/vpinops.desktop, with its icon beside it — so from now on you start it the way you start anything else.

   It is a file in your own home and it is yours: delete it and it stays deleted. If you already wrote one by hand, vPinOps leaves yours alone. To get ours back after deleting it, remove ~/.vpinops/launcher-installed and start vPinOps again.

4. Install ffmpeg, if you want video on the wheel.

   Playfield and DMD videos are played through ffmpeg, which most distributions ship but do not install by default. Without it a surface shows its still image instead.

   sudo apt install ffmpeg        # Debian, Ubuntu, Kubuntu

   sudo pacman -S ffmpeg          # Arch, Omarchy

   On other distributions it is the same package, installed however your distribution installs software.

5. Now set it up. Everything from here is the same on every platform, so it lives in one place: Getting started, from step 2.

Opening the port, and nothing wider

OpsLink — the page you open on your phone — is an HTTP service on port 7833/tcp. Two separate things decide who can reach it, and they are worth keeping apart.

vPinOps decides which networks it listens on. Settings → Listen on. It is 0.0.0.0 by default, meaning every network this machine is on. Set it to 127.0.0.1 and it is reachable from this machine and nothing else — no phone, ever. That is the strongest lock available and it needs no firewall.

Your firewall decides who gets through. Plenty of Linux desktops run none at all, in which case there is nothing to open and your router is already what keeps the internet out. Find out which one you have before writing a rule for a tool you are not running:

sudo ufw status; sudo firewall-cmd --state; sudo nft list ruleset | head -n 5

Two of those three will say command not found or not running. The one that answers is yours.

Your own network only

Every rule below is scoped to your subnet. Find it:

ip -4 addr show scope global | grep inet

inet 192.168.1.42/24 means your network is 192.168.1.0/24. Substitute yours everywhere below.

sudo ufw allow from 192.168.1.0/24 to any port 7833 proto tcp comment 'vPinOps OpsLink'

sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=192.168.1.0/24 port port=7833 protocol=tcp accept' && sudo firewall-cmd --reload

sudo nft add rule inet filter input ip saddr 192.168.1.0/24 tcp dport 7833 accept

— ufw, firewalld, nftables, in that order. The nft rule lasts until you reboot; put it in /etc/nftables.conf to keep it.

Scope the rule to your subnet, not just to the port

A bare sudo ufw allow 7833 opens the port on every network this machine is ever on, including a hotel or a coffee shop. Scoping the rule to your own subnet means a stranger never reaches the sign-in page at all. The password is still the gate either way — this is the layer in front of it.

To take a rule back, delete it the same way you added it — e.g. sudo ufw delete allow from 192.168.1.0/24 to any port 7833 proto tcp.

Building a dedicated cabinet

Two things decide whether a Linux cab works, and neither is your distribution.

1 · Use a normal user account with auto-login. Not a daemon account.

A daemon account, a systemd service, a nologin shell, no session, can serve OpsLink perfectly well, because that is just an HTTP listener. What it has no way to do is put a window on a display, because there is no graphical session for it to put one in. That is how Linux works rather than anything about vPinOps.

⇒ So if you want vPinOps to play tables, give it a logged-in graphical session. A normal user with auto-login is exactly that, and it needs no privileges of any kind.

Auto-login is a setting in your display manager, not in vPinOps:

GDM	/etc/gdm3/custom.conf, the [daemon] section
LightDM	/etc/lightdm/lightdm.conf
SDDM	/etc/sddm.conf

Most desktops also expose it in their own Settings → Users panel, which is the easier route.

Then make vPinOps start with that session: in the tray menu, tick Start vPinOps when I log in. It writes a standard autostart entry, ~/.config/autostart/vpinops.desktop, which your desktop runs when you log in. Untick it and the file is gone. With Launch front end at startup also on, the cabinet comes up straight to the wheel. Tested on Omarchy; KDE Plasma reads the same file, but that has not been tried yet.

vPinOps does not write your display manager’s config, and it never will. Those files need root, they differ on every distribution, and a front end that edits them is a front end that breaks somebody’s login. We document it; you choose it.

2 · Wayland or X11

Your screens work on Wayland. The wheel and its backglass, DMD and topper go where you put them, and Visual Pinball’s own surfaces reach the right monitors too. How they are placed, and what to check when one lands on the wrong monitor, is on Screens and layout.

Keyboard focus when a table opens

Visual Pinball opens its score view last, and on Wayland that window ends up holding the keyboard, so the flippers do nothing until you click the playfield. On KDE Plasma and on Hyprland vPinOps hands the keyboard back to the playfield for you, by asking the desktop rather than by any permission. On other desktops it cannot yet, and it says so in the run log rather than failing quietly. If your table waits for a click, that is this.

⚠ Tested on two desktops: KDE Plasma, and Hyprland on Arch Linux (Omarchy). Other desktops, GNOME included, are untested. It is the same download on both — vPinOps notices which desktop it is running under. Linux desktops vary far more than Windows or macOS, so if something does not behave, the run log is what to send us, along with which desktop you use and whether you are on Wayland or X11.

On Hyprland

Hyprland is a tiling desktop: it decides where windows go, and it ignores the positions an application asks for. So on Hyprland vPinOps asks Hyprland itself to put the wheel, the backglass and the DMD fullscreen on their monitors, and adds window rules so they open there every time. Those rules live only in the running session. Nothing is written to your Hyprland config, and they are gone when you log out.

Each surface fills its monitor there, except one that shares the wheel’s screen, which is left where it is. A smaller box drawn inside a screen is not kept on Hyprland yet.

Turn off the screensaver on a cabinet

On Linux vPinOps does not yet stop your desktop’s screensaver or idle lock. On a dedicated cabinet, switch them off in your desktop’s settings. A screensaver that starts over the wheel can leave the backglass and DMD un-fullscreened on Hyprland until the next table is played.

X11 sessions are going away

Some distributions have already dropped their X11 session, and more will. If your desktop still offers one at the login screen it is a valid way to run a cabinet today, but it is not something to build a new cab around.

What ended up on your disk

~/vpinops/app/               the program. Ours. Replaced wholesale when you update.
~/vPinOpsData/               your content. Never touched by an update.
    tables/                      one folder per table
    pinmame/                     the shared ROM fallback
    .inbox/                      tables sent from another device land here
    visualpinball/               Visual Pinball's own settings
    visualpinball/app/           Visual Pinball itself
~/.vpinops/                  your config, your run log, your OpsLink password

~/vPinOpsData/ appears when you set your folders in Getting started; the rest is there from the first run.

Keep them separate, as above. An update replaces the program folder and never touches your content. Where things are has the full map.

The dot in .inbox is load-bearing

vPinOps searches your content several levels deep and skips any folder whose name begins with a dot. Rename .inbox and a half-finished upload shows up on the wheel as a table you cannot play.

Where things are

The program	wherever you unpacked it — ~/vpinops/app/ is the suggestion
Your content	~/vPinOpsData/
Config	~/.vpinops/config.json
Run log — read this first when anything is wrong	~/.vpinops/last-run.log
OpsLink password	~/.vpinops/remote-password
Uploads waiting to be imported	~/vPinOpsData/.inbox
Visual Pinball’s own settings	wherever VPX settings points in Settings — by default ~/vPinOpsData/visualpinball/VPinballX.ini

Updating and uninstalling

Quit vPinOps from the tray icon, replace ~/vpinops/app/ with the new one, start it again. Your content and your config are in the other two places and are not involved. To uninstall, quit it and delete that folder. Your tables are still yours.