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 lane | Native lane | |
|---|---|---|
| How it arrives | a folder in the project's _packages/, or a mounted directory the project picks up | the deploying administrator registers it as a dependency of the host |
| Who can do it | anyone who can write to the project | only whoever controls the deploy configuration |
| Trust tier | untrusted (an admin may elevate to trusted; never to native) | native, assigned by the host |
| Runtime | WASM-confined | in-process |
| Outbound calls | only through the ctx.callRoute gateway | typed in-process package APIs |
| Connectors | outbound kinds, in that project's own partition | full connector contract, platform lane |
| App surfaces | iframe only | iframe from any registration; compiled React from any registration when the package ships a prebuilt UI module (see UI while registered from a directory) |
| Install step | drop the folder; rescanned in about half a second | neuralis 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
buildscript, and — when you declareapp.module— abuild:uiscript runningneuralis-build ui; files[]listing every first-level runtime folder (below);- the kernel packages as peers (below), never a dependency;
- no
link:orfile: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?
- Push to a git remote — source backup and review. Changes nothing about any deployment.
- Install it into the host — the administrator's trust act:
neuralis package installand 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 valuenative). - 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.
- 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_modulesis not what runs. A mounted directory resolves the kernel and React from the host's installation (its ownnode_modulesis masked); a standalone checkout has no kernel unless something there installs one. - Host-installed
node_modulescarry 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.
Related
- The directory contract — what a package folder may contain
- The manifest — every field, including
files[] - Features and access — how your capability is gated
- WASM build — the sandboxed lane's build
- Marketplace — publishing, when you get there