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

  • AOS user documentation covers installation, configuration, packages, security, upgrades, operations, and recovery.
  • AOS Hub documentation covers its trust model, web, API, CLI, native, and Cloudflare deployments.
  • Registry release stages explains unpublished candidate uploads and revision checks. Registry maintainers use apr release; AOS qualification and destination orchestration use aos maintain release.
  • Registry operator documentation covers hosting, signing, publishing, staged rollouts, and incident response.
  • Crucible documentation covers deterministic exploration, reproduction, debugging, and CI.
  • Maintainer documentation covers source builds, trust and package security, image production, repository development, and tests.

#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.

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.