# Building your own native package (https://docs.neuralisapp.com/package-system/external-native)

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 [#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](#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](https://docs.neuralisapp.com/package-system/source-packages.md) 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 [#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 [#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 [#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`](https://docs.neuralisapp.com/package-system/wasm-build.md) and declare
[`app.module`](https://docs.neuralisapp.com/package-system/app-surfaces.md) (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 [#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:

```json
{
  "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 [#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 [#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 [#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 [#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.

## Related [#related]

- [The directory contract](https://docs.neuralisapp.com/package-system/directory-contract.md) — what a package folder may contain
- [The manifest](https://docs.neuralisapp.com/package-system/manifest.md) — every field, including `files[]`
- [Features and access](https://docs.neuralisapp.com/package-system/features.md) — how your capability is gated
- [WASM build](https://docs.neuralisapp.com/package-system/wasm-build.md) — the sandboxed lane's build
- [Marketplace](https://docs.neuralisapp.com/package-system/marketplace.md) — publishing, when you get there
