AOS Hub / Docs

Maintain AOS

Start every release with the release checklist. It gives the order of operations, manual checks, and conditions for proceeding. The command reference and qualification specification provide supporting detail for experimental and production.

This section is for people changing the AOS source tree, package graph, system modules, release images, or Rust tools. Installing and operating a published AOS image should not require any of these workflows.

Before reviewing or merging a contribution, follow the contributor-authorization policy. It distinguishes Andyl employee contributions covered by the company CIAA from external contributions that require the project agreement, and defines the fail-closed records and identity checks maintainers must preserve.

Apply the code style guide to new and modified Rust and Nix code. It covers Rust APIs and implementation, Dendritic Nix modules, package expressions, comments, tests, and embedded shell.

Crucible gate evidence distinguishes component tests from live QEMU evidence and explains the fingerprint gate dependencies.

#Build the source tree

AOS builds hermetically from its bootstrap tools and AOS packages. It does not import nixpkgs. The short image commands below require an x86_64-linux caller. From another system, use an x86 Linux remote builder and select the Linux package output explicitly.

Build the golden server image in the format needed by a release pipeline:

nix build .#server-image-raw
nix build .#server-image-qcow2

From a non-x86 host with an x86 Linux builder:

nix build .#packages.x86_64-linux.server-image-qcow2

Build an individual package through its pkg- output:

nix build .#pkg-zlib

The source-build server tutorial exercises a custom image, first-boot metadata, AOS-built QEMU, and UEFI firmware. It is a maintainer and integration workflow, not the normal installation path.

Build and customize release images covers system variants, release policy, output formats, and image validation.

Deploy the hosted AOS Hub covers manual deployment with the packaged Wrangler and Cloudflare OAuth, isolated staging and production configuration, validation, promotion, and rollback.

Operate hosted registries defines the main/experimental trust and lifecycle split and links the per-registry runbooks. Back up and recover the hosted Hub covers HubDb PITR, R2, disposable shard state, release evidence, restore, and approved experimental-registry rebuilds.

Registry key management distinguishes experimental's HSM status from main's intended signing custody, provider integration, rotation, and recovery policy.

Plan and verify canonical releases documents the fail-closed release-selected target matrix, source and authorization preconditions, and offline bundle verification. It also identifies which RFC-0017 publication phases are not yet authorized for production use.

Maintain the AOS trust model defines the chain from source and release authorization through verified boot, image-baked anchors, signed registries, store realizations, and runtime measurements.

Review package security defines the maintainer's role in package build isolation, declared privileges, generated service confinement, host effects, and security regression testing.

#Use the repository CLI

Run the packaged repository command through the flake:

nix run . -- describe
nix run . -- show zlib
nix run . -- test eval

For incremental Rust work, build in the development environment and run the binary directly:

nix develop -c just cli-build
crates/target/release/aos --help

The just recipes use that release binary. Set AOS_BIN to an equivalent binary when the target directory lives elsewhere, for example on a constrained CI or agent filesystem.

The development environment supplies the AOS-built dependencies and embeds the required OpenSSL runtime path. Build and invoke the independent aos, apm, or apr program for the surface under test. On-host service commands belong to the private aos-package-runtime binary.

For direct incremental Cargo builds, use the lean shell so the build does not pull in integration-test services or the packaged CLI:

nix develop --file cargo-shell.nix -c cargo build --manifest-path crates/Cargo.toml --bin aos
crates/target/debug/aos --help

#Run checks

Start with the core evaluation and formatting checks:

crates/target/debug/aos test eval core
crates/target/debug/aos fmt --check
crates/target/debug/aos test eval

aos test eval runs the focused pure evaluation suites, including module-ABI, runtime-role, registry-policy, storage-profile, and config-provenance checks. It reports each suite's progress and uses at most two Nix evaluators. Use aos test eval <suite> to run one suite while iterating. The core suite builds checks.eval for a quick local pass. The CLI stops any individual eval suite after two minutes and reports which suite exceeded the limit.

Checks that run an executable or inspect rendered artifacts are under checks.build, including config evaluation, config materialization, the Darling harness, rendered-system checks, and discovered system variants. Flake checks include both groups.

VM and fleet checks require a Linux builder with KVM. Package, module, image, and CLI changes should run the narrowest relevant build or test in addition to the evaluation checks.

#Repository map

Path	Contents
`stdenv/` and `pkgs/`	Bootstrap chain, toolchain, and package graph
`lib/`, `modules/`, and `systems/`	Module framework and image variants
`crates/`	AOS tools, registry services, and Crucible
`tests/`	Evaluation, build, VM, fleet, and integration coverage

Application packages have a separate authoring guide. Registry producers and release automation should continue with the registry operator documentation.

#Runtime ability infrastructure

The runtime abilities guide explains module composition, generated package artifacts, and deferred execution. The native infrastructure contract identifies implemented entry points and limits; the consumer migration handoff tracks publication, APM, boot/image, and indexed-documentation integrations still to be moved. Infrastructure checks alone do not qualify existing OS consumers.