atomloops

module

v0.1.0 Latest Latest Go to latest Published: Jul 17, 2026 License: GPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mirkobrombin/atomloops

Links

Open Source Insights

README ¶

Atom Loops

Atom Loops is an open source system for atomic and reproducible deployment of the operating system on embedded and desktop Linux devices. An update is one transaction: download, verify, switch, with automatic rollback on boot failure.

It is not a Linux distribution and not a package manager. It consumes a finished system image and owns only the deploy and rollback lifecycle. It needs no container engine, no registry, and no dedicated partition layout beyond an ESP.

Status

Under active development, not ready for production.

The first integration target is Sinty OS, which is where the code is currently exercised end to end. Only x86_64 (UEFI) is validated so far. The roadmap below states what is implemented and what is not.

The proof of concept this project grew from is kept at the poc tag: loopback boot of a distribution image, plus mocks for the build and deploy infrastructure.

Roadmap

Milestone	Scope	Status
M1	Core engine: initramfs, WAL, atomic switch, dm-verity	Largely done
M2	OTA daemon: download, cryptographic verification, deploy	Partial. Manifest verification, revocation and staging work. Zsync delta download is not implemented, artifacts download in full
M3	Secure Boot and kernelcache: UKI and FIT	Partial. UKI only. FIT/U-Boot and `atom-enroll` not started
M4	Hardware anti-rollback: TPM 2.0 and RPMB	Partial. Not validated against TPM or RPMB hardware
M5	Recovery mode	Partial. The recovery agent lives in its own repository. The independent recovery image is not proven
M6	Testing across the target hardware fleet	Not started. x86_64 only
M7	CLI, documentation and public release	Partial. Release runbook only. No integration guide, no reproducible build environment

Requirements

Go >= 1.22 (daemon + release tools)
Zig 0.16 (the UEFI loader, loader/)

Build

go build ./...             # atomd (daemon) + atom-sign (release tool)
cd loader && sh build.sh   # BOOTX64.EFI (needs zig 0.16)

Components

internal/deployment - the deployment.json WAL (single source of truth).
internal/otad + cmd/atomd - the daemon: boot confirmation, staging, anti-rollback, recovery.
internal/trust + internal/signing + cmd/atom-sign - the two-level key chain (root cert, signing key, manifest) and the release tooling.
scripts/boot/initramfs-main.go - the early-boot engine: dm-verity setup and the atomic switch before switch_root.
loader/ - the Zig UEFI loader: boot-slot selection and signature verification before chainloading the kernelcache.

Security model

Two-level keys: a cold ROOT key signs a short-lived signing certificate and a revocation list; the operational SIGNING key signs update manifests. The daemon checks revocation first, then the cert against the root, then the manifest against the signing key, then the artifacts by SHA256. See docs/RELEASE-RUNBOOK.md.

Relationship to sinit

Atom Loops does not replace the init. The running-system half (atomd) confirms or rolls back the boot; sinit is PID 1.

License

GPL-3.0 - see LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
atom Package atom is the public API surface of Atom Loops that external consumers build on (for example the Sinty recovery image): the signed staging and verification pipeline, the deployment WAL, and slot promotion and rollback.	Package atom is the public API surface of Atom Loops that external consumers build on (for example the Sinty recovery image): the signed staging and verification pipeline, the deployment WAL, and slot promotion and rollback.
cmd
atom-sign command Command atom-sign is the release-side signing tool for Atom Loops updates.	Command atom-sign is the release-side signing tool for Atom Loops updates.
atomd command Command atomd is the Atom Loops OTA daemon: the running-system half of the deployment.json WAL protocol.	Command atomd is the Atom Loops OTA daemon: the running-system half of the deployment.json WAL protocol.
sinty-diag command Command sinty-diag collects a failure bundle and emits a compact, QR-ready report.	Command sinty-diag collects a failure bundle and emits a compact, QR-ready report.
updated command Command updated is the Sinty OS update agent.	Command updated is the Sinty OS update agent.
internal
audit Package audit is the OTA daemon's append-only update history: one JSON line per transition (stage, boot-success/promote, rollback, recovery), so a fleet operator can see what a device did and when, and recovery mode can show it.	Package audit is the OTA daemon's append-only update history: one JSON line per transition (stage, boot-success/promote, rollback, recovery), so a fleet operator can see what a device did and when, and recovery mode can show it.
deployment Package deployment models deployment.json, the Atom Loops write-ahead log (WAL) that records the atomic-update state of a device: which rootfs and kernelcache are current, which is a pending candidate, which is the last known good, and the counters that drive automatic rollback and stabilization.	Package deployment models deployment.json, the Atom Loops write-ahead log (WAL) that records the atomic-update state of a device: which rootfs and kernelcache are current, which is a pending candidate, which is the last known good, and the counters that drive automatic rollback and stabilization.
diag Package diag collects a diagnostic bundle when a boot or install fails and distills it into a compact report small enough to hand to a QR renderer.	Package diag collects a diagnostic bundle when a boot or install fails and distills it into a compact report small enough to hand to a QR renderer.
otad Package otad is the Atom Loops OTA daemon: the running-system half of the deployment.json WAL protocol.	Package otad is the Atom Loops OTA daemon: the running-system half of the deployment.json WAL protocol.
recovery Package recovery is the Atom Loops recovery-mode API.	Package recovery is the Atom Loops recovery-mode API.
signing Package signing is the release-side counterpart to the daemon's trust checks: it produces the Ed25519 keypair and the detached manifest signatures that otad.Stage (and the loader) verify.	Package signing is the release-side counterpart to the daemon's trust checks: it produces the Ed25519 keypair and the detached manifest signatures that otad.Stage (and the loader) verify.
trust Package trust is the two-level key chain (A4.1): a cold ROOT key signs the operational SIGNING key's cert and a revocation list; the SIGNING key signs manifests.	Package trust is the two-level key chain (A4.1): a cold ROOT key signs the operational SIGNING key's cert and a revocation list; the SIGNING key signs manifests.
scripts
boot command initramfs-main is the initramfs init for the AtomLoops STANDALONE build path (scripts/build/fetch-release.sh -> scripts/boot/initramfs-build.sh -> build-kernelcache.sh), used to build and test the OTA kernelcache on its own.	initramfs-main is the initramfs init for the AtomLoops STANDALONE build path (scripts/build/fetch-release.sh -> scripts/boot/initramfs-build.sh -> build-kernelcache.sh), used to build and test the OTA kernelcache on its own.
deploy command