Neutron kernel

Personal cloud computer

Decentralised, user-customizable, user-controlled, community-driven kernel for operating systems running on ICP.

Neutron is meant to be fully open. A user owns a Neutron canister, can install apps into it, and can deliberately replace the kernel with any .neutron kernel package they choose. Forking the kernel, changing the operating system rules, and installing that fork is an intended option, not an exception.

Backend is in Motoko.

Documentation: http://ntron.net code: devs

Run repository commands from the repository root:

npm run build
npm run package
npm run repository:generate

build runs the independent workspace builds. package runs each production app's complete packaging workflow and creates its .neutron archive. repository:generate consumes the packaged Hello and Kitchen Sink archives and generates the static example repository's Motoko resources. The generator is a separate phase because it cannot run before those archives exist.

To run all three phases in dependency order:

npm run build:all

App package scripts include their own app build, so build:all deliberately repeats that app-local stage while also covering independent workspace builds. It generates the repository source but does not compile or deploy the example repository canister. Browser and end-to-end tests are separate test commands; build:all does not launch Playwright.

• Kernel is replacable by users.
• Kernel only provides capabilities and security, no system apps - no Sherlocking.
• All apps are equal.
• Kernel is what makes apps work on different distros
• Distros are packs of apps + kernel, later customizations/themes

Start with the documentation index for the current architecture, core contracts, repository map, and suggested reading paths.

• Product Model And User Story explains what a user-owned Neutron is and how ownership, apps, and the replaceable Kernel fit together.
• Security Model defines the trust boundary, app isolation model, capabilities, authorization, and recovery authority.
• Repository And Build Topology maps the monorepo, package pipeline, generated outputs, and component ownership.
• Compiler And Actor Assembly explains how the Kernel and app packages become one checked Motoko actor and install plan.
• Kernel Backend Runtime documents the Motoko services, authorization, static assets, HTTP entrypoints, and self-upgrade path.
• Kernel Frontend Runtime documents the trusted React shell, workspaces, authentication, dialogs, endpoints, and brokers.
• Kernel-App Message Bus defines the private MessagePort protocol connecting the Kernel, tiles, trays, and resident backgrounds.

• App Developer Guide is the practical starting point for building a third-party .neutron app.
• App Development Workflow covers the local build, package, install, and iteration loop used by regular apps.
• App Package Format specifies the format-3 manifest, archive layout, modules, assets, and validation rules.
• Backend App Dependencies explains typed, install-time composition between app backends inside the generated actor.
• App Method Access And Call Consent separates canister-level method access from trusted-UI consent for calls.
• App Tray defines tray declarations, resident-background requirements, badges, and private tray actions.
• App And Agent Install Offers explains how apps and agents may present packages without gaining installation authority.
• Evolving Candid Interfaces gives compatibility rules for independently upgraded Candid services and clients.
• Managed Memory Migrations And Uninstall covers durable schemas, migration graphs, retirement, and safe data removal.
• Neutron Design System describes the shared UI package and conventions for consistent app frontends.

• Kernel Capability Inventory lists every authored and derived capability and its runtime projection.
• Asset Storage And HTTP Serving explains package assets, staging, certified records, public routes, and serving behavior.
• Certified HTTP And Certified Assets defines app-scoped certified collections and their fixed public-read policies.
• App-Isolated Stable Store documents the development implementation of bounded, installation-scoped durable binary storage.
• App-Isolated vetKeys explains the implemented key-slot contract, browser recovery, lifecycle state, and remaining release gates.
• App-Isolated Chain-Key Signing documents development-stage domain-separated assertion signing without exposing raw threshold authority.

• Unified Provisioning System is the canonical contract for local and production creation, reinstall, verification, and recovery.
• Local Development And Deployment is the PocketIC setup and deployment runbook.
• Production Provisioning covers IC creation, adoption, destructive reinstall, controller handling, and deployment evidence.
• Dispenser And Provisioning documents the developer-preview SushiOS bootstrap, payment, provisioning, and one-time activation handoff.
• Repository Setup Manifests defines repository-delivered setup offers without creating a marketplace or automatic install path.
• App Package Updates is the canonical version-bump, packaging, publication, verification, and owner-reviewed update workflow.
• Testing And Verification describes fast checks, browser tests, replica tests, and production qualification evidence.
• Playwright explains repeatable local browser tests and explicitly enabled interactive investigation.

• Developer Experience Roadmap records workflow improvements still planned for Kernel, app, and integration developers.
• Open Questions And Design Gaps collects unresolved cross-cutting questions and is not a statement of current authority.