Use AOS

AOS is an immutable Linux distribution for headless servers and edge systems. These guides are for developers installing, configuring, and operating AOS on their own machines.

AOS is an early preview. The public golden image is not published yet. First-boot storage provisioning, runtime host.nix activation, package profiles, and durable A/B image and configuration generations are present in the tree. They remain early-preview interfaces that must be qualified on the exact image and platform. Persistent state is ext4 by default, on partitions or on MD RAID arrays declared from host.nix, and sealed to the TPM on measured-boot images. xfs data volumes and the encrypted-ZFS bare-metal installer are opt-in at lower stability tiers (see filesystem support tiers). The checked-in verified-boot variants still use public test keys; production deployments must supply their own trust material.

#The operating model

Layer	How it is managed	Persistence
System image	Installed from the AOS golden image	Immutable root and UEFI image
First-boot storage	Literal host.nix supplied through metadata	Committed once; later changes are drift
Host configuration	Pure host.nix evaluation and authenticated package configuration	Numbered configuration generations under /var/lib/profiles/system
User packages	apm install, upgrade, remove, and rollback after account storage is provisioned	Per-user profile generations under /var/lib/profiles/per-user
Runtime system packages	apm install --system PACKAGE, upgrade --system, and remove --system	Machine-wide package generations under /var/lib/profiles/system
OS image	apm image install, upgrade, and rollback	A/B image generations under /var/lib/profiles/image

Three command names cover different jobs in the AOS toolchain:

Command	Use it for
apm	Consuming packages and switching configuration or image generations
apr	Creating, signing, and publishing package registries from a maintainer host
aos	Repository and AOS Hub tooling from a development or operations host

All three are independent programs backed by shared Rust libraries. aos has no package-management subcommand, apm cannot publish registries, and apr cannot install packages. Private activation and evaluation operations run through aos-package-runtime; that executable is reserved for AOS services and is not an operator CLI.

The base image installs apm, while AOS units reference the private runtime by an absolute store path. It does not put aos or apr on the image PATH. This keeps source construction, registry-authoring authority, package consumption, and on-host activation as distinct installed capabilities.

#Install and configure

• Install an image covers image formats, disk sizing, metadata transports, and deployment checks.
• Understand and operate host.nix covers first-boot policy, trust, storage, drift, and diagnostics.
• Configure an AOS host explains what host.nix and apm can change today and what still belongs to the release image.
• Configure networking covers DHCP, static addressing, DNS, diagnostics, and current advanced-networking limits.

#Operate the host

• Manage packages covers installing, upgrading, removing, and rolling back machine-wide and personal packages, plus optional package sets from a file.
• Configure package registries covers the built-in registry, other public and internal registries, priorities, credentials, and trust.
• Understand native package runtime policy explains how typed package requests become concrete host resources.
• Operate an AOS host covers services, logs, storage, packages, monitoring, and maintenance.
• Configure redundant and encrypted storage covers MD mirrors for /var and data volumes, TPM-sealed data volumes, and their mount units.
• Run ZFS storage covers the opt-in ZFS path: the memory budget, dataset declarations, pool lifecycle, and the metrics that move before a host runs into trouble.
• Upgrade and roll back a host covers the independent image and configuration generation axes, A/B boot counting, and failure semantics.
• Use Secure Boot and verify package trust follows the chain from firmware through the immutable root to signed package content.
• Control access covers accounts, SSH, privilege, and break-glass access.
• Harden an AOS host covers security presets, kernel policy, service isolation, and production qualification.
• Audit an AOS host covers audit policy, logs, evidence, and verification limits.
• Manage certificates and CA trust covers TLS identities, internal CAs, rotation, and compromise response.
• Manage secrets on AOS defines safe build-time and runtime handling, rotation, and incident response.
• Recover an AOS host covers first boot, activation, packages, disk pressure, Hub state, and reimaging decisions.
• Troubleshoot a host maps boot, provisioning, package, and generation failures to the relevant state and logs.
• AOS support status lists implemented and incomplete operational surfaces.

#Develop and maintain AOS

• Package an application for AOS follows a service from its derivation through image inclusion, registry publication, and upgrade.
• Inspect ability plans and retained execution covers offline checked graphs, private operator views, retained diagnostics, and realized artifact-consumption evidence.
• Package and service configuration is generated from each package's Nix interface and signed runtime contract. Use apm docs, apm options, the offline apm docs serve browser, or the package documentation workspace in AOS Hub. The generated reference covers nginx, Envoy, k3s and add-ons, registry services, containerd, databases and storage, identity services, network daemons, and KubeEdge without maintaining a second Markdown schema.
• Deploy AOS in production covers golden-image qualification, platform import, bare metal, and fleet promotion.
• Maintain the source tree covers Nix builds, image production, the repository CLI, and tests.
• Build and boot from source is the maintainer integration tutorial; it is not the normal installation path.

Registry producers should continue with Operate an AOS package registry. Hub operators should use the AOS Hub guide.

#Runtime abilities

Runtime abilities explains native package modules, mergeable operation contracts, composed handlers, and the build-to-runtime path. Use aos docs runtime to inspect generated references and deferred transactions. The guide marks the remaining consumer migration explicitly.