LICENSE-MIT Documentation

1. Project Overview & Quickstart (unicity-astrid/LICENSE-MIT) Copy Chapter

LICENSE-MIT

Open-source repository unicity-astrid/LICENSE-MIT

Repository Details Copy Section

• Repository: unicity-astrid/LICENSE-MIT
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (unicity-astrid/unicity-astrid.github.io) Copy Chapter

File: README.md Copy Chapter

Unicity AOS website

Product website and developer documentation for Unicity AOS, the modular
Agent Operating System from Unicity. The site explains the product distribution
while preserving the boundary to Astrid Runtime,
the open operating-system engine beneath it.

The production hostname is aos.unicity.ai. Until the
first signed AOS product release is published, the install surface visibly marks
stable, dev, nightly, Homebrew, and AOS Oracle channels as staged and keeps every
copy action disabled.

Repository layout Copy Chapter

Develop Copy Chapter

The website requires Node.js 22.12.0 or newer.

cd site
npm ci
npm run check
npm run build
npm run dev

Both check and build are release gates. The product release integration is
centralized in site/src/lib/release.ts; available may become true only
after matching AOS artifacts, checksums, signatures, and installer assets exist.

The default installer channel is stable. Development and nightly channels are
always explicit (--channel dev and --channel nightly) and never fall back to
stable. The commands are documentation only while their channel metadata is
unavailable.

site/public/install.sh is a byte-for-byte mirror of the canonical aos-ce
installer. Pages CI records the exact source commit in
AOS_INSTALLER_SOURCE_COMMIT and compares both source and built copies. Update
that commit and the mirror together only after the canonical installer contract
has landed.

Community Edition source lives in
unicity-aos/aos-ce.

File: site/src/content/developers/architecture.md Copy Chapter

title: Product and runtime architecture part: Orientation order: 20 Copy Chapter

Unicity AOS is the agent operating system people install. Astrid is the secure
engine included inside it, and capsules are the isolated abilities that turn the
engine into a useful agent. The layers keep product behavior replaceable without
weakening the part that enforces permissions.

The stack Copy Chapter

The kernel deliberately contains no agent loop, model choice, memory strategy,
or product workflow. It routes typed events, checks capabilities, runs WebAssembly
components, meters resources, and maintains runtime records. Intelligence lives
in capsules.

How a turn moves Copy Chapter

1. An uplink publishes a user prompt on the event bus.
2. The coordinator loads the session and asks the prompt builder for context.
3. Hook capsules contribute identity, project rules, memory, and other context.
4. A provider capsule calls the selected model.
5. Tool calls pass through the router and capability checks.
6. Results return over typed topics and the uplink renders the response.

Every step crosses an explicit contract. Capsules do not call one another by
linking Rust libraries together, and a prompt cannot grant a host capability.

Decide where a change belongs Copy Chapter

Put a change in AOS when it defines the product composition, customer behavior,
edition policy, a first-party capsule, an integration, or a product API. Put it
in Astrid Runtime when every distribution needs the same generic primitive: a
WIT contract, sandbox rule, capability type, scheduler behavior, or daemon API.

If an AOS capsule needs a missing host function, design the smallest generic
contract upstream. Release the WIT and SDK change, then consume that release in
AOS. Do not fork the engine or add an AOS-only escape hatch to the kernel.

Compatibility is part of the architecture Copy Chapter

Crate names, astrid:* WIT namespaces, @unicity-astrid package identities,
ABI names, signed artifacts, and release URLs are versioned compatibility
surfaces. AOS can change its product composition without rewriting the contracts
existing capsules were built against.

File: site/src/content/developers/build-package.md Copy Chapter

title: Build and package part: Ship and release order: 70 Copy Chapter

There are two different build outputs. A raw WebAssembly file proves the Rust
component compiles. An installable .capsule bundles the component, manifest,
metadata, and verification material expected by the runtime.

Compile the component Copy Chapter

Run from the capsule directory so .cargo/config.toml selects
wasm32-unknown-unknown and the repository's getrandom backend configuration.

cargo build --release

Do not install the .wasm directly and do not rename it by hand to .capsule.
That skips component packaging and verification.

Build the artifact Copy Chapter

Use the released Astrid build tooling through the product's pinned development
environment:

aos capsule build

The supported build produces an artifact under dist/. The exact filename is
derived from the package identity and version; automation should discover it
from the build output or a manifest, not guess it.

Before release, verify:

