AOS Community Edition: the agent operating system you can inspect

The problem AOS Community Edition solves

Most agent frameworks give you a library and leave the runtime to you. AOS Community Edition makes the opposite bet: it ships an operating system surface for agents, with a CLI, an HTTP API, a capsule model and a distribution manifest, all owned by one repository. The README describes it as "the open agent operating system for people who want an inspectable, composable environment for agents." That framing matters, because it tells you who the project is for. It is for engineers who need to see what an agent is doing at the process and filesystem level, not just at the prompt level.

The repository layout reflects that ambition. crates/ holds the product CLI, the HTTP API, a control client and shared product code. capsules/ holds first-party production capsules. distros/ holds Community distribution manifests and release metadata. docs/ holds product and operator documentation. The Cargo.toml workspace lists 30 members, of which 22 are capsules, matching the README's claim that the installer ships "the exact 22 Community Edition capsules built from this source tree."

Who is this not for? Anyone who wants a drop-in Python agent loop with a dozen lines of glue. AOS expects you to think in terms of capsules, principals, distributions and a product-owned root at ~/.aos. That is a real conceptual cost, and the README does not pretend otherwise.

Capsules, principals and the aos command boundary

The core mechanism is the capsule. Capsules are described in the README as "general user-space building blocks: users can compose them into harnesses, meta-harnesses, connectors, services, or other systems." The Cargo.toml workspace confirms the shape of this: capsule-fs, capsule-http, capsule-memory, capsule-mcp, capsule-openai, capsule-router, capsule-session, capsule-shell, capsule-skills, capsule-forge and others sit side by side as workspace members. Each is a Rust crate, so the boundary between capsules is a compile-time and process boundary rather than a convention.

The second mechanism is the command boundary. AOS owns its product roots: init, status, migrate, update, distro, mcp, daemon and serve-health. Every other runtime root is part of the AOS CLI directly, and the README is explicit that "there is no nested aos astrid or aos runtime namespace." When AOS owns a root such as status or init, its product implementation replaces the lower-level command at that same location, so the supported surface stays aos <verb>.

The third mechanism is the principal. Provisioning another principal keeps the authenticated operator separate from the target environment:

aos --principal operator init --target-principal alice

That separation is the part of the design most likely to matter in a shared or multi-tenant setup, and it is the part the README covers in the fewest words.

Release validation ties the two together: it compares the exact pinned runtime's public command inventory with AOS's classified root contract, so a new runtime verb cannot enter a product release without an explicit inherit-or-own decision. That is a governance mechanism, not a marketing claim, and it is the most interesting thing in the README.

Installing AOS Community Edition and running a first status check

The supported installer is a shell script served from aos.unicity.ai. It installs the aos product command, its pinned runtime, and the 22 Community Edition capsules under the product-owned ~/.aos root.

curl --proto '=https' --tlsv1.2 -fsSL https://aos.unicity.ai/install.sh | sh
aos init

After the installer returns, aos init provisions from local, product-versioned capsule assets. The README states that a fresh Community installation automatically resumes Astrid's ten-capsule batches after each rate-limit window, and that installing all 22 capsules includes approximately two minutes of waiting. Completed installs are not repeated. A stalled batch remains an error rather than being silently retried forever, which is the behaviour you want if you are scripting this.

There is also an offline path. The README mentions aos init --offline, which provisions from the same local capsule assets without reaching out. If you are installing into an air-gapped or rate-limited environment, that is the flag to reach for.

Once init completes, the first useful command is a status check. The CLI supports both human and machine output:

aos status
aos status --json

The JSON form is the one to wire into a health check or a supervisor, because it avoids parsing a human-facing table. If you want to run the persistent daemon directly, the README gives this form:

aos daemon foreground --workspace /workspace

On Unix, that command replaces the AOS process with the persistent bundled daemon, preserving direct signal and exit-status ownership for process supervisors. On other hosts it waits for the daemon and preserves its exit status. Neither path enables ephemeral lifetime, so the daemon is meant to stay up.

