[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[NixOS](/kb/nixos/)Build a Firefox web kiosk USB drive with web_kiosk

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[NixOS](/kb/nixos/)13 articles

- [Overview](/kb/nixos/)
- [A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)
- [Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)
- [Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)
- [Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)
- [Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)
- [Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)
- [Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)
- [Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)
- [Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)
- [Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)
- [Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)
- [Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)
- [WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In NixOS: 13 articles

[Overview](/kb/nixos/)[A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)[Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)[Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)[Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)[Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)[Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)[Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)[Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)[Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)[Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)[Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)[Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)[WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

NixOSBuild a Firefox web kiosk USB drive with web_kiosk

Build a bootable NixOS image that opens Firefox in kiosk mode on one URL and joins your WiFi automatically, then write it to a USB drive.

UpdatedOct 5, 2026

Applies toNixOS unstable (nixos-unstable input)Nix with flakesx86_64 hardware

Tagsnixoskioskdevicesfirefox

Reading time9 min

On this page[What you get](#what-you-get)[Prerequisites](#prerequisites)[Configure the kiosk](#configure-the-kiosk)[Use the setup wizard](#use-the-setup-wizard)[Write the file by hand](#write-the-file-by-hand)[Build the image](#build-the-image)[Build without direnv](#build-without-direnv)[If your changes do not show up](#if-your-changes-do-not-show-up)[Write the image to a USB drive](#write-the-image-to-a-usb-drive)[Boot the kiosk](#boot-the-kiosk)[Update or change the kiosk](#update-or-change-the-kiosk)[Change the URL, time zone or WiFi](#change-the-url-time-zone-or-wifi)[Update Firefox and the base system](#update-firefox-and-the-base-system)[Change how the kiosk behaves](#change-how-the-kiosk-behaves)[Test the build](#test-the-build)[Troubleshoot](#troubleshoot)[The kiosk shows the wrong page or time zone](#the-kiosk-shows-the-wrong-page-or-time-zone)[The machine does not connect to WiFi](#the-machine-does-not-connect-to-wifi)[The machine does not boot from the drive](#the-machine-does-not-boot-from-the-drive)[The screen stays blank or the boot stalls](#the-screen-stays-blank-or-the-boot-stalls)[The build ignores your settings](#the-build-ignores-your-settings)[Known limitations](#known-limitations)[Related documents](#related-documents)

This document shows how to build the `web_kiosk` image, a small NixOS live system that boots straight into Firefox in kiosk mode on a URL you choose, with your WiFi credentials baked in. Use it when you need a dedicated single-page display (a dashboard, a sign-in screen, a status board) that starts itself when you plug in a USB drive and power on.

The project lives at [github.com/Avunu/web_kiosk](https://github.com/Avunu/web_kiosk) and is MIT licensed.

## What you get

The image is a hybrid ISO built from a Nix flake. When it boots, it does the following:

Starts cage, a single-application Wayland compositor, as a user named `kiosk`.

Runs `firefox -kiosk <START_PAGE>` inside cage, so Firefox fills the screen with no tabs or address bar.

Joins the WiFi network you configured, if any.

Sets the time zone and turns the screen brightness to 100%.

The system runs live from the USB drive and is not installed anywhere. There is no login prompt, no SSH, no `sudo`, and no firewall. The sections below explain what that means for how you use it.

## Prerequisites

The flake builds the image for the system it runs on, and the kiosk only supports x86_64, so build it on an x86_64 Linux machine. You need:

The [Nix package manager](https://nixos.org/download.html) with flakes enabled (the `nix-command` and `flakes` experimental features).

[direnv](https://direnv.net/), if you want to use the project's development shell (recommended). The shell provides the `build` and `setup` helper commands and loads your `.env` file.

Git, to clone the repository.

A USB drive. The finished image is roughly 1.6 GB, so use a drive of at least 2 GB.

A target computer with x86_64 hardware. The project does not support other architectures.

Note

The flake declares a binary cache for devenv in its `nixConfig`. Depending on your Nix configuration, Nix may ask you to confirm that setting the first time you build.

## Configure the kiosk

Clone the repository and move into it:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">git</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">clone</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">https://github.com/Avunu/web_kiosk.git</span>
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">cd</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">web_kiosk</span>
```

The build reads four environment variables. The simplest way to set them is a `.env` file in the project root.

| Variable        | Meaning                   | Default when empty       |
| --------------- | ------------------------- | ------------------------ |
| `START_PAGE`    | The URL Firefox opens.    | `https://www.google.com` |
| `TIME_ZONE`     | An IANA time zone name.   | `America/New_York`       |
| `WIFI_SSID`     | The network name to join. | WiFi is disabled         |
| `WIFI_PASSWORD` | The WiFi passphrase.      | Not used                 |

### Use the setup wizard

Inside the development shell, the `setup` command asks for each value and writes `.env` for you. It also offers to start the build when it finishes. Run it after the shell is active (see the next section), or skip ahead and write the file by hand.

### Write the file by hand

Create `.env` in the project root:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">START_PAGE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=https://example.com/dashboard</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">TIME_ZONE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=America/New_York</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">WIFI_SSID</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=<WIFI_SSID></span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">WIFI_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=<WIFI_PASSWORD></span>
```

The repository includes `.env.example` with the same four keys. You can copy it as a starting point.

To see valid time zone names, run this on any systemd-based Linux machine:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">timedatectl</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">list-timezones</span>
```

To build an image with no WiFi, leave both WiFi values empty. The README says this disables WiFi; Avunu has not verified how the image behaves on wired Ethernet, since the flake only turns on `systemd-networkd` and does not set up a wired connection explicitly:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">WIFI_SSID</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">WIFI_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">=</span>
```

Warning

Your WiFi passphrase is written into the image in plain text. Anyone who has the ISO or the USB drive can recover it. Use a dedicated network or guest SSID for kiosks, never your main network, and treat the image like a credential. The `.env` file and the `result` link are listed in `.gitignore` so they stay out of Git, but keep them out of backups and shared folders too.

## Build the image

Enter the development shell. The project's `.envrc` loads `.env` and the flake shell:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">allow</span>
```

Build the image with the helper command:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">build</span>
```

The `build` command runs `nix build --impure`. The `--impure` flag is required because the flake reads your settings from environment variables at evaluation time.

When the build finishes, the image is at `result/iso/kiosk.iso`:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">ls</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-lh</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">result/iso/</span>
```

If you run the `setup` command from the shell, it writes `.env`, asks whether to build, and runs `direnv reload` followed by `nix build --impure` for you.

### Build without direnv

You do not need direnv. The flake reads plain environment variables, so you can pass them on the command line:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">START_PAGE</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">https://example.com/dashboard</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> TIME_ZONE</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">America/New_York</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> WIFI_SSID</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=<</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">WIFI_SSID</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> WIFI_PASSWORD</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=<</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">WIFI_PASSWORD</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">build</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--impure</span>
```

### If your changes do not show up

Changing `.env` does not rebuild anything on its own. If the new image still has old values, reload the shell so the variables are re-read, then build again:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">reload</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">build</span>
```

## Write the image to a USB drive

The ISO is built to be bootable from USB, and the project supports both UEFI and legacy BIOS boot. The repository itself only says to burn the ISO to a USB drive, so the commands below are the standard Linux method rather than something the project provides.

Plug in the drive and identify it by size:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">lsblk</span>
```

Write the image to the whole device (for example `/dev/sdX`, not a partition such as `/dev/sdX1`):

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">sudo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">dd</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">if=result/iso/kiosk.iso</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">of=/dev/</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">USB_DEVIC</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">bs=4M</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">status=progress</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">conv=fsync</span>
```

Flush buffers before you unplug:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">sync</span>
```

Warning

`dd` overwrites the target device without asking. If you pick the wrong device you will destroy its contents. Check the device name against `lsblk` twice.

On macOS or Windows, use any tool that writes a raw image to a disk. Graphical tools such as balenaEtcher work for hybrid ISOs like this one.

## Boot the kiosk

Plug the drive into the target computer and power it on.

Open the firmware boot menu (the key varies by manufacturer) and choose the USB drive.

If a boot menu appears, let it time out. The project's boot test relies on the default entry starting automatically after a short countdown (about ten seconds in its BIOS boot configuration).

The system then starts `cage-tty1.service`, which launches Firefox on your start page. If WiFi is configured, the machine joins the network without any input.

Things to know about how it behaves:

**No persistence.** Nothing you do in the browser survives a reboot. Every power cycle starts from the image as built.

**No login.** The login program on the console is replaced so you cannot sign in from a keyboard. The `kiosk` user is not in the `wheel` group and `sudo` is disabled.

**No remote access.** SSH is disabled. If you need to reach the machine after deployment, this image is the wrong tool.

**Firewall off.** The image does not run a firewall. SSH is disabled, but keep the kiosk on a network you trust.

**No sound.** PipeWire and PulseAudio are disabled.

**Physical access still matters.** Kiosk mode limits the browser UI. The project does not claim to lock down attached keyboards or mice, so secure the machine physically if that matters.

## Update or change the kiosk

The image is static. It does not update itself, and there is no way to change the start page or WiFi settings on a running kiosk. To change anything, rebuild and rewrite the drive.

### Change the URL, time zone or WiFi

Edit `.env` (or run `setup` again).

Run `direnv reload`, then `build`.

Write the new ISO to the drive as above.

### Update Firefox and the base system

The flake pins its inputs (`nixpkgs` on the `nixos-unstable` branch, `devenv` and `flake-parts`) in `flake.lock`. To pick up newer software, update the lock file, rebuild, and reflash:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">flake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">update</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">build</span>
```

### Change how the kiosk behaves

Kiosk behavior lives in `modules/kiosk.nix`. It exposes two options, `kiosk.startPage` and `kiosk.timeZone`, and also defines the Firefox command line, the `kiosk` user, the disabled services and the brightness service. Image settings (boot modules, compression, volume label, WiFi and firewall) live in `flake.nix`.

For example, the Firefox command is set here:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">services</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">cage</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">program</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">${</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">firefox</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">}</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/bin/firefox -kiosk </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">${</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">config</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">kiosk</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">startPage</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">}</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">user</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"kiosk"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">;</span>
```

Edit that line to add Firefox flags, then rebuild.

## Test the build

The flake defines two checks that run NixOS virtual machine tests:

`kiosk` boots the kiosk module in a VM and confirms that `cage-tty1.service` is active, that Firefox is running, that the `kiosk` user exists outside the `wheel` group, and that the `sudo` wrapper is absent.

`kiosk-iso-boot` attaches the built ISO to a VM as a CD-ROM and waits for the console to report that `cage-tty1.service` started.

Both checks are available on Linux. They are useful when you change the module and want to know it still boots before you touch real hardware.

## Troubleshoot

### The kiosk shows the wrong page or time zone

The image was built with different values than you expected. Confirm what is in `.env`, run `direnv reload`, rebuild, and reflash. If a variable is empty, the defaults in the table above apply.

### The machine does not connect to WiFi

Check `WIFI_SSID` and `WIFI_PASSWORD` for typos. If the SSID is empty, WiFi is not configured at all.

The image includes redistributable firmware, but Avunu has not verified support for any particular WiFi adapter. If one does not work, test the same image on different hardware.

Rebuild after any change. The credentials cannot be edited on the drive.

### The machine does not boot from the drive

Pick the USB drive explicitly in the firmware boot menu.

Confirm you wrote the ISO to the whole device and not to a partition, and that `dd` finished without errors.

Check that the hardware is x86_64.

### The screen stays blank or the boot stalls

You cannot log in to inspect a running kiosk, but the kernel is configured to log to the first serial port (`console=ttyS0,115200n8`). If the machine has a serial port, or you are testing in a VM, you can read boot messages there. A healthy boot reports that `cage-tty1.service` started.

### The build ignores your settings

Make sure you pass `--impure`. A plain `nix build` cannot read your environment variables during evaluation, so your settings are ignored and the defaults are used. Use the `build` helper or run `nix build --impure` yourself.

## Known limitations

These are the project's own stated caveats:

x86_64 hardware only.

The image is static and non-upgradable. Updates mean rebuilding and reflashing.

The ISO is about 1.6 GB, larger than the job strictly needs.

Pull requests that address these are welcome on the [project repository](https://github.com/Avunu/web_kiosk).

## Related documents

[A NixOS Micro Desktop for Family and Friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/), for a NixOS desktop that installs to disk and keeps itself updated, in contrast to this static live image.

[Why Nix for Business Systems](/kb/nixos/why-nix-for-business-systems/), for the wider case for building devices and servers declaratively.

Sources

- [github.com/Avunu/web_kiosk](https://github.com/Avunu/web_kiosk)
- [nixos.org/download.html](https://nixos.org/download.html)
- [direnv.net](https://direnv.net/)

Need help with NixOS?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousAdd OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)[Next →Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [What you get](#what-you-get)
- [Prerequisites](#prerequisites)
- [Configure the kiosk](#configure-the-kiosk)
- [Use the setup wizard](#use-the-setup-wizard)
- [Write the file by hand](#write-the-file-by-hand)
- [Build the image](#build-the-image)
- [Build without direnv](#build-without-direnv)
- [If your changes do not show up](#if-your-changes-do-not-show-up)
- [Write the image to a USB drive](#write-the-image-to-a-usb-drive)
- [Boot the kiosk](#boot-the-kiosk)
- [Update or change the kiosk](#update-or-change-the-kiosk)
- [Change the URL, time zone or WiFi](#change-the-url-time-zone-or-wifi)
- [Update Firefox and the base system](#update-firefox-and-the-base-system)
- [Change how the kiosk behaves](#change-how-the-kiosk-behaves)
- [Test the build](#test-the-build)
- [Troubleshoot](#troubleshoot)
- [The kiosk shows the wrong page or time zone](#the-kiosk-shows-the-wrong-page-or-time-zone)
- [The machine does not connect to WiFi](#the-machine-does-not-connect-to-wifi)
- [The machine does not boot from the drive](#the-machine-does-not-boot-from-the-drive)
- [The screen stays blank or the boot stalls](#the-screen-stays-blank-or-the-boot-stalls)
- [The build ignores your settings](#the-build-ignores-your-settings)
- [Known limitations](#known-limitations)
- [Related documents](#related-documents)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