• every [[component]].file exists in the package;
• the component imports only declared WIT contracts;
• manifest and component versions agree;
• the runtime compatibility range covers the pinned AOS runtime;
• no source maps, local paths, secrets, or test fixtures leaked into the bundle;
• a clean checkout produces the same content digest.

Reproducibility Copy Chapter

Use the committed Cargo.lock, pinned toolchain, released SDK, and a clean
working tree. Do not package with an unpublished path dependency.

cargo build --locked --release
git diff --exit-code

Record the source commit, toolchain, artifact digest, and dependency lock in the
release attestation. Signing identifies what was published; reproducibility lets
another developer prove how it was produced.

Smoke installation Copy Chapter

Create a temporary product home, install the artifact through the normal runtime
surface, invoke one success path, and exercise at least one denied capability.
Do not reuse a developer's live ~/.aos in CI.

The product release should stage every capsule artifact first, verify all
digests, then compose the distro lock. Never resolve Community Edition from
mutable repository branches during end-user installation.

File: site/src/content/developers/capsule-anatomy.md Copy Chapter

title: Capsule anatomy part: Build capsules order: 35 Copy Chapter

A capsule is an installable WebAssembly component plus a declarative manifest.
It is not a daemon plugin and it is not a Rust library loaded into the kernel.
The runtime instantiates it inside a sandbox and exposes only the WIT imports and
capabilities approved at installation.

Create the package Copy Chapter

First-party capsules live at capsules/capsule-<name> in the AOS CE workspace.
A minimal layout is:

capsules/capsule-greeter/
├── .cargo/config.toml
├── Cargo.toml
├── Capsule.toml
├── README.md
└── src/lib.rs

Use the workspace SDK and compile as a cdylib.

[package]
name = "astrid-capsule-greeter"
version = "0.1.0"
edition = "2024"
license = "MIT OR Apache-2.0"

[lib]
crate-type = ["cdylib"]

[dependencies]
astrid-sdk = { workspace = true }
serde = { workspace = true, features = ["derive"] }
serde_json = { workspace = true }

The published package name can retain the astrid-capsule-* compatibility
identity while its description and documentation correctly place it in AOS.

The checked-in target configuration makes a plain capsule build produce the
component input expected by the packaging tool:

[build]
target = "wasm32-unknown-unknown"

[target.wasm32-unknown-unknown]
rustflags = ["--cfg=getrandom_backend=\"custom\""]

That custom random backend routes entropy through the audited astrid:sys
host import. Do not switch the capsule to WASI to make an undeclared host call
work.

Implement one handler Copy Chapter

The SDK macros generate the component export surface. Keep the handler small and
move deterministic logic into ordinary Rust functions that host tests can call.

#![deny(unsafe_code)]

use astrid_sdk::prelude::*;

#[derive(Default)]
pub struct Greeter;

#[capsule]
impl Greeter {
    #[astrid::interceptor("handle_greet")]
    pub fn handle_greet(&self, payload: serde_json::Value) -> Result<(), SysError> {
        let name = payload.get("name").and_then(serde_json::Value::as_str).unwrap_or("agent");
        ipc::publish_json(
            "greeter.v1.response.greet",
            &serde_json::json!({ "message": format!("Hello, {name}") }),
        )
    }
}

Never trust a caller identity supplied inside payload. The runtime-stamped
envelope is the authority for the current invocation. Validate size, required
fields, enum values, and paths before touching a host import.

Declare the same contract Copy Chapter

Capsule.toml is the runtime's installation boundary. The subscribe handler must
match the exported macro name, and every response topic must be allowed by
[publish].

[package]
name = "astrid-capsule-greeter"
version = "0.1.0"
description = "Greeting example for Unicity AOS"
astrid-version = ">=0.9.4"

[[component]]
id = "greeter"
file = "astrid_capsule_greeter.wasm"
type = "executable"

[subscribe]
"greeter.v1.request.greet" = { wit = "@example/greeter/greet-request", handler = "handle_greet" }

[publish]
"greeter.v1.response.greet" = { wit = "@example/greeter/greet-response" }

Only one trailing wildcard is accepted for normal subtree subscriptions. Prefer
concrete publish topics when the capsule can enumerate them. A handler return
value is not a bus response; publish the response explicitly.

First validation loop Copy Chapter

cd capsules/capsule-greeter
cargo fmt -- --check
cargo build
cd ../..
cargo test --locked -p astrid-capsule-greeter

