What Neutron is

Neutron is a personal operating-system kernel running on the Internet Computer: one user-owned canister whose owner chooses its apps and may replace the kernel itself. Canister state is replicated and Neutron does not make a general confidentiality claim.

Nobody installs "Neutron" by itself, any more than anyone installs Linux by itself. What you deploy is a distro — an operating system assembled on the kernel, carrying its own starter apps, assets, and runtime configuration, seeded when the canister is provisioned. SushiOS is the first. A different distro can change any of that, and because the kernel is itself just a package, it can replace the kernel too.

A running system is one canister. That canister runs the kernel, serves the browser UI, stores every installed application's frontend assets and backend state, and rewrites its own WebAssembly module whenever you install something. The product model assigns it to one human owner; the implementation represents that owner's access as a flat set of full-trust authorized principals.

The system is deliberately open all the way down. The kernel is packaged and installed by the same machinery as any other app, and a package whose id is kernel is a kernel replacement. Forking the kernel, changing its rules and its UI, and installing that fork into your own canister is an intended option — not an exception someone forgot to close. That is what makes more than one distro possible.

We are developing the chicken and the egg at the same time.

The one idea that explains the rest

Most of Neutron's design follows from a single decision:

Applications are not separate canisters. They are compiled into yours.

An app package ships a Motoko backend module, browser assets, and a manifest. Installing it collects every backend module already living in your canister, adds the new one, assembles them into one Motoko actor, compiles that actor to WebAssembly inside your browser tab, and asks the canister to upgrade itself with the result.

That gives you a genuinely integrated computer — apps share one identity, one Candid interface, one canister HTTP service with separate static/package and app-published certified stores, one upgrade path, and can call each other's declared backend functions directly with no network hop. It also means there is no canister boundary between apps, so the security boundary has to be built somewhere else: in the code generator, in static analysis of app source, in a closed capability system, and in the browser's frame isolation. Those four mechanisms are what the Security chapter is about.

What is in the box

Layer	What it does
Kernel backend	Owns authorization, certified asset storage, HTTP serving, capability brokers, the install journal, and canister self-upgrade.
Kernel frontend	A React tiling workspace shell: launcher, workspaces, app tray, Settings, install dialogs, and every consent prompt.
App packages	.neutron archives containing a manifest, hashed Motoko modules, and optional web assets.
Compiler	Assembles and compiles the combined actor — in the browser, in a CLI, or inside the provisioner.
Capability brokers	Kernel-owned, per-installation gatekeepers for outbound calls, randomness, HTTPS outcalls, threshold signing, stable storage, vetKeys, and certified assets.
Provisioner	Creates and reinstalls whole canisters, locally on PocketIC or in production on the IC.

Who this documentation is for

App developers want Building an app and the Packaging chapter — how to shape a Motoko backend, what the manifest declares, and how a package is built and installed.

Reviewers and security people want Security. It is written to separate what the implementation actually enforces from what is merely intended, and it names the boundaries Neutron explicitly does not claim.

Operators want Operating a Neutron — how canisters are created, how a local fleet is stood up, and how certified repositories and update sources work.

Everyone should start with Concepts, which is short and explains why the rest of the system is shaped the way it is.

A note on maturity

Neutron is preproduction. Several subsystems documented here are marked development and carry explicit release gates. In particular, the Certified Assets API has a source-owned local qualification runner, but only a pass receipt bound to the current candidate is qualification evidence, and even that bounded run does not establish behaviour at the production entry ceiling. The hosted dispenser also still needs a paid mainnet deposit-to-activation qualification. Those caveats are stated inline where they apply rather than collected in a disclaimer, because they change what you are allowed to promise your users.

Where this documentation describes a limitation, an open question, or an unfinished path, that is deliberate. See Open questions.

Getting a system to work on

For the hackathon you do not need to deploy anything on the Internet Computer. Clone the repository and run a whole Neutron locally: the provisioner fetches and verifies its own pinned PocketIC server, creates the canister on it, compiles the kernel and every configured app into a single actor, and installs it. No ICP, no cycles, no mainnet canister.

git clone https://github.com/infu/neutron
cd neutron
npm install

Keep the local server running in one terminal:

npm run provision -- local.ndeploy.json serve

and from a second terminal in the same environment, install the configured fleet and print where it landed:

npm run provision -- local.ndeploy.json reinstall
npm run provision -- local.ndeploy.json status

Open the node URL printed by status — with the default gateway it has the form http://<canister-id>.localhost:8000/ — and you have a system to build against, including the same launcher install flow an owner sees. What you get is a real Neutron: the same kernel, the same browser compile, the same capability checks. What you do not get is persistence across runs — every reinstall is a destructive whole-canister reinstall — or a URL anyone else can open.

Getting started has the prerequisites (Bun, Mops on PATH) and the app packaging loop; Provisioning explains configs, sessions, and what each command is allowed to do.

Deploying on the Internet Computer is the other path — for when you want a canister that is actually yours: persistent, publicly reachable, paying its own cycles, upgrading itself. The dispenser creates one for 2 ICP, which becomes the cycles it runs on; the button on the home page says what you get.