The MCP edge and how approvals are handled

aos mcp serve is the product edge shared by Codex, Claude and Grok. The interesting design decision is what happens when a client cannot present its own approval forms. If a client supports MCP form elicitation, it keeps presenting its own constrained approval forms. When it does not, the default --interaction auto mode falls back to a local AOS decision surface: AppKit on macOS, a native Windows dialog, or Pinentry on Linux.

The policy can be made explicit with --interaction client, native, or deny. The README notes that the local bridge accepts only a single boolean or the fixed AOS approval enum. Arbitrary strings, password-shaped fields, and URL elicitations are never collected through it. That is a deliberately narrow surface, and it is the right call: an approval prompt that can ask for a password is an approval prompt that can be used to phish the operator.

The trade-off is that the fallback is platform-specific. If you are running headless on a Linux host without Pinentry configured, the native path has nothing to draw on, and your realistic options narrow to --interaction client or --interaction deny. The README does not document what happens in that specific combination, which is worth testing before you put it in front of users.

The principal flag appears in the serve form as well:

aos --principal codex-code mcp serve

That is the same principal mechanism used by init, applied to the MCP edge rather than to provisioning.

Forge, meta-harnesses and the self-extension story

Community Edition ships Forge as OS construction tooling. The stated goal is that a fresh agent can inspect the running system, learn the capsule model, identify a real capability gap, and build and verify a least-privilege capsule. Forge also installs the meta-harness skill, which the README says teaches an agent how to build a governed meta-harness on AOS by treating its instructions, memory, skills, harness code, tools, capsules, traces and evaluations as an improvable user-space world.

This is the most ambitious part of the project and the hardest to evaluate from the README alone. The claim is not that Forge writes code; it is that the agent is instructed to notice useful extensions during real work and reach for Forge proactively when new code is the right way to improve that world. Whether that instruction produces useful capsules or a pile of speculative ones depends on the model and the harness around it, and the README does not offer evidence either way. The referenced doc, docs/meta-harness.md, is where the world model, research loop, Forge boundary, optional worker pattern and representative user experiences are described.

A related capsule, capsule-meta-harness, appears in the workspace members, so the skill and the capsule are separate artifacts. If you are evaluating this feature, read docs/meta-harness.md before you install anything, because the README only sketches it.

Distribution pinning, migration and the upgrade path

The sharpest constraint in the README is this: "This AOS release fixes its distribution state to Unicity CE." If you want to apply another distribution, the README directs you to a standalone astrid installation and runtime home. That means AOS Community Edition is not a general-purpose distribution host. It is one distribution, packaged as a product.

The upgrade path depends on how you installed. Homebrew installations update with aos update. Direct installs resolve the signed stable channel by default and can select dev, nightly, or an exact version. The README adds that all of these remain fail-closed until their signed metadata is actually published. That is a meaningful operational detail: selecting nightly does not get you nightly bits if the signed metadata for nightly is absent. It gets you an error.

Importing existing state is a separate, deliberate operation. The aos CLI can copy compatible state from a standalone runtime installation without changing the source. The exact allowlist, integrity checks, recovery behaviour and command live in docs/runtime-migration.md. The README does not document rollback for that import, and it does not document rollback for aos update either. If you are migrating a production runtime, treat the absence of a documented rollback path as something to establish yourself before you run the import.

Re-running the installer performs a coordinated product upgrade without rewriting a standalone runtime installation. That distinction matters if you have both AOS and a standalone astrid on the same machine: the installer will not quietly overwrite the standalone one.

Supply chain, licensing and what a release actually contains

Every release publishes checksums, Sigstore bundles, GitHub build-provenance attestations, and runtime-compatibility.toml, which pins the exact runtime release and WIT commit. Two gates must both be true before a tag can publish: the machine-readable runtime-compatibility gate and the upgrade/self-heal gate. The README states that the latter is approved only after the exact candidate preserves a frozen standalone-home clone and boots with freshly generated runtime coordination state. That is a concrete, checkable release criterion rather than a promise, and it is the strongest signal in the repository about how the maintainers think about upgrades.

