@package-system

Building your own native package

Develop a Neuralis package in its own repository: administrator-assigned native trust, sandboxed alternatives, build requirements and kernel peers.

A package does not have to live inside Neuralis to be a native one. This page is for a package that is a product in its own right: its own repository, history and release cadence, built against the published contract into the deployment's image from its directory, a packed tarball or a registry version.

First decide which lane you are in

The two lanes that run code differ not in where the code lives but in trust, which is assigned by how the package arrived, never declared by the package.

Sandboxed laneNative lane
How it arrivesa folder in the project's _packages/, or a mounted directory the project picks upthe deploying administrator registers it as a dependency of the host
Who can do itanyone who can write to the projectonly whoever controls the deploy configuration
Trust tieruntrusted (an admin may elevate to trusted; never to native)native, assigned by the host
RuntimeWASM-confinedin-process
Outbound callsonly through the ctx.callRoute gatewaytyped in-process package APIs
Connectorsoutbound kinds, in that project's own partitionfull connector contract, platform lane
App surfacesiframe onlyiframe from any registration; compiled React from any registration when the package ships a prebuilt UI module (see UI while registered from a directory)
Install stepdrop the folder; rescanned in about half a secondneuralis package install while the host runs, approved, then a restart — or register the dependency and rebuild the image

Markdown-only source packages run no code, so the question does not arise for them. If the sandboxed lane can express what you need, use it: it needs no administrator and is reversible by deleting a folder. The native lane (native connectors, in-process routes, the full contract) is a decision somebody with deploy rights makes about you.

The dependency line is the trust act

Nothing else grants native trust — not access.trust in your manifest (read and ignored), not the folder's location, not a git remote. The administrator adding your package to the host's dependencies is the decision, reviewable like any dependency. The line may name a registry version (public or private), a packed tarball or a directory on the deploying machine; every form installs as a real directory in the host's node_modules, under any scope. Registering a directory or tarball runs the runtime's own admission check first, so a package the platform would refuse is refused there. A package that still fails at start (no init, or a collision over a service, an OAuth prefix or a configuration key) is left out alone, and the operator's health view names it.

What the image build expects of a directory

A directory you register is built by the image build, so it has to build there on its own:

  • a build script, and — when you declare app.module — a build:ui script running neuralis-build ui;
  • files[] listing every first-level runtime folder (below);
  • the kernel packages as peers (below), never a dependency;
  • no link: or file: specifier that points outside your directory — the build cannot follow it, and registering refuses it with the specifier named.

A tarball is installed as packed and never rebuilt, so it must carry its dist/ already built.

UI while registered from a directory

The server side (tools, routes, skills, agents, workflows, connectors, MCP) is live once the image carries it. Compiled React ships as a prebuilt UI module, because the workspace imports no package's React source: put the install entry at app/host.tsx, build it with neuralis-build ui and declare app.module (typically { "entry": "dist/app/host.js" }). The image build runs that step for a registered directory; a tarball or registry version ships it prebuilt. The host serves dist/app/ from a content-hashed URL to signed-in members, supplies React and the client library itself (a bundle carrying a copy fails the build), and compiles your utility classes into the workspace stylesheet. Without a module, direct surfaces show "This widget cannot be rendered by this host"; iframe surfaces render from every lane.

The host refuses a module built for another host API version or React major, one whose build record names no React major, or whose entry exports no install<Name>HostComponents function, and the placeholder names the reason; the image build lists the same refusals when it finishes. The placeholder does not mean "not loaded": check the package's diagnostics, where a loaded native package reports loaded and its trust tier.

Kernel packages are peers

Your package's consumer is a Neuralis host, and that host already loads @neuralis/agent-core and @neuralis/package-system in its own process. Declaring either as a dependency installs a second copy, and one contract with two module graphs is a genuinely hard class of bug to diagnose.

Declare them as peers. The image build provides them — your package is built inside the same workspace as the platform's own — so one copy of each is all any package ever sees:

{
  "peerDependencies": {
    "@neuralis/agent-core": ">=0.1.0",
    "@neuralis/package-system": ">=0.1.0"
  }
}

No link: devDependency into a Neuralis checkout beside yours (registering refuses it). With pnpm, autoInstallPeers: false in your own pnpm-workspace.yaml keeps a standalone install from fetching the kernel. The host's dependency line naming your directory or tarball is a local source: it builds into that machine's image only, is never committed or published, and a plain package-manager install of the host must not run while it exists (it would write the path into the lockfile).

Your tsconfig has nothing to extend

Outside a monorepo, inline what a base config gave you. Two settings are load-bearing: skipLibCheck (the kernel ships several hundred .d.ts files) and declaration (required by composite: true). A config that covers only src/** should say so.

What you must ship

files[] decides what actually leaves your repository — for a publish and for a live swap alike. List every first-level runtime folder: dist, tools, workflows, skills, rules, instructions, agents, docs, team, app, and hooks.json if you have one. Omitting one is a quiet failure: it works locally and ships empty.

Private development notes belong in a root-level Markdown file NOT in files[]; in rules/ they would ship and spend every agent's always-on prompt budget.

Four separate acts, and only one of them makes it load

These are routinely confused, and the confusion always sounds the same: it is committed and pushed, why is it not loaded?

  1. Push to a git remote — source backup and review. Changes nothing about any deployment.
  2. Install it into the host — the administrator's trust act: neuralis package install and an approval while the host runs, applied at its restart; or register the dependency and rebuild the image. This is what makes the package discovered and loaded in-process as a native package (manifest trust value native).
  3. Mount the directory for live development — the container binds your directory over the installed copy, so an edit needs a build in your directory and a restart, not an image rebuild. Plumbing; without step 2 the package is still invisible.
  4. Publish to a registry — a separate decision with its own audience and its own review.

Steps 2 and 3 are operator commands and belong to the deployment's own runbook. Steps 1 and 4 are yours, and they are not the same act: a private git remote is not a publication.

Run your gates where you installed your dependencies

  • Your directory's own node_modules is not what runs. A mounted directory resolves the kernel and React from the host's installation (its own node_modules is masked); a standalone checkout has no kernel unless something there installs one.
  • Host-installed node_modules carry host-built native bindings, which a container of another platform or libc cannot load.

Run the gates where you installed the dependencies, and never report a suite green in an environment you did not run it in.

On this page