v2.0.0 - kioskOS/os - Yena.dev: Development for the rest of us.

kioskOS/os

Watch

Fork 0

4 releases 4 tags

RSS feed

v2.0.0 9e81ed2010

v2.0.0 Stable

kaisa released this 2026-07-26 03:28:30 +00:00 | 2 commits to main since this release

⚠️ Breaking changes & upgrade notes

2.0.0 is a breaking release. Devices no longer self-register.

An administrator now creates each kiosk in the control server and issues a
one-time enrollment code, which the device redeems for its auth token.
Agents older than 2.0.0 cannot enroll against a 2.0.0 server.
Already-enrolled devices keep their tokens and keep checking in, but must
be re-imaged (or upgraded and re-enrolled) to obtain browser sessions
— kiosk pages now authenticate to terminal APIs through a device-session
cookie that only 2.0.0 agents can obtain.
The standalone kioskos-browser.service unit is gone. Upgrading via
install.sh disables and removes the legacy unit, its generated
start-browser.sh launcher, and browser.env. The agent is now the only
browser launcher.

Upgrade path: deploy the 2.0.0 control server first (existing devices
continue to check in), then roll out 2.0.0 images/agents and enroll each
device with a fresh code.

Protocol (agent ↔ server API `v1`)

Breaking

POST /api/v1/register/ now requires enrollment_code. Anonymous
self-registration is removed; every other field in the request is
self-asserted, recorded for inventory only, and never trusted. Unknown,
expired, and redeemed codes all return the same 403.

New endpoints

Endpoint	Auth	Purpose
`POST /api/v1/browser-grant/`	device token	Mint a single-use URL (2-minute expiry) that sets an `HttpOnly` device-session cookie and redirects to the target page. Off-origin `next=` values are discarded.
`GET /api/v1/setup/status/` · `POST /api/v1/setup/`	public (one-shot)	First-boot onboarding: report whether an admin exists / create the first admin.
`POST /api/v1/auth/login/` · `/logout/` · `GET /auth/me/`	session	Admin UI session authentication.
`POST /api/v1/kiosks/{uid}/enrollment-code/`	admin session	Issue a fresh one-time enrollment code.
`POST /api/v1/kiosks/{uid}/command/`	admin session	Queue a one-shot `reload_browser` / `restart_browser` command.

Response & field changes

Registration, check-in, and config responses now carry
screen_orientation (normal / left / right / inverted —
values pass straight through to xrandr --rotate).
Check-in responses carry command: the pending one-shot command,
delivered exactly once (the server clears the slot in the same request).
Empty string when none is queued. Delivery latency is bounded by
checkin_interval (default 60 s).
config_updated is derived from admin config_update events newer than
the device's last_seen_at.

Security model

Devices authenticate with Authorization: Token <token>; the token is
minted only by redeeming an enrollment code and never enters the browser.
Admin endpoints use session auth with CSRF protection; registration,
login, and setup are rate-limited.

Control (Django control server)

New admin web UI

Complete Angular + PrimeNG single-page admin interface replacing raw API
usage: login page, kiosk list with live online/offline/unenrolled status,
kiosk detail with a full configuration form, and an event history table.
Kiosk lifecycle from the UI: create (returns an enrollment code to hand to
the installer), edit, delete, re-issue enrollment codes, and queue
remote browser actions.
First-boot onboarding page: a fresh install walks the operator through
creating the initial admin account.

Enrollment & authentication

One-time enrollment codes (XXXX-XXXX-XXXX): human-typeable alphabet
that drops easily-misread characters (O/0, I/1, S/5, Z/2), 7-day expiry,
single-use, and unique per kiosk. Re-issuing a code never invalidates a
working device token, so it cannot knock a kiosk offline.
Registration rejects unknown, expired, and already-redeemed codes with an
identical response, so the endpoint cannot be used to probe which codes
exist.
First-boot setup endpoint (/api/v1/setup/) is open only while no admin
exists, then permanently closed.
Session-based auth endpoints for the admin UI (/auth/login/,
/auth/logout/, /auth/me/) with CSRF protection.
Rate limiting on registration, login, and setup endpoints.

Device management features

Browser session grants: the server mints single-use, short-lived grant
URLs that give the kiosk browser an HttpOnly device-session cookie —
the device token itself never reaches the browser.
Screen orientation per kiosk (normal, left, right, inverted),
editable in the admin UI and delivered to the device with every
registration and check-in response.
One-shot remote commands: admins can queue reload_browser or
restart_browser from the kiosk detail page. The command is delivered on
the device's next check-in and cleared atomically, so it fires exactly
once; queueing a new command replaces a pending one.
Every admin config change and queued command is recorded as a kiosk event
and drives the config_updated flag on the next check-in.

