Skip to main content

Repositories

An independent provider can hand an owner a setup link: a pinned reference to a certified manifest naming a set of packages to install together.

This is not a Neutron-operated app store. Neutron configures no default or production repository, and the protocol does not change the ordinary .neutron trust boundary. A setup manifest is not an update feed; later app upgrades use the separate update_source contract.

A setup link carries only three things, in the URL fragment:

  • the canonical repository canister principal
  • the manifest id
  • the exact manifest SHA-256

Query-string setup fields are rejected. The Dispenser and Kernel synchronously capture and remove the fragment and keep it in short-lived same-tab state. The Dispenser backend never receives any of it. The Kernel refuses partial triples, duplicate or unknown reserved fields, and setup or activation fields supplied in a query string.

The flow​

Two decisions in that flow are worth understanding.

Anonymous reads​

Load setup creates a fresh anonymous agent rather than reusing the owner's Internet Identity agent. That keeps the owner principal out of the repository Candid call. Transport forces omitted credentials, no referrer, and no cache, and the kernel HTML carries a no-referrer policy.

:::caution This is not network anonymity Gateways and IC network infrastructure may still see request metadata, and a provider can correlate a uniquely issued manifest id or digest with whoever was given that link. :::

Uniform fetching​

The browser fetches, verifies, and prepares every package in the pinned manifest before consulting owner selection — including ids already installed.

That uniform request set is deliberate: fetching only the not-yet-installed subset would reveal the owner's installed inventory to the provider through the omissions. Selection and dependency closure are computed locally and make no further repository request.

What certification proves​

Every consumed resource is bound to the chosen canister and the exact certified tree key through an IC certificate and Merkle witness. The link digest is checked against exact manifest bytes before any JSON use. Each manifest entry pins the exact raw package size and SHA-256, and bounded preparation then requires the package's internal id and version to agree.

:::caution What it does not prove Certification and digests prove byte provenance and integrity. They do not prove publisher identity, legality, security review, or quality.

Provider and publisher names and HTTPS links are plain-text, visibly unverified claims. A package's internal neutron.json remains authoritative, and repository-supplied display fields cannot change package behaviour or select a different fetch URL. :::

Bounds​

Remote import bounds cover metadata, packages, chunks, concurrency, archive entries, decoded entry bytes, and aggregate raw and decoded bytes across the whole manifest — the repository path uses stricter limits than a manual local file install, plus manifest-wide aggregates.

The decoder preflights the MessagePack map and bounded gzip envelopes before accepting files. Duplicate ids, duplicate digests, mutable targets, and conflicting shared modules all fail before mutation.

Kernel packages are excluded​

A repository package can never be a kernel replacement. The importer rejects repository-delivered kernel outright.

Deliberate kernel replacement remains a manual, owner-selected, explicitly disclosed local-file action. This is one of the clearest boundaries in the system: an app catalog cannot replace your kernel.

Installation​

Installed presence is conservatively reconciled across the registry, the compiled config, and runtime state. Any present id is skipped rather than updated — a repository import never becomes an implicit upgrade.

The selected closure compiles once and deploys through one journal. Immediately before mutation the kernel rechecks the authenticated baseline; the repository path requires a checked install begin comparing the expected running deployment id before storing the journal.

Opening the link, authenticating, loading and validating the manifest, changing selection, or compiling the review does not install anything. The setup reference expires after one hour through loading, selection, and compilation. Once the owner approves the exact compiled transaction, an in-flight deployment may finish after that deadline; if it fails, the original deadline is restored and rechecked.

Interrupted-install recovery​

The repository flow holds the shared compiler/deployment mutex from Load setup until cancellation, failure, or completion. A checked journal fences app authority and other app mutations once deployment begins.

Before and after loading an install baseline, the Kernel reconciles any existing journal. If the journal's actor is already active, it completes the commit. If activation may still arrive, it waits rather than guessing. A persistent, nonmodal recovery panel in Settings lets the owner inspect the exact staged deployment and discard it only after the dispatch marker and ordered management fence prove that no queued activation can still apply it.

The journal does not block unrelated Settings work, and Neutron never aborts another tab's journal merely because a timer elapsed. After an interrupted deployment, resolve that recovery state before opening a replacement setup or starting another app mutation.

Provenance​

Only selected, committed apps receive a minimal source and integrity record under /system/install-provenance.json. It is an ordinary certified HTTP asset and therefore public, not private.

Not retained: the raw link, any token, unselected ids, provider prose, fetch history, or a repository callback.

In Settings, normal mode turns that record into a source kind and package integrity status without implying publisher trust; developer mode shows the repository principal, manifest id, pinned manifest SHA-256, and package SHA-256.

It is a source/integrity record — not an update link, subscription, private record, or provider endorsement. Manual package replacement clears a stale entry, and uninstall removes it.

Running a provider​

A static provider template exists in the repository. It derives deterministic certified manifests and package resources from real .neutron artifacts, which makes it usable both for provider development and for protocol tests.

The generated canister exposes only four public certified query methods. It has no HTTP asset endpoint, uploader, publisher account, application administrator, or deployment command. “Static” does not mean cryptographically immutable: an IC controller can still replace its code. Setup-link manifest digests ensure that changed manifest bytes fail an old link; they do not constrain the controller itself.

Repository apps conventionally start at 0.1.0 and increment the patch component until a minor or major bump is chosen deliberately.