Skip to content

Runtime Install — Windows mini-PC

How to set up the Windows mini-PC that hosts IMMERSE Runtime at the venue.

Hardware

  • Any small Windows PC. Intel NUC, Beelink S12, Lenovo M75n, etc.
  • Minimum spec: 4 GB RAM, 64 GB SSD, gigabit Ethernet
  • Wired connection to the show network switch — not Wi-Fi

OS setup

  1. Install Windows 11 (Pro recommended for Group Policy, but Home works)
  2. Set the PC's hostname to something descriptive: IMMERSE-RUNTIME or runtime-{venue}
  3. Set a static IP for the show network interface — match the IP plan from site-prep.md
  4. Install Edge or Chrome (you almost certainly have one already)
  5. Disable Windows Update during shows — it WILL try to reboot mid-show otherwise. Set "Active hours" to span your show schedule, or pause updates entirely on show days.
  6. Disable sleep/hibernation: Settings → System → Power → Screen and sleep → Never
  7. Disable Notifications during the show — focus assist or Do Not Disturb

If the venue powers down nightly and the Runtime PC has no human to log in:

  1. Win+R → netplwiz
  2. Uncheck "Users must enter a user name and password"
  3. Enter the password twice when prompted
  4. Reboot to verify it auto-logs in

Install IMMERSE Runtime

  1. Copy IMMERSE-Runtime-v0.1.0.zip to the PC (USB stick or network)
  2. Unzip to C:\IMMERSE-Runtime\
  3. If Node.js isn't installed:
  4. Download Node.js LTS from https://nodejs.org
  5. Run the installer, defaults are fine
  6. Open Command Prompt in C:\IMMERSE-Runtime\
  7. Run npm install — this fetches the e131 package (sACN library) and takes about 60 seconds
  8. Test: node src\runtime.js path\to\sample-show.ishow
  9. You should see "IMMERSE Runtime v0.1.0 starting"
  10. A small browser window should pop up showing the dashboard
  11. In the console window, type quit

Or: build the standalone EXE

For deployments where you don't want Node.js installed on the Runtime PC:

  1. On a development machine, run npm run build in the immerse-runtime folder
  2. Copy dist\immerse-runtime.exe to the Runtime PC
  3. Copy the .ishow file alongside it
  4. Run: immerse-runtime.exe show.ishow

The exe is fully self-contained — no Node.js install needed.

Auto-start on boot

You want Runtime to launch when the PC boots, with the show file pre-loaded.

Option 1: Startup folder (simplest)

  1. Create a .bat file like this: 
    @echo off
cd C:\IMMERSE-Runtime
node src\runtime.js C:\Shows\current-show.ishow --log C:\Shows\logs\runtime.log
  2. Save it as start-runtime.bat
  3. Press Win+R, type shell:startup, press Enter
  4. Drag a shortcut to start-runtime.bat into the Startup folder
  5. Reboot — Runtime should launch automatically

Pros: simple, requires no admin tools. Cons: only runs when the user is logged in. If Runtime crashes, no auto-restart.

  1. Open Task Scheduler
  2. Create Task (not Create Basic Task)
  3. General tab:
  4. Name: "IMMERSE Runtime"
  5. "Run whether user is logged on or not"
  6. "Run with highest privileges"
  7. Triggers tab:
  8. "At startup"
  9. Actions tab:
  10. "Start a program"
  11. Program: node
  12. Arguments: C:\IMMERSE-Runtime\src\runtime.js C:\Shows\current-show.ishow
  13. Start in: C:\IMMERSE-Runtime
  14. Settings tab:
  15. "If the task fails, restart every 1 minute"
  16. "Attempt to restart up to 5 times"
  17. Save (will prompt for the user password)

Pros: auto-restart on crash, runs without login, more robust. Cons: console output not visible — you have to tail the log file.

Option 3: NSSM (gives you a Windows service)

NSSM — Non-Sucking Service Manager — wraps any program as a Windows service. Use it if you want Runtime to behave like SQL Server or IIS — managed by services.msc, restartable, log-streamed.

nssm install IMMERSE-Runtime "C:\Program Files\nodejs\node.exe" "C:\IMMERSE-Runtime\src\runtime.js" "C:\Shows\current-show.ishow"
nssm set IMMERSE-Runtime AppDirectory C:\IMMERSE-Runtime
nssm set IMMERSE-Runtime AppStdout C:\Shows\logs\runtime-stdout.log
nssm set IMMERSE-Runtime AppStderr C:\Shows\logs\runtime-stderr.log
nssm start IMMERSE-Runtime

This is the most production-grade option. Recommended for permanent installations.

Open Runtime's ports through Windows Firewall

By default, Windows Firewall blocks inbound connections from other devices. Operator tablets won't reach the dashboard.

netsh advfirewall firewall add rule name="IMMERSE Runtime" dir=in action=allow protocol=TCP localport=7880

This opens port 7880 (the dashboard + API). DMX/sACN goes outbound, no firewall change needed.

Verify the install

Once Runtime is running:

  1. From the Runtime PC: curl http://localhost:7880/status — should return JSON
  2. From a separate device on the same network: http://<runtime-ip>:7880/ — should show the dashboard
  3. From the Runtime PC's console: status and quit should work
  4. Check the log file: should show "Listening on" and "Loaded show"

Where things live

After install, expect this layout:

C:\IMMERSE-Runtime\         ← Runtime install
C:\Shows\                   ← convention for show files
  current-show.ishow        ← the active show
  archive\                  ← prior versions
  logs\                     ← runtime log files
    runtime.log
    runtime.log.old

This isn't enforced by the software — Runtime just reads paths you give it on the command line — but it's a sane convention.

What to do when the show file changes

The designer has updated the show. Steps:

  1. Receive the new .ishow (rsync, USB, email, whatever)
  2. Validate it: from any machine, node tools\ishow-validator.js newshow.ishow — should report 0 errors
  3. Copy it to C:\Shows\current-show.ishow (overwriting the previous version, after archiving the old one)
  4. From the operator's dashboard or the console, POST /load or load <path> to reload without restarting Runtime
  5. Or: restart the Runtime service if you prefer a clean state

You don't need to reboot the Runtime PC. Just reload the show.