Operations

Dockerfile and entrypoint reworked: migrations, static file collection,
and Gunicorn startup are handled on container boot.
Test suite expanded to 47 tests covering enrollment, check-in, commands,
orientation, onboarding, and admin auth.

KioskOS Agent (`kioskos-agent` 2.0.0)

Enrollment & sessions

Registration redeems the admin-issued enrollment code; the agent no longer
invents its own identity. Clear operator-facing errors distinguish a
missing code from a rejected one.
Registration is retried from the check-in loop rather than only at
startup, since it can now legitimately fail on a bad or expired code.
Before each browser launch the agent exchanges its token for a browser
grant URL, giving kiosk pages a device session without ever exposing
the token to Chromium. If the grant cannot be obtained the agent falls
back to the plain URL (a visible page beats a blank screen) and marks the
launch degraded.

Reliability (white-screen fixes)

The agent waits for the X display before the first browser launch —
previously Chromium could start into a not-yet-existing display and die
with nothing to relaunch it.
A degraded launch is self-healing: on the first successful check-in
after launching without a session (network still coming up, grant
refused), the agent restarts the browser with a fresh grant instead of
waiting for a URL change. A degraded first launch also triggers an
immediate check-in rather than sleeping a full interval.
Dead-browser watchdog: every check-in cycle (even while offline) the
agent relaunches Chromium if its process has died — including browsers
that outlived an agent restart.
Stale Chromium SingletonLock files are removed before launch and the
user-data directory ownership is corrected, eliminating silent
fails-to-display after crashes.

Display & kiosk behavior

Screen orientation is applied with xrandr — at boot before the
browser launches (so the fullscreen window sizes itself to the rotated
geometry) and at runtime on change, followed by a browser restart. The
setting persists locally and survives offline reboots.
Remote commands: reload_browser performs a SIGHUP page reload;
restart_browser kills and relaunches Chromium with a fresh session.
Chromium now launches with kiosk printing enabled and media-stream
permission prompts auto-accepted.

Setup wizard

The wizard cannot complete without a saved configuration: cancelling
or failing any step returns to the previous menu or offers a restart, and
the .setup-complete marker is written only after the config is
confirmed and saved. DHCP and static-IP failures now offer
retry / go back / continue-anyway, matching the existing WiFi flow.
New kioskos-setup command re-runs the TUI wizard from any console,
VT, or SSH session and restarts the agent on success; the wizard prints
that recovery hint on any abnormal exit.

Security

/etc/kioskos/config.json is written 0600 with atomic replace — since
2.0.0 it holds a real credential that gates terminal APIs.
Single browser launcher: the legacy kioskos-browser.service +
start-browser.sh path is removed (it raced the agent, restarting old
browser instances the agent had just killed).

KioskOS OS (image & build system)

Installer & first boot

The GRUB "Install KioskOS" entry no longer runs the TUI setup wizard
or the agent inside the live installer session — configuration made there
landed in the tmpfs overlay and never propagated into the installed
system, and a registration attempt would have burned the one-time
enrollment code. Setup now runs on the installed system's first boot.
USB config preload (kioskos-preload): first boot searches a
KIOSKOS-CONFIG-labeled partition, removable media, and /boot for a
pre-provisioned kioskos-config.json, validates it, applies the network
settings, and skips the wizard — enabling zero-touch mass deployment.
The setup service no longer marks setup complete on its own
(ExecStartPost removed); completion is owned by the wizard itself.

Boot ordering & session

kioskos-agent.service now orders after network-online.target
(with NetworkManager-wait-online enabled), so the browser is not
launched against a dead network.
Mouse cursor auto-hides after 10 seconds of inactivity
(unclutter-xfixes), in kiosk mode only — the installer session keeps a
normal cursor.
The dead XFCE autostart browser entry and browser.env were removed from
the overlay; the agent is the single browser launcher.

Build system

GRUB packages switched to the -bin variants (grub-pc-bin,
grub-efi-amd64-bin, grub-efi-arm64-bin) to avoid postinst conflicts
inside the chroot build, for both amd64 and aarch64.
Intel/AMD CPU microcode included on amd64 images.
Added x11-xserver-utils (provides xset/xrandr) and
unclutter-xfixes to the image package set.
The overlay-shipped /etc/kioskos/config.json is locked to
root:root 0600 in the image.
Documentation (README, ARCHITECTURE.md) updated to match the real
boot flow and 2.0.0 security model.

Downloads

Source code (ZIP)
1 download
Source code (TAR.GZ)
1 download