Kiosk UI

Last updated on November 20, 2026

In kiosk mode, the CLI starts a local WebSocket server on loopback and opens the Operator UI full screen: in its own window on Windows and macOS, in a kiosk-mode browser on Linux, with no toolbars and no address bar. The window's lifetime tracks the daemon, so operators see only the procedure UI for as long as the station is running.

There are three operator UI modes in total, so see Terminal UI for the in-shell variant and Remote UI for remote supervision.

Kiosk mode needs a graphical display. A station running as a root system service (see Launch on boot) has no display, so the kiosk cannot open and the dashboard disables this toggle. Control those stations from the dashboard instead.

Enable kiosk mode

The kiosk_ui station config key controls kiosk mode, and you set it at Station > Configuration > Kiosk UI on the dashboard. The change syncs on the next config push, and the CLI reads the key on startup.

A tofupilot run --deployment follows the same setting. To override it for a single run, or to show the kiosk on a local-path run, pass --ui or --no-ui (see tofupilot run).

terminal
tofupilot run ./procedure.yaml --ui kiosk
tofupilot run --deployment 550e8400-e29b-41d4-a716-446655440000 --no-ui

When you turn kiosk_ui off, the station serves no local operator UI; operators use the dashboard.

What happens on station start

When the daemon comes up with kiosk mode on, it walks through four steps before the operator sees the UI.

  1. It binds a local WebSocket server on 127.0.0.1 and prints Operator UI: <url> to the log.
  2. It seeds the WebSocket hello frame with the current local deployments so the SPA renders the procedure list immediately.
  3. It opens the kiosk window on the local URL (see How the kiosk window opens).
  4. It holds the window process in a KioskHandle whose Drop impl kills it on daemon shutdown.

How the kiosk window opens

One host per platform.

PlatformHostPrerequisite
WindowsCLI window on WebView2WebView2 runtime. Present on current Windows 10 and 11 consumer and Pro editions; LTSC, IoT Enterprise and N editions need the standalone installer, which works offline.
macOSCLI window on WKWebViewnone
LinuxChromium in kiosk modeChromium, preinstalled on Pi OS Desktop; install commands per distribution

If the prerequisite is missing, the CLI logs what to install and opens the operator UI in the default browser: the station works, the window has tabs and does not close with the daemon.

Windows and macOS: the CLI window

tofupilot kiosk-window hosts the operator UI in a bare web view, full screen, with no tab strip, address bar, menus, browser shortcuts, translate prompt, sidebar or image search. Navigation is limited to the station's own loopback origin, file drops and downloads are refused, and closing the window with Alt+F4 or Cmd+Q does nothing; the window ends when the station stops. On macOS, Quit from the Dock menu does end the window; the daemon opens a new one a few seconds later. Operating-system shortcuts (Alt+Tab, Cmd+Tab, Mission Control) are not affected. Links that open the dashboard are hidden: there is no browser to open them in.

To serve the operator UI without any window, for a test client or a browser opened by hand, run tofupilot run --ui headless. A local-path run in a terminal without --tui does this by default.

Linux: Chromium kiosk mode

To install Chromium:

DistributionCommand
Ubuntu, and derivatives with snapd (Zorin, KDE neon)sudo snap install chromium
Debian, Linux Mintsudo apt install chromium
Raspberry Pi OS Bookworm and older (preinstalled on Desktop)sudo apt install chromium-browser
Raspberry Pi OS Trixiesudo apt install chromium
Fedorasudo dnf install chromium
RHEL, Rocky, AlmaLinuxChromium is in EPEL: sudo dnf install epel-release (on RHEL, enable CodeReady Builder and install the EPEL release package), then sudo dnf install chromium
Archsudo pacman -S chromium
openSUSEsudo zypper install chromium

On other distributions (Pop!_OS, elementary OS, SLES), install a package that puts chromium or google-chrome on PATH, such as Google Chrome's .deb or .rpm. A Flatpak does not: the CLI does not find it.

Station setup checks for it on a machine with a desktop session installed: when the kiosk UI is on and no Chromium is found, tofupilot login --token prints the command for the distribution and, at a terminal, offers to run it with sudo, which asks for your password. A headless machine (Pi OS Lite, Ubuntu Server) is not checked: no window opens there with or without Chromium. The station also reports it to the dashboard, which shows No Chromium on this station under the Kiosk UI setting until Chromium is installed and the station restarts.

The CLI launches the first of chromium-browser, chromium, google-chrome, google-chrome-stable found on PATH. Each launch gets a fresh, private profile, so a regular browser window already open on the station is left alone and nothing from a previous run carries over. The CLI passes:

ConcernSwitches and preferences
Kiosk window--kiosk, --noerrdialogs, --class=tofupilot (the window carries the TofuPilot icon when the desktop icon setting is on)
First run, default-browser prompt, search-engine choice--no-first-run, --no-default-browser-check, --disable-search-engine-choice-screen
OS keyring prompt--password-store=basic
Translate prompt--disable-features=Translate, translate.enabled off
Password and autofill bubblescredentials_enable_service, profile.password_manager_enabled, autofill.profile_enabled, autofill.credit_card_enabled off
Spellcheck underlinesbrowser.enable_spellchecking off

Chromium kiosk mode is a presentation mode. The window is full screen with no toolbars, but the rest of the browser is still there and keyboard shortcuts such as Ctrl+T, Ctrl+O and F12 keep working. Policies close them; see below.

