Kiosk Setup: DisplayGrid

Pre-configure the screen token

By default, the display client shows a token entry screen on first launch. To skip this and boot straight into the player, pre-configure the token in the environment file.

Create or edit apps/display-client/.env.local:

# URL of your DisplayGrid server
VITE_API_BASE=http://192.168.1.10:3000
VITE_WS_BASE=ws://192.168.1.10:3001

# Token for this specific screen (get it from Dashboard → Screens → key icon)
VITE_SCREEN_TOKEN=your-screen-token-here

Get the token from the dashboard: Screens → your screen → key icon → Copy token. Each screen has a unique token. Use a separate .env.local per kiosk device.

Linux / Raspberry Pi

Manual launch

chromium-browser \
  --kiosk \
  --noerrdialogs \
  --disable-infobars \
  --autoplay-policy=no-user-gesture-required \
  http://192.168.1.10:5173

Autostart on Raspberry Pi OS (LXDE)

Edit the autostart file:

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart

Add this line at the end:

@chromium-browser --kiosk --noerrdialogs --disable-infobars --autoplay-policy=no-user-gesture-required http://192.168.1.10:5173

Autostart with systemd (headless or Wayland)

Create a systemd user service at ~/.config/systemd/user/displaygrid-kiosk.service:

[Unit]
Description=DisplayGrid Kiosk
After=graphical-session.target

[Service]
ExecStart=chromium-browser --kiosk --noerrdialogs --disable-infobars http://192.168.1.10:5173
Restart=on-failure
Environment=DISPLAY=:0

[Install]
WantedBy=graphical-session.target

Enable and start:

systemctl --user enable displaygrid-kiosk
systemctl --user start displaygrid-kiosk

Hide the mouse cursor

Install unclutter to hide the cursor after inactivity:

sudo apt install unclutter
unclutter -idle 1 &

Add @unclutter -idle 1 to your autostart file to persist across reboots.

macOS

Manual launch

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --kiosk \
  --noerrdialogs \
  --disable-infobars \
  --autoplay-policy=no-user-gesture-required \
  http://192.168.1.10:5173

Autostart on login

Create a file named DisplayGrid Kiosk.command on your desktop with the launch command above.
Make it executable: chmod +x ~/Desktop/DisplayGrid\ Kiosk.command
Go to System Settings → General → Login Items and add the file.

Windows

Manual launch

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --kiosk ^
  --noerrdialogs ^
  --disable-infobars ^
  --autoplay-policy=no-user-gesture-required ^
  http://192.168.1.10:5173

Autostart on login

Create a shortcut to Chrome with the above arguments as the target.
Press Win+R, type shell:startup, and press Enter.
Copy the shortcut into the Startup folder that opens.

Windows kiosk tip: Consider using Windows Assigned Access (kiosk mode) in Settings to lock the device to a single app. This prevents users from exiting Chrome even with keyboard shortcuts.

Unlocking the kiosk

The display client has a built-in kiosk lock feature. To activate it, hold the configured key combination (default: Ctrl+Alt+K) for 3 seconds. A PIN entry panel will appear.

The PIN is set during the dashboard setup wizard, and can be changed in Settings. The key combination can also be customised there.

Once unlocked, the admin panel gives access to session management without touching the server.

Static build for production

For production kiosks, build the display client into a static bundle rather than running the Vite dev server. This is faster, uses fewer resources, and requires no Node.js on the kiosk device.

On the server machine, build with the correct env vars baked in:

cd apps/display-client
VITE_API_BASE=http://192.168.1.10:3000 \
VITE_WS_BASE=ws://192.168.1.10:3001 \
VITE_SCREEN_TOKEN=your-token-here \
pnpm build

This produces a dist/ folder. Serve it on the kiosk with any static file server:

# Option 1: Node.js serve (install once: npm i -g serve)
serve apps/display-client/dist -p 8080

# Option 2: Python (no install needed)
python3 -m http.server 8080 --directory apps/display-client/dist

Then point Chrome at http://localhost:8080 in kiosk mode.