AOS / Docs

AOS // ANDYL OS

[Status: early preview] [License: multi-license]

AOS is an immutable Linux distribution for headless servers and edge systems. Its bootstrap toolchain, userspace, packages, system images, and tests are built from source in this repository without nixpkgs dependencies.

#Get started

  1. Install the AOS image on a machine or import it into a hypervisor.
  2. Configure the host with first-boot host.nix policy.
  3. Install and manage packages with apm.
  4. Operate the host, apply upgrades, and use the recovery guide when needed.

Check the support-status matrix before planning a deployment.

#Projects

  • AOS is the operating system, package manager, and host operating model.
  • AOS Hub hosts package registries and binary caches. It runs as a native service or as a Cloudflare Worker and exposes a web console, HTTP API, and the registry and cache protocols used by apr, apm, Git, and Nix. It is also the planned distribution point for AOS system images.
  • Crucible provides deterministic state-space exploration and debugging for unmodified QEMU guests.

#Documentation

#Contributing

Bug reports and feature proposals are welcome in GitHub Issues. Report undisclosed vulnerabilities privately under the security policy. External contributions are currently disabled, and only project contributors may open pull requests. Before changing packages, images, or build tooling, read the contribution requirements and maintainer guide. The contribution requirements document the employee authorization, external CLA, DCO, and license-boundary checks that apply before a change is merged. AOS is built hermetically from source; new dependencies must be added to the AOS package graph rather than imported from nixpkgs.

Load the development shell through direnv or nix develop --accept-flake-config. It puts aos-dev and the ordinary packaged aos CLI in PATH:

aos --help
aos-dev run apm --help
aos-dev run apr --help
aos-dev cache init
aos-dev build package crucible --no-out-link

Tool-running commands fetch or build ordinary packaged binaries on demand. Explicit development builds use shared compiler caches. The shell and script use the production testing binary cache with signature verification and source fallback; an empty cache still permits source builds. See the development instructions for cache setup and incremental Rust builds.

Development VM and kernel-boot fleet tests materialize large images into the local images cache, retaining only small, closure-pinning recipes in the Nix store. Each launch verifies the base and creates a private reflink or sparse copy. Assembly scratch and the cache both require disk-backed storage; only completed images enter shared publication staging. Changing assertions reuses the base; changing closures, tools, assembly, layout, or baked configuration selects another base. Missing or corrupt bases rebuild automatically. Image boot/integrity fixtures and interactive fleet launchers keep ordinary immutable images.

aos-dev cache images status
aos-dev cache images prune --days 7 --max-gib 50
aos-dev --no-image-cache build check fleet.vm-artifact-reuse --no-out-link

Images use $AOS_DEV_CACHE_DIR/images on disk-backed storage, mounted at /aos-build-cache/images by default (AOS_DEV_IMAGE_CACHE_DIR selects the sandbox path). Automatic maintenance retains at most 100 GiB of allocated idle bases for 14 days, oldest use first; active leases can temporarily exceed the bound. Pruning skips active assembly/copy operations, reclaims abandoned staging, and keeps lock files. It never removes source closures or private run disks. Builders must trust cache writers: the local integrity manifest detects incomplete or corrupt entries, but cannot authenticate a writer able to replace both images and manifests. For qualification, --release and --no-cache select ordinary derivations and bypass it even alongside enabling cache flags. Existing realized test results still follow Nix reuse; changing assertions or explicitly rerunning a check is necessary to execute its VMs again.

Shared ext4 root builders, headless assertion volumes, and fleet GPT assembly normalize staged timestamps and ownership and derive filesystem UUIDs, directory hash seeds, and partition GUIDs from content and partition roles. Independent cold ordinary builds and runtime recipe reconstructions are compared byte for byte by aos-dev --release build check build.image-reproducibility --no-out-link, including ext4 shrink/grow and the shared EROFS root builder. Normalization preserves modes, symlinks, extended attributes, and deliberate staging hardlinks without modifying store inputs. Nix input copies discard hardlinks introduced by store optimization, which NAR does not encode. Different payloads receive different filesystem UUIDs; identical image clones retain their UUID and should not be mounted together by UUID. This guarantee does not cover the separate production ESP/GPT assembly or guest runtime provisioning, which continues to allocate fresh machine identities.

Rust code uses one Cargo workspace under crates/, grouped into shared libraries, AOS subsystems, Hub, and Crucible. See the workspace organization and crate inventory for package ownership and reusable boundaries. The rename and extraction reference maps every former crate to its current name and location, including merges and new shared libraries.

#Project status

AOS is under active development. Interfaces and disk formats may change before the first stable release. Public installation images, a production external-signing workflow, durable kernel updates, and complete runtime host.nix activation are not available yet.

#License

Original AOS code is generally licensed under the Apache License 2.0. The repository and its distributions also contain separately licensed components, including QEMU and its Crucible integration. GitHub's Apache-2.0 label describes that default; it does not describe every component in this multi-license repository. The licensing guide points to the authoritative component map, contribution agreement, and complete license texts.