Documentation

Getting started

Create a profile with the URL and settings you want (e.g. kiosk URL, idle timeout, browser flags).
Add a kiosk in the dashboard: give it a name, optional location, and assign the profile.
Copy the one-line install command (it includes a time-limited enrollment token).
On each Ubuntu device, run that command as root. The agent installs, enrolls, and applies the profile.

The kiosk will appear in your dashboard and start checking in within a minute.

Install the agent

Requirements: Ubuntu (or compatible Linux), root access, network access to api.bigkiosks.com, and a display (X11 / :0).

You must use the enrollment token from the dashboard. Replace <enrollment-token> with the token shown when you add a kiosk (token expires after about an hour).

curl -fsSL https://api.bigkiosks.com/install.sh | sudo bash -s <enrollment-token>

The script will:

Install dependencies (Python 3, Chromium, X11, etc.)
Create /opt/kiosk-agent/ and install the agent
Enroll the device with the server and save a device key
Create and start a systemd service so the agent runs on boot

After enrollment, the agent polls the server every 60 seconds for configuration and runs Chromium in kiosk mode with your profile’s URL and settings.

Profiles and configuration

Creating a profile: In the dashboard, go to Profiles → Create. Set the URL (must be HTTPS or allowed by your tenant allowlist), optional Chrome flags, idle timeout, display rotation, timezone, auto-reboot schedule, and other options. Save to create version 1.

Assigning to kiosks: When adding or editing a kiosk, choose a profile. All kiosks on that profile receive the profile’s current version on their next check-in.

Versioning: Every time you edit a profile, a new version is created. You can see version history and rollback to a previous version. After rollback, kiosks pull the rolled-back config on their next check-in.

Preview: Use the profile detail page to preview the effective configuration before assigning it to more kiosks.

Troubleshooting

Kiosk shows offline

Kiosks are marked offline if they haven’t checked in for several minutes. Check that the device has network access, that the agent service is running (systemctl status kiosk-agent), and that the device key wasn’t revoked. If the kiosk was recently enrolled, wait a minute and refresh the dashboard.

Config not updating

The agent applies new config only when it receives a different config version from the server. Confirm the profile was saved (new version) and the kiosk is assigned to that profile. Check that the kiosk is online so it can receive the update on its next check-in.

Kiosk works offline

By design, the agent caches the last good config. If the network is down, the kiosk keeps running on the cached config. After a long outage it may fall back to a safe default. No action needed once the network is restored; the agent will resume check-ins and pull the latest config.

Enrollment token invalid or expired

Tokens expire (about 1 hour). Generate a new one from the kiosk’s page in the dashboard (or when adding the kiosk) and run the install command again with the new token. Use one token per device.