The workspace pins its runtime dependencies exactly: astrid-sdk at =0.7.1, and astrid-core, astrid-crypto, astrid-types and astrid-uplink at =2026.9.2. The = prefix means no semver drift. If you are building a capsule against this tree, you are building against those exact versions, and a runtime bump is a coordinated event rather than a patch release.

Licensing is dual: MIT or Apache-2.0, at your option, except where otherwise noted. The workspace manifest declares license = "MIT OR Apache-2.0". The practical implication for capsule authors is that you can pick either licence for your own crate without a compatibility problem. This is a description of what the files say, not legal advice; if you are redistributing a modified AOS or embedding it in a product, read LICENSE-MIT and LICENSE-APACHE yourself.

The release profile is tuned for size rather than speed: opt-level = "z", lto = true, codegen-units = 1, strip = true, panic = "abort". That is a distribution-oriented profile. If you build the workspace yourself for development, expect different build times than the shipped binaries suggest.

Where AOS Community Edition is the wrong tool

The clearest limitation is the distribution pin. If your requirement is to run a distribution other than Unicity CE under the same product install, AOS Community Edition is the wrong tool by design. The README points you to a standalone astrid installation instead. That is not a bug to work around; it is the boundary the product draws around itself.

The second limitation is coupling. Because the runtime crates are pinned exactly and because runtime-compatibility.toml must agree before a tag publishes, a capsule you write today is tied to a specific runtime release and WIT commit. The release validation that prevents an unclassified runtime verb from entering a product release is the same mechanism that makes the surface stable. If you want to write a capsule once and forget about it across many runtime versions, this is not the project for that.

The third is operational. A fresh install includes roughly two minutes of rate-limit waiting, and a stalled batch remains an error. If your deployment pipeline cannot tolerate a multi-minute, rate-limit-aware install step, you need the offline path or a pre-baked image. The README documents aos init --offline but does not describe how to pre-stage the capsule assets for it.

Finally, the project is young in release terms. The listed releases are 2026.9.0, 2026.9.1 and 2026.9.2, all within September 2026. The last push to main was on 2026-09-17. That cadence is fast, which is good for fixes and bad for anyone who needs a long support window.

How AOS CE differs from a standalone Astrid runtime

The most useful comparison is not to another agent framework. It is to the standalone astrid runtime the README keeps referring to. Both run capsules. The difference is what owns the command surface.

A standalone astrid installation owns its own runtime home and exposes the runtime's own command inventory. AOS Community Edition owns a product root at ~/.aos, replaces the lower-level command at any root it claims (init, status, migrate, update, distro, mcp, daemon, serve-health), and passes everything else through with arguments, exit codes and signals unchanged. The complete supported surface is aos <verb>. There is no aos astrid and no aos runtime.

That has a practical consequence for migration. Because the standalone runtime keeps its own home, the AOS CLI can copy compatible state from it without changing the source. The allowlist and integrity checks are in docs/runtime-migration.md. So the two are not competitors so much as two configurations of the same runtime, one of which is productized and pinned to Unicity CE.

If your team already runs a standalone astrid installation with a custom distribution, adopting AOS CE means either running both or migrating state across the documented allowlist. Neither is a drop-in swap, and the README is honest about that.

Editorial conclusion

Adopt AOS Community Edition if you want an inspectable, capsule-composable agent runtime with a single aos command surface and you are willing to stay on the Unicity CE distribution. Do not adopt it if you need to run a different distribution under the same install, or if you expect a stable plugin API across runtime releases: the pinned astrid-* versions and the runtime-compatibility.toml gate exist precisely because that coupling is tight. Before committing, verify three things: the exact astrid-core and astrid-sdk versions your toolchain resolves against, whether the signed stable channel metadata is actually published for the release you intend to run, and whether the import allowlist in docs/runtime-migration.md covers the standalone runtime state you want to bring over.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. unicity-aos/aos-ce on GitHub