The operator UI is English. The translate prompt is disabled on purpose: a machine-translated procedure changes labels and units in ways an operator cannot see.

Brand the kiosk with your organization icon

On the Pro and Enterprise plans, stations show your organization icon instead of the TofuPilot logo: in the top bar, in the taskbar or Dock, and with your organization name in the window title.

Upload the icon in Settings > General > Icon. Use a square mark without text. Open kiosks pick up a new icon without a restart.

Locking down the browser

Linux only. The switches above remove prompts; they do not stop an operator from opening a tab, a file dialog or the developer tools, and Gemini and Lens have no command-line switch at all. Those are controlled by Chromium policies, which the station administrator installs once per machine. The CLI never writes policies: they need root and they change the browser for every user of the machine.

After installing a policy file, open chrome://policy in a normal browser window on the station. Every value below should be listed as applied. Policies take effect on the next kiosk launch.

Chrome and Chromium

Chromium reads JSON files from /etc/chromium/policies/managed/, Chrome from /etc/opt/chrome/policies/managed/. Snap Chromium reads /etc/chromium-browser/policies/managed/.

/etc/opt/chrome/policies/managed/tofupilot.json
{
  "TranslateEnabled": false,
  "GenAiDefaultSettings": 2,
  "GeminiSettings": 1,
  "AIModeSettings": 1,
  "HelpMeWriteSettings": 1,
  "TabOrganizerSettings": 1,
  "LensOverlaySettings": 1,
  "PasswordManagerEnabled": false,
  "AutofillAddressEnabled": false,
  "AutofillCreditCardEnabled": false,
  "SpellcheckEnabled": false,
  "DefaultBrowserSettingEnabled": false,
  "BrowserSignin": 0,
  "SyncDisabled": true,
  "BackgroundModeEnabled": false,
  "MetricsReportingEnabled": false,
  "DeveloperToolsAvailability": 2,
  "DownloadRestrictions": 3,
  "URLAllowlist": ["http://127.0.0.1", "chrome://policy"],
  "URLBlocklist": ["*"]
}

GenAiDefaultSettings is the default for every generative AI feature Chrome adds; value 2 disables them. The per-feature policies above override it for the features Chrome ships today, so a new AI feature is off before anyone hears of it.

Raspberry Pi: labwc touch fix

Pi OS Bookworm ships labwc in mouse-emulation mode, which makes touch events behave like mouse drags and breaks scrolling and slider controls. To work around this, the CLI patches the labwc config on Linux when kiosk mode is enabled.

On Linux with kiosk mode enabled, the CLI patches ~/.config/labwc/rc.xml once at startup:

  • It flips every <touch mouseEmulation="yes"/> to "no".
  • It sets <libinput><mouseEmulation>no</mouseEmulation></libinput>.
  • It writes a .bak.tofupilot backup.

The patch is best-effort, so a missing config, a non-labwc compositor, or a parse failure logs a warning and lets the daemon continue.

Deployment status and Pull now

The PROCEDURE menu in the top bar shows the deployment the station runs for the selected procedure: its ID, the first line of its commit message, and when it was installed. A badge next to the Deployment heading tells the operator where that deployment stands.

BadgeMeaning
Up to dateThe station's last check reached the dashboard and found nothing newer.
InstalledThe deployment is in place, but the station has not reached the dashboard since it started, or its last check failed (offline).
Checking / PullingA check is running, or a new deployment is downloading and installing.
Update readyA newer deployment was downloaded during a run. The line under the details names it, and the next run uses it.
FailedThe last install failed. The error is shown under the details, and the previous deployment keeps running.

The station keeps this status itself, so it survives a reload of the operator UI, including in the middle of a run.

The refresh button next to the badge, Pull now, asks the station to check for a new deployment right away instead of waiting for its next check. After a failed install it reads Retry and installs the deployment again without waiting for the retry delay.

Pull now is hidden while a run is starting, scanning its unit or running, and the station accepts it at most once every 30 seconds. The dashboard's Pull now, on the station page, works at any time.

Shared with the dashboard

On a station running as a service, the kiosk and every dashboard tab on the station show the same prompt values as they are typed, and the top bar shows who else is on the station. See Fill prompts together and See who is here.

Lifecycle

The kiosk window dies with the daemon, and the Close CLI button in the operator UI sends an Exit station command over the local WebSocket. The CLI catches that command, detaches the kiosk handle synchronously, and exits, and kill -TERM produces the same result.

The window also dies when the daemon does not get to clean up: a kill -9, an out-of-memory kill, a crash. The window process is a process group (a Job Object on Windows) the operating system ends with the daemon, the native window polls the daemon's pid and exits when it is gone, and on Linux Chromium runs under a small tofupilot kiosk-launcher process that does the same poll and ends the browser when the daemon is gone. Whichever way the daemon stops, no frozen operator screen is left over it. The operator UI itself shows a Reconnecting to the station notice two seconds after it loses the daemon's WebSocket, which turns into Station stopped after 30 seconds, and comes back on its own when the daemon is running again.

A window that dies while the daemon is healthy (a WebView2 or Chromium crash, an out-of-memory kill of the renderer, a window closed by hand) is reopened by the daemon: after 2 s the first time, then 4, 8, up to 60 s between attempts while the window keeps dying at start. The daemon logs each exit with the delay before the next attempt.

How is this guide?

On this page