EmberRTOS Headless
EmberRTOS Headless is the general-purpose edition of EmberRTOS, Fireball Industries' own Linux distribution for the EmberNet edge. It runs the general-purpose kernel and is the right choice for the majority of edge nodes: container hosts, protocol gateways, telemetry collectors, and anything that does not have a hard real-time deadline. For workloads that must hit a deadline, use EmberRTOS Headless RT instead. Everything on this page applies to every edition, the Desktop included.
Headless has no real-time kernel, no tuning, and no Real-time screen in the setup app. That is the
only difference from Headless RT, and it makes Headless the smaller install. It comes as an install ISO
for x86_64 industrial PCs and as a flashable image for the Raspberry Pi 4 and 5. A booted Headless box
reports its edition in /etc/os-release:
grep -E '^(NAME|VERSION|VARIANT)=' /etc/os-release
# NAME="EmberRTOS"
# VERSION="0.1.11"
# VARIANT="Headless"

The immutable foundation
EmberRTOS is an immutable operating system. The root filesystem is mounted read-only, and
the running system cannot be changed in place. This is what keeps a fleet of edge devices identical
and predictable: there is no configuration drift, no half-applied update, and no "works on that one
box" mystery state. /etc stays writable, so node configuration persists across reboots.
Changes are made transactionally. Instead of modifying the live system, EmberRTOS creates a new filesystem snapshot, applies the change there, and switches to it on the next reboot. Every update is therefore atomic (all-or-nothing) and reversible.
Updating the system
Package and system changes go through transactional-update, which prepares a new snapshot without
touching the running system:
# Install a package into the next snapshot
sudo transactional-update pkg install <package>
# Apply all available updates into a new snapshot
sudo transactional-update up
# Open a shell in the new snapshot to make several changes at once
sudo transactional-update shell
None of these affect the running system until you reboot into the new snapshot. In normal operation you do not run these by hand. EmberRTOS stages its own updates every day (see below).
Automatic updates, and the restart you plan
A daily timer runs transactional-update cleanup dup. It writes the available updates into a new
snapshot and stops: the running system is not touched and the box does not restart. The update takes
effect at the next restart a person plans, when you decide the line can stop:
sudo emberrtos-update status # the running snapshot, and "An update is waiting for a restart" when one is
sudo emberrtos-update check # what an update would change
sudo emberrtos-update apply # stage an update now, without waiting for the timer
sudo systemctl reboot # the restart that makes it take effect
There is no reboot manager on an EmberRTOS box (its service is masked) and no maintenance window: nothing schedules a restart for you. A fleet stays current because every box stages the same updates daily, and you choose when each one restarts.
These releases enable the distribution's reboot manager, which restarts the box after an update inside
a window that opens at 03:30 and runs for ninety minutes. Update them to the current release. Until
then, write REBOOT_METHOD=none into /etc/transactional-update.conf, and the box stages updates
without restarting. Keep the reboot manager running: on 0.1.5, stopping it restarts the box as soon as
the update service finishes.
The EmberNet endpoint and the Plasma firewall update themselves from the stable channel, separately from the operating system.
Rollback
Because every change is a snapshot, recovering from a bad update is a rollback, not a repair:
# List snapshots
sudo snapper list
# Roll back to the previous (or a specific) snapshot, then reboot
sudo transactional-update rollback <number>
If a staged update fails to boot, EmberRTOS returns to the last known-good snapshot automatically.
First-boot configuration
On the node image, the normal way to bring a box up is the full-screen setup app: network ports, EmberNet enrollment, and the cluster, from the screen on the machine.
For automation, EmberRTOS can also be provisioned on its first boot from a configuration
medium: a disk, USB stick, or config drive whose filesystem is labeled combustion. The system
reads a /combustion/script from it and runs that script inside a transactional shell before the
node comes up for real.
A minimal first-boot script looks like this:
#!/bin/bash
# combustion: network
# set the hostname, add an SSH key, install packages, enable services, and so on.
echo "emberrtos-node" > /etc/hostname
install -d -m 0700 /root/.ssh
echo "<your public key>" > /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
The # combustion: network line brings up networking (DHCP by default) so the script can pull
packages. This is how a stock image becomes a configured EmberRTOS node on first power-on, with
no rip-and-replace and no manual install steps.
What's included
EmberRTOS ships a deliberately minimal host with the pieces edge operation needs:
- A container runtime, so EmberNet workloads run as containers on top of the immutable host.
- The cluster service, already on the host with everything it needs on the disk.
- SSH for administration over the network.
- Time synchronization, which is critical for correlated telemetry and for certificates.
- A hardware watchdog, on machines whose firmware exposes one. The Raspberry Pi image does not arm it.
- A maintenance login and a keyed install, for getting a box into EmberNet with a key instead of by hand.
- A signed update service, so a box only ever updates the packages it has. A Headless box never sees the real-time kernel or the desktop shell.
Security posture
- Read-only root eliminates a large class of runtime tampering and persistence techniques.
- The setup app answers only on the machine's own loopback address, so nothing on the network can change a box through it.
- EmberNet's zero-trust networking removes the need for exposed management ports.
- Every OS change is an auditable, reversible snapshot.
- Docker is not installed and cannot be added.
Headless or Headless RT: which do I deploy?
Choose EmberRTOS Headless unless the node runs a workload with a hard timing requirement. Choose EmberRTOS Headless RT when the node performs motion control, high-rate deterministic I/O, or any control loop that must respond within a bounded worst-case time. Both are the same OS with the same operations model; only the kernel and its tuning differ. Choose EmberRTOS Desktop when a person works at the machine.
Next steps
- EmberRTOS Headless RT: the real-time edition, how to switch it, and how to check it
- EmberRTOS on the Raspberry Pi: the Pi 4 and Pi 5 images
- First boot and the setup app: bring a node up from its own screen
- System Requirements: hardware and sizing
- Installation Guide: provisioning a node