Nexus

Nexus is how apps get on and off AuraOS. It's both the distribution layer (resolve → fetch → validate → install) and the app store (a catalog aggregated across every registered source). Once Nexus installs an app, the AppManager runs it like any other — nothing in the app SDK depends on Nexus, and apps never call into it.

To ship your own app, jump to Publish an App. This page covers the model and how to manage registries.

Sources

Nexus aggregates apps from a set of sources you register. Each source is exactly one strict kind — the store never guesses:

Two distribution forms follow: an OCI artifact (from an oci source or an index entry's oci ref) or a git repo (a git-app or an index entry's git ref). Sources are persisted in the shell KV store at os/nexus/sources.

The local registry

Every OS ships with com.aura.registry — a zot OCI registry running as a system service at http://aura-com.aura.registry:4090. It's pre-registered as the source local (priority 0), so you can publish and install end-to-end with no external account. It's the default target for aura nexus app publish.

Managing sources

aura nexus registry list                          # every source: kind, url, priority
aura nexus registry remove <name>                 # drop a source

# Add an OCI registry (a private mirror, a corporate ghcr.io, …):
aura nexus registry add myreg https://reg.example.com --kind oci

# Add a git-index catalog (a repo with an index.yaml of many apps):
aura nexus registry add community github.com/you/aura-catalog --kind git-index

# Add a single-app git repo:
aura nexus registry add hello github.com/you/hello --kind git-app

--priority <n> orders sources (lower wins when the same app id appears in several); --mirror (oci) probes that registry first for any ref; --ref <branch|tag> pins a git source. When you add a git-index or git-app, Nexus fetches/clones it once to validate it before saving.

Run your own store by standing up any OCI registry (or hosting an index.yaml in a repo) and registering it here — no AuraOS-specific server needed.

Installing

aura nexus app install <ref>            # resolve + fetch + validate + install
aura nexus app list                     # what's installed (id, version, scope, source)
aura nexus app info <ref>               # dry-run: resolved address + permission preview
aura nexus app update [<id>|--all]      # re-resolve the stored ref, reinstall if changed
aura nexus app uninstall <id> [--purge] # stop instances, remove (purge also wipes /data)
aura nexus search [<q>] [--refresh]     # search the aggregated catalog

<ref> can be a store id, a registry ref, a git URL, or a local path — the resolver dispatches on the shape, no flags needed:

Installs default to the global scope; pass --scope user for a per-user install. Full command flags live in the CLI Reference.

Permission gating

Before an install lands, Nexus diffs the incoming manifest's permissions[], tools[], and dataProvider against the currently-installed version. Pure code updates go through silently; anything that adds a permission, a tool, or a content-provider authority pauses and asks for approval. Pass -y / --yes to skip the gate (right for CI, never for user-driven installs).

The pipeline

Every install walks the same stages, driven as an async generator (NexusManager.install) so the CLI and the shell UI consume the same event stream:

ref  →  Resolver  →  Fetcher  →  Validator  →  PermissionDiff  →  Installer
                                                     ↓
                                              (approval gate)
                                                     ↓
                                              install record

• Resolver classifies the ref and, for store ids, looks it up in the aggregated catalog.
• Fetcher pulls the source into staging — oras pull for OCI, git clone for git, copy for local.
• Validator runs the manifest schema and rejects anything malformed.
• PermissionDiff computes the approval gate above.
• Installer lands the app into the target scope's appsDir and writes an install record; the AppRegistry picks it up and the app becomes launchable.

For the internals, see the Nexus pipeline deep-dive.

Next

• Publish an App — ship your app to a registry.
• Scopes — where installs land (system / global / user).
• CLI Reference — every aura nexus … flag.