Plain cargo build verifies the WebAssembly compilation configured by the
capsule. Run host tests from the workspace root so the member's WebAssembly
target configuration does not try to execute a browserless .wasm test binary.
The build does not produce an installable .capsule; packaging is a separate
step covered in Build and package.

File: site/src/content/developers/capsules.md Copy Chapter

title: Compose capsules into AOS part: Build capsules order: 30 Copy Chapter

A capsule is one isolated ability in AOS. Community Edition selects a tested set
of capsules and grants each one the capabilities it needs. The Astrid SDK, WIT
contracts, sandbox, and artifact format provide the common runtime surface.

Add the workspace member Copy Chapter

Create capsules/capsule-<name> and add it to root workspace.members. Reuse
root dependency versions wherever possible. Every capsule has its own
Cargo.toml, Capsule.toml, source, tests, and README, while the workspace has
one committed dependency lock.

cargo check --locked --workspace

Finish the component itself using the chapters on capsule anatomy,
manifest authority, and IPC contracts.

Add the distro entry Copy Chapter

Community Edition composition lives in
distros/community/unicity-ce/Distro.toml. The first product release packages
verified .capsule artifacts beside the distro under capsules/; pin the
artifact version and reference that release-local path.

[[capsule]]
name = "astrid-capsule-example"
source = "capsules/astrid-capsule-example.capsule"
version = "0.1.0"

Add role = "uplink" for a frontend. Use a named group for mutually selected
providers. Supply product defaults through env placeholders rather than
hard-coding credentials in the capsule.

[variables]
example_endpoint = { description = "Example service base URL", default = "https://example.invalid" }

[[capsule]]
name = "astrid-capsule-example"
source = "capsules/astrid-capsule-example.capsule"
version = "0.1.0"
env = { endpoint = "{{ example_endpoint }}" }

The public capsule registry is not live yet. Do not put a registry namespace in
the CE manifest until that namespace resolves to signed, immutable artifacts.

Validate the composition Copy Chapter

The distro is a graph. Installing a capsule is insufficient if its subscribed
topics have no publisher, its WIT requirements are unsatisfied, or its provider
group has no selected member.

Check:

• package version matches the built artifact;
• all required WIT packages fall within distro compatibility;
• publish and subscribe topics have intended peers;
• requested host capabilities are explainable during onboarding;
• environment variables resolve without exposing secrets;
• clean initialization installs the complete CE set;
• removing the capsule leaves the remaining distro coherent.

Keep runtime contracts generic Copy Chapter

Add product behavior through capsules and distro policy. If the change needs a
generic WIT contract, SDK capability, kernel operation, or sandbox behavior,
design it upstream in Astrid Runtime and consume a released version.

Published crate names, astrid:* namespaces, @unicity-astrid WIT identities,
and signed artifact names remain compatibility contracts. Product prose and
descriptions say AOS; identifiers change only through a deliberate compatible
protocol migration.

File: site/src/content/developers/ci.md Copy Chapter

title: Continuous integration part: Ship and release order: 80 Copy Chapter

CI should fail at the earliest useful boundary and still prove the final artifact.
Separate fast workspace feedback from packaging and end-to-end release jobs.

Pull-request gates Copy Chapter

Run for every Rust change:

cargo fmt --all -- --check
cargo check --locked --workspace
cargo test --locked --workspace
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings

Also build each capsule with its checked-in target configuration. A host-only
workspace pass does not prove the WebAssembly component compiles.

Contract gates Copy Chapter

When SDK or WIT inputs change:

• verify generated WIT mirrors are current;
• build every consuming capsule;
• compare the public API and WIT contract surface;
• reject an unversioned incompatible change;
• test both the oldest and newest supported runtime where the range spans them.

Artifact gates Copy Chapter

For each release candidate:

1. build from a clean checkout with --locked;
2. produce the .capsule, not only raw .wasm;
3. inspect the package manifest;
4. calculate and record its digest;
5. install into an isolated AOS home;
6. execute success and denial smoke tests;
7. upload only after every capsule passes.

Run matrix jobs for Linux and macOS when host tooling differs. Do not claim
Windows support from a Rust cross-compile alone; the product needs state paths,
IPC, services, installer, and end-to-end tests on Windows.

Product-site gates Copy Chapter

The website is part of the release contract. It must pass both:

npm run check
npm run build

Validate that installer metadata names the same AOS version as release assets,
that the command downloads the product rather than a standalone runtime, and
that the developer-guide index contains working /developers/... URLs.

Secrets and logs Copy Chapter

