XiOSK Documentation

Setup Guide

Note: Starting with v5.0.0, PiOSK has been renamed to XiOSK.

XiOSK Setup Video Walkthrough

Important: XiOSK assumes a few things to keep itself lean and just focuses on the essentials. It should still work even if some of those assumptions aren't met, but it may require some tinkering & manual overrides.

1. Preparation

  1. Boot into Raspberry Pi desktop1
  2. Ensure username, hostname etc. are configured
  3. Check ethernet/WiFi works & has internet access
  4. Enable desktop auto login (set by default on RPi OS)

1 That is to say... boot into runlevel 5 or graphical.target and not in console mode — it's NOT a recommendation to use the 3.4GB boot image named Raspberry Pi OS Desktop

Note: Check recommendations section for more detailed explanations.

2. Setup and Management

XiOSK v5 simplifies lifecycle management using a single bootstrap script. You can install, update, backup, or remove the software using the specific flags below.

Installation

To install XiOSK on a fresh system, run:

bash
curl -sSL https://raw.githubusercontent.com/debloper/xiosk/main/www/public/bootstrap.sh | sudo bash -s -- --install

Updating

To update an existing installation to the latest version:

bash
curl -sSL https://raw.githubusercontent.com/debloper/xiosk/main/www/public/bootstrap.sh | sudo bash -s -- --update

Backup

To backup your current configuration (URLs, durations, etc.):

bash
curl -sSL https://raw.githubusercontent.com/debloper/xiosk/main/www/public/bootstrap.sh | sudo bash -s -- --backup

Uninstallation / Cleanup

To remove XiOSK from your system:

bash
curl -sSL https://raw.githubusercontent.com/debloper/xiosk/main/www/public/bootstrap.sh | sudo bash -s -- --cleanup

3. Usage Guide

Once installed, XiOSK serves a web dashboard on Port 80. You can access this from any device on the same local network.

3.1 Accessing the Dashboard

  1. Open a browser on your laptop or phone.
  2. Visit http://<pi's IP address>/ (e.g., http://192.168.1.50/).
  3. If you set a hostname, you might be able to visit http://xiosk.local/.

3.2 Managing Screens

The dashboard allows you to define which webpages are displayed on the Kiosk.

  • Add URL: Enter a valid URL (remote https://... or local file:///...) and click ADD.
  • Duration: Set how long (in seconds) the screen should remain visible before switching to the next URL.
  • Refresh Every: Set a count for how many times the page is shown before it is hard-refreshed (reloaded).
    • Example: Set to 10 to reload the page after it has been displayed 10 times.
    • Disable: Set to 0 to never refresh the page (useful for static content or SPAs that manage their own data fetching).

3.3 Applying Changes

Changes made in the list are not active immediately. You must click the APPLY ⏻ button. This will save your configuration and restart the Kiosk service to load the new settings.

3.4 Service Control

You can terminate Kiosk mode without shutting down the Pi by clicking the STOP button in the navigation bar. Click START to resume the Kiosk display.

4. Advanced Configuration

Warning: Try these at your own risk; if you know what you're doing. Misconfiguration(s) may break the setup.

  1. The XiOSK repo is cloned to /opt/xiosk
  2. You can change the dashboard port from index.ts (Note: Changed from index.js in v5)
  3. You can change browser behavior (e.g. no full screen) from scripts/runtime/runner.sh

5. Appendix

5.1 Assumptions

  1. You're using a Raspberry Pi (other SBCs may work, not tested)
  2. You're using "Raspberry Pi OS (64bit)" (This is a mandatory requirement for XiOSK (version 4.0.0 and newer). XiOSK now uses the Deno runtime, which does not provide official binaries for 32-bit ARM systems. This change allows XiOSK to be a standalone executable, simplifying installation by removing the need for a separate Node.js runtime.)
  3. You've applied proper OS customizations & the Pi is able to access the internet (required for setup)
  4. You're not using port 80 on the Pi to run some other web server (apart from XiOSK dashboard)

5.2 Recommendations

Choose the right device and OS

  • Raspberry Pi Zeros struggle running Chromium due to low memory
  • Raspberry Pi4 or Pi5 (or their compute modules) are ideal for XiOSK
  • Apply the necessary customizations (user account, WiFi credentials, SSH access etc)

Choose the right display/screen

  • Browser content window resolutions smaller than 1024px*600px may not be ideal
  • Different websites have different responsive rules & handle small screens differently
  • Also be mindful of LCD burn-in if displaying very limited number of static pages
  • DSI displays are more discreet, but they may require driver setup to work properly

Take necessary steps to harden security

  • Disable touchscreen unless required
  • Disable ports that aren't required
  • Disable unused network interfaces, remote SSH
  • Enable OverlayFS to write protect storage

Discover the Pi on the network

  • Set hostname (e.g. xiosk) so you can call it by hostname without needing to hunt for IP
  • The dashboard's URL with the hostname & IP address is shown at the end of the install script
  • Or, run angry IP scanner or login to router/switch to discover the Pi's IP the hard way

6. Backstory

This started as a simple automation script — a wrapper of the official Raspberry Pi kiosk mode tutorial for personal use. Then one thing lead to the other and I found myself installing nodejs & writing systemd unit files...

That's when I realized... maybe there are other people (or future me) who'd also find this "single script setup" useful.

Note: And apparently, I wasn't wrong! From GitHub stars, issue reports, to news articles covering XiOSK - the community acceptance has been far more than I had imagined. So, with the wide range of users, there's a need for stabilizing the repo and consolidating the features.