Install on macOS

macOS does everything. The wheel, import, screens, OpsLink and Steam games all run here today.

There is no installer and no runtime to install first. It is an app you copy.

Install it

1. Download the macOS build from Releases and drag vPinOps.app to your Applications folder.

2. Open it.

   Nothing appears full-screen yet. You get a status icon in the menu bar, top right. That icon is how you talk to vPinOps from now on — it is also the only way to quit it.

   It creates ~/.vpinops/ on this first run: your config, your run log, and a generated OpsLink password.

   macOS will refuse to open it the first time

   The build is not signed with an Apple developer certificate yet, so Gatekeeper blocks it on first launch. Right-click the app and choose Open, then confirm — you only do this once. If you double-clicked and got a refusal, the approval is also waiting in System Settings → Privacy & Security.

   No icon in the menu bar?

   macOS silently drops status icons when the menu bar runs out of room, and it does not tell you. Quit something else that lives up there and start vPinOps again.

3. Open Settings from the menu bar icon and check the network.

   That window does one job: it makes OpsLink reachable. Port, password and Listen on — that is everything this window holds, deliberately, because those three are exactly what you cannot fix from a phone that cannot connect.

   Leave all three as they are unless something else already wants port 7833.

   Your paths are not in this window

   VPX, Tables, PinMAME and the rest are set in OpsLink, in a browser — along with your screens and your library. (Mapping a controller is the one thing that is neither: it is in the same menu as Settings.) Get the network working here first; everything else happens there.

4. Check your phone can reach it.

   The run log names the address every time it starts:

   remote: LISTENING on http://0.0.0.0:7833  (open http://192.168.4.58:7833)

   Open that in any browser on the same network. Sign in with the password in ~/.vpinops/remote-password, then change it in Settings — it is generated to be typeable on a phone, not to be strong. More: connecting to OpsLink.

   If the Mac answers itself but nothing else can reach it, check macOS’s firewall in System Settings → Network → Firewall.

5. In OpsLink, open Settings and point it at your stuff.

   Settings → Where your stuff lives. Press Fill these in for me and it fills in the suggested layout for you:

   • Tables → ~/vPinOpsData/tables
   • VPX settings → ~/vPinOpsData/visualpinball
   • PinMAME and Your content as well

   Then set VPX yourself — point it at ~/vPinOpsData/visualpinball/app/VPinballX_BGFX.app using Browse…. The button deliberately leaves this one alone: vPinOps does not install Visual Pinball, so it will not write a path to a file it has not checked is there. It is also the one path you cannot skip — without it the page says Not ready to play.

   Change any of them — an existing library, an external drive — nothing refuses to work if you ignore the suggestion. Nothing is saved until you press Save settings, and folders under your content root are created for you when you do.

   What the PinMAME box is actually for

   It matters only if you keep your ROMs in one shared folder. vPinOps reads it to check a table’s ROM is there before launching, so it can tell you what is missing instead of dropping you into a black screen. If every table carries its own pinmame/roms/ you can leave whatever the button put there — nothing looks in it. It is not passed to Visual Pinball; VPX has its own setting for the shared folder. See ROMs and nvram.

   Visual Pinball first, if you have not already

   Put VPinballX_BGFX.app in ~/vPinOpsData/visualpinball/app/ and launch it once on its own so it writes its settings. The build sits one level below its own settings deliberately: clear app/ to replace a Visual Pinball version and VPinballX.ini survives it.

   vPinOps does not write VPinballX.ini until you launch a table — up to that point Visual Pinball’s settings are exactly as you left them.

6. Set the two macOS display settings a cabinet needs.

   In System Settings → Desktop & Dock:

   setting	value
   Automatically hide and show the menu bar	Always
   Automatically hide and show the Dock	on

   These are required on a Mac, not recommended

   vPinOps covers the menu bar. Visual Pinball does not. So if you leave it showing, the wheel looks right and then the menu bar sits across the top of every table you launch, hiding the top strip of it.

   The Dock does the same at the bottom. Nothing is misplaced by either of them — the table is still drawn to the full screen underneath, so this is not something you can fix from inside vPinOps. They are simply on top of it.

   “Always” is the only value that works. The other options — including macOS’s own default, “In Full Screen Only” — never fire, because neither vPinOps nor Visual Pinball uses native macOS full screen. A setting that looks enabled and silently does not apply is the most confusing kind there is.

7. Now put some tables in it.

   That works the same on every platform, so it lives in one place: Importing.

What ended up on your disk

~/Applications/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

The split is ours versus yours, not programs versus data. Visual Pinball is yours, which is why it sits under the content root rather than beside our program. The updater may only ever write inside the program, and uninstalling is deleting it.

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.

Getting a cabinet’s screens right

The display settings above are the macOS half. Where the playfield, backglass and DMD actually go is screens and layout — vPinOps writes those keys per table, immediately before launch, so a table that wants a different arrangement gets one. If a window lands somewhere wrong, the run log names exactly what was written.

Where things are

The program	~/Applications/vPinOps.app
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 menu bar icon, replace the 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 the app — your tables are still yours.