Use least-privilege workflow tokens, pin third-party actions to reviewed
revisions according to repository policy, and never echo signing material. Keep
release jobs protected from untrusted fork code.

File: site/src/content/developers/cli.md Copy Chapter

title: Product CLI part: Operate AOS order: 100 Copy Chapter

aos is the product command. It owns the product home, Community Edition
composition, health projection, version identity, and update policy.
Lower-level operator commands use the Astrid engine bundled in the same AOS
release, so the complete runtime command set remains available through one CLI.

Product-owned commands Copy Chapter

aos self-update remains an alias for aos update. aos distro is also
product-owned and refuses replacement of the Unicity CE composition.

The public installer applies the embedded Community Edition composition and
wires the selected host plugins. There is no separate activation step. A
developer who deliberately wants another distribution uses standalone Astrid
Runtime outside the product installation.

Delegated commands Copy Chapter

Every other command is executed by ~/.aos/runtime/bin/astrid with
ASTRID_HOME=~/.aos/runtime and the product workspace state directory
set only in the child process. This includes runtime/operator surfaces such as
daemon operation, capsule inspection, diagnostics, and agent execution. The
product-owned aos status remains the supported local status projection; it is
not delegated to the runtime command of the same name.

aos doctor
aos start
aos logs
aos capsule list
aos run

The exact delegated command set is the command set of the Astrid Runtime version
pinned into that AOS release. aos does not copy the implementation and should
not maintain a second parser for every runtime flag.

Product home override Copy Chapter

Use AOS_HOME to isolate a development or CI installation:

export AOS_HOME=/absolute/path/to/aos-home
aos status

Do not export ASTRID_HOME globally as an AOS setup step. The wrapper owns that
child-process setting, which prevents product state from colliding with a
standalone runtime.

Exit codes and automation Copy Chapter

Product commands return zero on success and nonzero on validation,
health-service, update, or child-runtime failure. Automation should consume the exit
code and structured HTTP contracts rather than matching human help text.

aos serve-health binds only 127.0.0.1:8765. It is a long-running service,
not a one-shot health check; probe it with GET /v1/runtime/health.

File: site/src/content/developers/get-started.md Copy Chapter

title: Get started with AOS CE part: Orientation order: 10 Copy Chapter

Unicity AOS Community Edition is the public product distribution. Its command is
aos; its product home is ~/.aos; its private bundled runtime lives at
~/.aos/runtime.

Install AOS Copy Chapter

Stable is the installer default. Development and nightly are always explicit:

# Stable
curl -fsSL https://aos.unicity.ai/install.sh | sh

# Explicit prerelease channels
curl -fsSL https://aos.unicity.ai/install.sh | sh -s -- --channel dev
curl -fsSL https://aos.unicity.ai/install.sh | sh -s -- --channel nightly

An unavailable channel must stop without installing or falling back to another
channel.

git clone https://github.com/unicity-aos/aos-ce.git
cd aos-ce
cargo check --locked --workspace
cargo test --locked -p unicity-aos-bootstrap

Do not use cargo install astrid as an AOS installation. That installs a
standalone runtime CLI and does not provide the AOS product wrapper, embedded
Community Edition manifest, product home, or coordinated update policy.

Product release layout Copy Chapter

The signed release archive contains:

bin/aos
runtime/bin/astrid
runtime/bin/astrid-daemon
runtime/bin/astrid-build
runtime/bin/astrid-emit
Distro.toml
capsule-assets.txt
capsules/*.capsule

The installer selects a platform archive named
unicity-aos-<target>.tar.gz, verifies the signed release identity and archive,
and installs the product, pinned runtime, and Community Edition capsule set
together.

Verification passes the archive itself to cosign verify-blob, binding the
downloaded bytes to the AOS release workflow identity and immutable calendar
version tag before extraction. The release publishes BLAKE3SUMS.txt as its
primary digest inventory and SHA256SUMS.txt for compatibility with external
tooling such as Homebrew.

The archive's schema-2 release-manifest.json records the Astrid Runtime input as
runtime.digest = "blake3:<64 lowercase hex>". The installer does not substitute
a detached checksum comparison for direct Sigstore archive verification.

Start a host plugin Copy Chapter

No manual post-install activation command is required for Claude Code, Codex,
or Grok Build. Start a selected host after installation. Its plugin provisions
only that host's named principal and Oracle pack.

The release also publishes the Homebrew formula:

brew install unicity-aos/tap/aos

The tap repository and formula automation can exist before the formula itself.
The command works only after the stable release publishes and verifies it.

The installer applies the Unicity CE manifest from the same signed product
release. It does not fetch a mutable manifest from main. The wrapper keeps
the product runtime home separate from standalone Astrid state.

Verify the installation Copy Chapter

aos --version
aos status
aos doctor
aos capsule list

If the health service is enabled:

curl --fail http://127.0.0.1:8765/v1/runtime/health

A ready response proves the local product runtime is reachable. It does not
prove that every provider credential, external service, or optional capsule is
ready; use delegated runtime readiness and product diagnostics for those.

A clean product home Copy Chapter

AOS creates ~/.aos and provisions Community Edition from scratch. It does not
import, rename, rewrite, or delete a standalone ~/.astrid installation. The two
homes can coexist, which makes a first AOS install safe to evaluate and remove
without changing an existing Astrid setup.

File: site/src/content/developers/http.md Copy Chapter

title: HTTP API status and conventions part: HTTP API order: 130 Copy Chapter

Unicity AOS exposes a narrow local health service and a broader authenticated
product gateway. The health service answers one readiness question; the gateway
provides the customer and integration API documented in the remaining chapters.

Implementation status Copy Chapter

The remaining chapters map the complete gateway surface. The running release's
generated OpenAPI document remains authoritative when website copy and a deployed
version differ.

Product health Copy Chapter

GET /v1/runtime/health HTTP/1.1
Host: 127.0.0.1:8765

The loopback service returns 200 {"ready":true} when the bundled runtime is
ready and 503 {"ready":false} otherwise. It accepts no query parameters, no
implicit HEAD, no CORS, and no caller-selected principal, socket, or IPC topic.
It does not expose diagnostics, keys, audit records, or arbitrary bus access.

Gateway base and discovery Copy Chapter

Examples use http://127.0.0.1:2787. Operators may bind the product gateway
elsewhere, but public exposure requires TLS, reverse-proxy policy, and an
explicit CORS allowlist.

curl --fail http://127.0.0.1:2787/api/openapi.json

Unauthenticated routes are limited to discovery, onboarding, redemption, and
operations probes:

All other routes require Authorization: Bearer <session-token>.

Wire conventions Copy Chapter

• JSON requests send Content-Type: application/json.
• Ordinary responses are JSON unless the OpenAPI content type says otherwise.
• Streaming routes use Server-Sent Events and reconnect semantics documented in
  Agent and event streams.
• Unknown fields, invalid identifiers, and out-of-range pagination values are
  client errors; clients must not rely on silent coercion.
• Error bodies and status codes in the deployed OpenAPI document are
  authoritative for that release.
• CORS is off by default. An empty origin allowlist emits no CORS headers.
• Security headers apply to public, authenticated, preflight, and error responses.

Client rule Copy Chapter

Generate clients from the OpenAPI document shipped by the same AOS release you
deploy. Do not copy schemas from main, and do not assume a route documented
here exists until the running product release advertises it.

File: site/src/content/developers/http-admin.md Copy Chapter

title: Administration API part: HTTP API order: 145 Copy Chapter

Administration routes require a bearer session and then apply capability checks
for the requested operation. Authentication alone does not make a caller an
administrator.

Principals Copy Chapter

IDs are path parameters validated by the server. A disabled principal remains an
identity and can retain records; clients should not present disable as delete.

Capabilities and quotas Copy Chapter

Capability grants narrow authority; they do not alter capsule code. Build
administrative UIs from the capability catalog instead of hard-coding labels.
Quota and usage are different: setting a limit does not reset consumed usage.

Groups and invites Copy Chapter

Invite list responses expose fingerprints and safe metadata, not reusable
secret material. Show a newly issued code once, then store only what the schema
permits.

Capsules and environment Copy Chapter

Install accepts only sources allowed by product policy and verification. Do not
build a UI that turns an arbitrary URL into a trusted capsule. Environment
schemas mark request text, types, defaults, and secret handling; never echo a
secret value after writing it.

Models and runtime Copy Chapter

Model selection is a product operation delegated to capsules; the kernel does
not contain model policy. A reload is an administrative mutation and should be
followed by readiness checks before traffic resumes.

Operations probes Copy Chapter

GET /healthz and GET /metrics are public to support load balancers and
Prometheus. “Public” means no bearer middleware, not safe for the open internet.
Restrict them with the reverse proxy or firewall. The separate AOS
/v1/runtime/health loopback projection remains intentionally narrower.